Building Hercules for Windows

This short article is supposed to help you to build Hercules from source code. The main tool we are going to use is the Cygwin Development Kit, which allows us to use the Unix development tools on the Windows platforms. On all Windows platforms? I wouldn't know. Windows 95 is probably out of the question. I know it works nicely on Windows NT 4.0, and on Windows 2000. I strongly believe that it also works on Windows 98, but I haven't tried this. And what about Windows XP? Don't ask me. I don't have Windows XP, and I am not very likely to buy it, either. At least not as long as I can use Windows 2000

Talking about the Cygwin ... This software is constantly changing, sometimes to the better, sometimes to the worse. The build process I am describing nowis based on the version 1.5.4, downloaded on September 20, 2003. If you use an other version, things may work out as well, but also they may not...

Setting up the Cygwin Environment

You need a working Cygwin environment to build and/or run Hercules on a windows platform. Installation of Cygwin is described elsewhere

Getting Hercules Sources

Actually, there are several different places from where you can get source.

The source package from the Hercules distribution site http://www.conmicro.cx/hercules
The daily developer's snapshots/index.html
The source tree from the developer's CVS repository

To obtain the source from the first location, just point your browser to the distribution site and http://www.conmicro.cx/Hercules click on the link for the "source tarball". This file will have a name similar to hercules-3.00.tar.gz . Place the file into the C:\Cygwin\root directory. Change to that directory and enter the command

tar -xvzf hercules-3.00.tar.gz

This will unpack the tar file and create a directory hercules-3.00 in the C:\Cygwin\root directory.

If you want access to a later level of Hercules, you can access the source code aod precompiled binaries from the snapshots directory. Please remember that those snapshots are not release-level quality code, and may or may not work. Actually, they may not even compile!

The Snapshots have filenames like hercules-yyyy-mm-dd.tar.gz and can be expanded into a source directory with

tar -xvzf hercules-yyyy-mm-dd.tar.gz

If you would like to play around with the source as the developers have it right now you need to access the developer's source repository. You can do so with a tool called CVS. You would need to download the full source tree once, and then you would only need to download the modified source modules. I have provided a few scripts that help you doing so. These scripts are available by downloading and executing the file cygherc.exe, which is a self-extracting archive that exapnds into directory C:\Cygwin\root. You may of course change the target directory, but I'll be assuming the default directory in this little article.

Change to the directory C:\Cygwin\root. Run the command file

_hercnew

which will create a new directory hercules and will download the full source tree into that directory. Be patient, this will take some time

At a later time, when some of the source modules have changed in the repository, and you want to just pick up those changed modules, you should run the command file

_hercupd

If you, for whatever reason, have modified one or more of your local source modules, and want to revert back to the original CVS version of the modules, you can run

_hercclean

Both the _hercupd and the _hercclean scripts work either on the full repository (when no argument is given) or on selected modules, whose names you would provide as an argument

_hercupd config.c  config.in

would update the two modules config.c and config.in. Wild cards are also accepted as in

_hercclean cckd*

which would get a clean copy of all cckd modules

Please note the building the binaries from the CVS source is not necessarily a good thing. Nobody guarantees that the binaries are working, it isn't even guaranteed that the whole thing compiles! On the other hand, any enhancement, bug fix, etc will of course be available first in that developer's repository. Just keep in mind the dangers of living at the bleeding edge.

Obtaining the source of previous Hercules Versions

Sometimes you might want to revert back to an earlier version of Hercules. This can be easily done. In the directory C:\Cygwin\root you will find a file called set_rel_tag.

