
HOW TO RUN HYPERMAIL ON WIN32 WITH CYGWIN

Getting cygwin:

        * Go to http://sourceware.cygnus.com/cygwin/ (I'll call this
          the "cygwin home").

        * Click "Download Sites" in the box on the left.

        * Choose a download site close to you.

        * When you click on a link on that page, you'll always be
          taken to a directory.  Click on "latest" to go to the
          directory containing the latest release.

        * There are several packages there.  I recommend getting
          "full.exe".  This is the package that has everything
          (compiler, shell tools, etc.)

Installing cygwin

        * While you *could* simply double click on full.exe, I
          recommend that you read the documentation first.

        * Go to the Cygwin home and click "Documentation" in the
          box on the left.  Then click on Cygwin User's Guide.

        * Read the documentation.  The more you read, the happier
          you'll be.

        * Double click on full.exe and install cygwin.

        * In the current version, you need to do a few things with
          the shortcut that's created in

                C:\Windows\Start Menu\Programs\Cygnus Solutions

          before you can fire up the shell.

          Using Windows Explorer, go to that folder and right
          mouse on Cygwin B20.  Select "Properties".  You'll
          probably want to make the following changes:

                * On the "Program" tab, check "Close on exit"

                * On the "Memory" tab set "Initial Environment"
                  to some high number (e.g., 4096).  This avoids
                  a bug in Windows' DOS shell where auto
                  allocating memory fails.

                * On the "Misc" tab, uncheck "Fast Pasting".
                  This will let you use copy and paste to paste
                  text into the bash shell.

                * On the "Screen" tab, select Initial size: 50 lines.
                  This will give you as big a window as you can get.
 
                * On the "Font" tab, select TT 8 x 16 to start with.
                  This gives you full-sized characters for the window.

        * Double-click on Cygwin B20 or use the Start menu to bring
          up the shell.

        * You'll get a warning message that bash can't find the
          /tmp directory.  Fix that by typing:

                mkdir /tmp /bin /usr /etc
         
          This is in the instructions you should have read.

        * In bash, type:

                ln -s /cygnus/cygwin~1/h-i586~1/bin/sh.exe /bin/sh.exe

          (If you've installed cygwin somewhere other than the default
          location, you'll have to make the left-hand side of the link
          expression something else).

          This creates a soft link that's recognizeable by bash.  If
          you use Explorer to make a shortcut, what you'll get in /bin
          is a file called "she.exe.lnk" which unfortunately bash
          doesn't recognize as executable.

          You need to make the link (or a copy of sh.exe) into the
          directory that bash recognizes as /bin because many scripts
          (e.g., configure, many makefiles) will call /bin/sh.

          This is also in the instructions you should have read.

        * NOTE: if you don't like the idea of creating all those
          directories in the C: root, you absolutely can use links
          and mount to put them somewhere else.  On my system at
          home, I've got /usr/bin pointed to the Cygnus bin
          directory and /usr/local pointed somewhere entirely
          different, and I've got /bin pointing to /usr/bin.  This
          falls under advanced customization, and I don't recommend
          it unless you have a lot of time to play around with the
          mount command, which is somewhat different in cygwin (both
          from Unix and often from their own documentation).

        * To exit from bash type

                exit

          You should *not* just click the "X" box in the top right-hand
          corner of the window.  bash can leave your system in a
          blue-screen-of-death state if you don't exit properly.
          bash is a lot better than it used to be about this, but it's
          still dangerous to just kill off bash.

