Building HYPERMAIL on
WIN32 with CYGWIN

Getting cygwin:

• Go to http://sourceware.cygnus.com/cygwin/

• 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-2b30.tar.gz, not hypermail-2b30_tar.gz.

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

  tar zxvf hypermail-2b30.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-2b30 (in DOS shell notation) or //c/aawork/hypermail-2b30 (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-2b30

• 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.

• 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.

  (I 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.