export REL_TAG=rel_3_00
DIRSUFF=${REL_TAG#rel_*}
export DIRSUFF=`echo ${DIRSUFF} | tr '_' '.'`

You need to edit the first line to indicate which major Hercules version.release you want to work on (It is currently set to Version 3.00). The latest stable Hercules release for that level will be accessed then.

After having edited the set_rel_tag file you need to run

_relhercnew

to download the corresponding source. Of course, you need to be connected to the internet first. After you downloaded the source you will need to run

_relhercbuild

to build the binaries. The program

_relhercrem

finally will remove the Hercules binaries again, if you need to do so.

Building Hercules Binaries

Building the Hercules binaries is pretty simple now. The easiest way is to change to the source directory and enter

bash
./configure
make
make install-strip

In most cases this will do the trick. You can also change to the directory C:\Cygwin\root instead and run the script

_hercbuild

This script will do all the required work (like issuing the commands above), and after it has finished, will have placed

The Hercules binaries into C:\Cygwin\usr\local\bin, which is in the path
The Hercules shared libraries into C:\Cygwin\usr\local\lib, which is in the path
The Hercules NLS (National Language Support) files into C:\Cygwin\usr\local\share\locale
The Hercules web server support files into C:\Cygwin\usr\local\share\hercules

Sometimes you would like to have more control, or need more control, therefore the _hercbuild script accepts a few options:


_hercbuild [-c {cputype}] [-t {threadmodel}] [-n]
             !              !                  !
             !              !                  +--- no-ansi, do not
             !              !                       use fancy colours
             !              +---------------------- thread model to use
             !                   threadmodel can be f or fthread (default)
             !                                      p or posix
             +------------------------------------- target cpu type
                                     cputype can be i586 or Pentium or Athlon
                                                    i686 or PentiumPro
                                                    p4 or Pentium4

Which CPU Type?

The script will normally detect the CPU type that is in your machine. Sometimes it guesses incorrectly, and sometimes you might want to create the binaries for another target machine. Then you would use the -c command line option for specifying the CPU type:

i585: Any Pentium class CPU qualifies for this CPU type. If you have an older Pentium based PC, or a PC based on an Athlon K processor, you should choose the i586 column from the download Array
i686: The i686 CPU type include all processors from the Pentium Pro processor onwards. If you have a modern PC this should probably be the column to choose from the download array
p4: The p4 CPU type include all processors from the Pentium 4 Processor onwards. I have tested this version, and it works on my system. If it brings any performance gain, I cannot tell. Try it out yourself. If you run into problems, you can always use the i686 version

Which Thread Model

Hercules is relying heavily on the multithreading facilities provided by the Cygwin environment. There are two different implementation available:

fthread: Fish (aka David B. Trout) has developped an optimized threading model for Hercules running in a Cygwin environment, which obviously is called fish-thread or fthread. You should normally choose the fthread row from the download array.
pthread: The Cygwin system comes with its own posix compliant thread model, called pthread. You should only choose the pthread row from the download array if you have experienced serious problems when using the fthread model

You have even tighter control about what is going to even if you enter the command

configure --help | less

to see which other options you may turn on or off.

When you are working with the developer's source, you will eventually have to rebuild the configure file yourself. First of all you need to check the last line of the file configure.ac. It could be that the last two entries in that line are duplicated as shown here

AC_OUTPUT([Makefile util/Makefile html/Makefile po/Makefile.in po/Makefile intl/Makefile m4/Makefile intl/Makefile m4/Makefile ])

If that is the case, remove the last two entries to make the line look like this:

AC_OUTPUT([Makefile util/Makefile html/Makefile po/Makefile.in po/Makefile intl/Makefile m4/Makefile ])

Then you have two different ways of building the configure script. The first alternative is to change to the source directory and to enter

sh autogen.sh

If after some time the script just seems to have stopped, press the ENTER key once. The autogen script will now rebuild the configure file. Check for any errors in the file autogen.log. Then you can continue as above.

The second alternative is to delete the file configure and then use _hercbuild as explained above. The script will detect the absence of configure and will take the necessary action. Again it might be necessary to press the ENTER key in case the script stops halfway through, and again it is a good idea to check the file asutogen.log for error or status messages

That's all, folks

If I managed to confuse you with these instructions, just drop me a line.

Enjoy your private Hercules mainframe