Testing the Compiler:
 
        * Create a "hello.c" file somewhere.  Type the usual into that
          file:

                #include <stdio.h>
                main()
                {
                    printf("Hello, world!\n");
                }

        * In your bash shell, go to the folder where you've put
          hello.c (use cd) and type:

                gcc hello.c

        * When the code compiles and links successfully (you can read
          what it's doing on the caption of the bash window), type

                ./a.exe

          and you should get the familiar "Hello, world!".

        * Create a file called "hello.cpp".  Type the usual into that
          file:

                #include <iostream>
                int main()
                {
                  cout << "Hello, world!" << endl;
                  return 0;
                }

          Incidentally, you may #include <iostream> or <iostream.h>

        * Type in

                g++ -o hello hello.cpp

        * Execute hello.exe:

                ./hello

        * Right mouse on hello.exe in Explorer and see if one of the
          options on that menu is Quick View.  If not, you should think
          about installing it.  While you could just take my word for
          some of the assertions I'll be making about what you'll see
          using Quick View, if you're doing any software development
          on your machine, you'll probably need it eventually.  Here's
          how to install it:

                * Open the control panel

                * Select Add/Remove Programs

                * Go to the Windows Setup tab
 
                * Select Accessories, and press the "Details..." button

                * Look for Quick View, check it, and insert your Windows
                  9X CD-ROM when prompted.

        * In exporer, right mouse on a.exe and select Quick View.
          Notice that the executable requires cygwin1.dll.  Do the
          same for hello.exe.

        * Recompile the first file, "hello.c", as follows:

                gcc -mno-cygwin hello.c

        * Now use Quick View and notice that the executable requires
          crtdll.dll and kernel32.dll, but not cygwin1.dll.

        * Now recompile the second file, "hello.cpp", the same way:

                g++ -mno-cygwin -o hello hello.cpp

          Disaster!  A huge number of error messages.

          To solve it, go out and get

               ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin/egcs-1.1.2/egcs-1.1.2-mingw-extra.tar.gz

          and extract it to:

               C:\usr\mingw32

          In this tarball, libm.a seems to be a soft link which got
          copied by mistake into the distribution.  Either extract
          everything but libm.a or extract everything and delete libm.a
          from C:\usr\mingw32\lib

          Now try again, using the following command line arguments:

          g++ -mno-cygwin -I/usr/mingw32/include -L/usr/mingw32/lib hello.cpp

          This time it should link and run correctly.
          
          The whole issue is explained in:
          http://www.xraylith.wisc.edu/~khan/software/gnu-win32/ -- click
          on the article "-mno-cygwin"

        * Now test gcc on a Windows program.  Copy the following file
          http://www.geocities.com/Tokyo/Towers/6162/win32/simple.txt
          to the directory you're working in and rename it to simple.c

        * Compile it as follows:

                gcc -mwindows simple.c  or
                gcc -mno-cygwin -mwindows simple.c

        * Execute it from your shell:

                ./a.exe

        * If you compiled it -mno-cygwin, you can execute it from
          Explorer by double-clicking on the icon.  If you compiled it
          without that option, you'll need to make a copy of cygwin1.dll
          somewhere in your executable path before you can execute it
          by double-clicking on the icon.

        * A somewhat more complex Win32 program is at
          http://www.geocities.com/Tokyo/Towers/6162/win32/test.txt
          Rename it to test.c and compile as you did simple.c
          
Extracting hypermail:

        * Save the tarball in a local folder.  If you're using Netscape,
          don't forget to make the dot that Netscape turned into an
          underscore a dot again.  That is, the file should be named
          hypermail-2b25.tar.gz, not hypermail-2b25_tar.gz.

        * In the bash shell extract it into some folder using tar:

                tar zxvf hypermail-2b25.tar.gz

        * Alternately, using WinZip, open the file and extract it into
          some folder.  Make sure that "Use folder names" is checked on
          the Extract menu.

          In our example, we'll assume you extracted the hypermail
          source into C:\aawork\hypermail-2b25 (in DOS shell notation)
          or //c/aawork/hypermail-2b25 (in bash shell notation).


Configuring and compiling hypermail:

        * In bash, go to the directory where you extracted the files
          in the tarball.  e.g.,

                cd //c/aawork/hypermail-2b25
         
        * In bash, type

                sh ./configure
         
          This should give you a lot of messages and complete
          successfully.  If you've used configure on a Unix system,
          the only surprise is how familiar the outputs look.

        * In bash, type

                make
 
          This should also complete successfully, with one warning
          message:

                mail.c: In function `lookupnumaddr':
                mail.c:40: warning: return discards `const' from
                  pointer target type

        * In bash, type

                mkdir /usr/local /usr/local/bin /usr/local/man
                mkdir /usr/local/man/man1 /usr/local/man/man4
         
          This creates the directories your programs and documents
          will reside in.  Yes, I know install is supposed to do
          a mkdir if it can't find those files, but that seems to
          be broken.

        * In bash, type

                make install

          If you've changed all the makefiles correctly, you should
          see the following directory contents:

                BASH.EXE-2.02$ ls -F /usr/local/bin
                hmail.exe*       na-mail.exe*     nu-rdmsg.exe*
                hrdmsg.exe*      na-rdmsg.exe*    wu-rdmsg.exe*
                hypermail.exe*   nu-mail.exe*     wuftpdmail.exe*

                BASH.EXE-2.02$ ls -F /htdocs
                customizing.html  hr.yellow.gif     hypermail.html
                hmrc.html         hypermail.gif

                BASH.EXE-2.02$ ls -RF /usr/local/man
                man1/  man4/
 
                /usr/local/man/man1:
                hypermail.1

                /usr/local/man/man4:
                hmrc.4

Testing Hypermail:

        * Create an /etc/passwd file that has one entry:

                yourlogin:x:500:10:Your Name://c/Bob:/usr/bin/bash

          Note that I define HOME in C:\autoexec.bat:

                SET HOME=C:\Bob

          so vim doesn't end up writing its scratch files everywhere.
          It *appears* that the routine in file.c uses this entry to
          find $HOME and that no other routine finds $HOME any other
          way.  Still, it probably isn't a bad idea to go ahead and
          define HOME in C:\autoexec.bat and reboot.

          In the line above, the user number "500" is important.  The
          group number "10" probably isn't (I don't have an /etc/group),
          and (obviously) //c/Bob isn't important unless your name is Bob.
          Just make sure the directory exists.

          Incidentally, creating /etc/passwd was the *only* thing I had
          to do to get hypermail to run.  Before I did this, it crashed
          on line 231 of file.c

                    sprintf(tmppath, "%s%s", pp->pw_dir, path + 1);

          because pp was null.

CODE GURUS: You might want to think about checking the return of
getpwuid() and getting $HOME out of the environment if it's NULL.
That would avoid a crash for Win32 users who don't bother to set up
/etc/passwd

        * Copy the example .hmrc file to your home directory:

                cp hmrc.example ~/.hmrc

        * Get an example mbox file.  If you have Netscape Navigator,
          it turns out that in C:\Program Files\Netscape\Users\you\Mail
          all the files that don't have extensions are mbox-style files.
          In the example below, I used "Sent" as a simple test case.

        * Copy the mbox file to some test directory.

        * Go to that directory and create a directory (say, call it foo).

                cd test
                mkdir foo

        * From bash, execute hypermail to build your archive.

                /usr/local/bin/hypermail -m Sent -d foo

        * Admire the results.

                (speaking of admire, included mail files seem to lack the
                 <PRE> and look awful!)

                (I also noticed that a JPEG file that was attached to one
                 of the messages didn't seem to translate properly, though
                 the JPEG header looked good.)  If nobody else runs into
                 this, forget it and chalk it up to a bad file.  Otherwise,
                 you might want to look at Jorgen Hagg's base64 routine,
                 which I got permission to use in foxynews:
                 http://home.hiwaay.net/~crispen/src/#foxynews
                 I'm sure he'd give us permission to use it in hypermail.

Now if you want to know about receiving mail on Win9x/NT and using
hypermail interactively, I've run out of things I know how to do.
Somebody else want to pick up the ball?

