"MSVC" Hercules Build Instructions

This document provides instructions on how to build the "MSVC" version of Hercules.

To build the Windows MSVC version of Hercules you need to first download and install Microsoft's free Visual C++ 2008 Express product and then do just a couple of simple minor things to finish setting it up.

The overall setup process is basically very simple:

Note: once you've setup your build environment, (which you only need to do once and never again) the process of actually building Hercules is extremely simple: just open our pre-provided "Hercules.sln" Solution file and click the 'Rebuild Solution' button!

1. Download and install Visual C++ 2008 Express.

   
   

2. (optional)  Download and "install" the ZLIB package
   1. Download
   2. Unzip somewhere
   3. Define a ZLIB_DIR environment variable pointing to your directory so the Hercules build process can find the needed files.

   
   

3. (optional)  Download and build the BZIP2 package
   1. Download
   2. Unzip somewhere
   3. Define a BZIP2_DIR environment variable pointing to your directory so the Hercules build process can find the needed files.

   
   

4. (optional)  Download and "install" the Perl-Compatible Regular Expressions (PCRE) package
   1. Download
   2. Unzip somewhere
   3. Define a PCRE_DIR environment variable pointing to your directory so the Hercules build process can find the needed files.

   
   

5. (optional)  Download and install your preferred Rexx package.

   The Hercules build process should automatically detect your Rexx installation an build Rexx support into Hercules automatically. Hercules Rexx support is new for version 4.0.

   
   

6. Start Visual C++ 2008 Express, open our pre-provided "Hercules.sln" Solution file and click on the 'Rebuild Solution' button!

   ... OR ...

   If you wish to build via the command-line instead, simply open a Command Prompt window and enter the proper 'makefile' command.

ZLIB is a compression algorithm written by Jean Loup Gailly and Mark Adler and may be used in the Hercules project pursuant to the ZLIB License (a copy of which may be seen at http://www.zlib.net/zlib_license.html).

As a convenience, Fish has created a pre-packaged .zip file containing the necessary header and lib files and a pre-built version of the DLL to satisfy the Hercules build process which may be downloaded from here.

In source form, the Hercules project does not contain any ZLIB source code at all.

In binary form however, the Hercules project may include an unmodified version of the ZLIB runtime DLL in addition to its own distribution binaries.

The 'ZLIB_DIR' environment variable defines the location of where the needed files are for building a version of Hercules that supports ZLIB compression. The makefile used by the Hercules build process tests whether this environment variable is defined or not in order to know whether you wish to build ZLIB compression support into Hercules or not.

If 'ZLIB_DIR' is undefined when you build Herc then it tries looking for it in a predefined default directory. If it doesn't find it then ZLIB support will simply not be generated. Otherwise 'ZLIB_DIR' must point to a valid directory where the ZLIB package is installed.

ZLIB_DIR should contain the path of the ZLIB directory. This means the following file/directory layout is expected:

    $(ZLIB_DIR)

        zlib1.dll
        zlib1.pdb

        include
            zconf.h
            zlib.h

        lib
            zdll.lib

        x64

            zlib1.dll
            zlib1.pdb

            include
                zconf.h
                zlib.h

            lib
                zdll.lib

When building a 64-bit (x64) version of Hercules the above 'x64' subdirectories are automatically searched, so as long as the above directory structure is adhered to then Hercules should build fine.

BZIP2 is a freely available (open-source (BSD-style) license), patent free (as far as the author knows), high-quality data compressor written by Julian R Seward. It typically compresses files to within 10% to 15% of the best available techniques (the PPM family of statistical compressors), whilst being around twice as fast at compression and six times faster at decompression.

As a convenience, Fish has created a pre-packaged .zip file containing the necessary header and lib files and a pre-built version of the DLL to satisfy the Hercules build process which may be downloaded from here.

In source form, the Hercules project does not contain any BZIP2 source code at all.

In binary form however, the Hercules project may include an unmodified version of the BZIP2 runtime DLL in addition to its own distribution binaries.

If 'BZIP2_DIR' is undefined when you build Herc then it tries looking for it in a predefined default directory. If it doesn't find it then BZIP2 support will simply not be generated. Otherwise 'BZIP2_DIR' must point to a valid directory where the BZIP2 package is installed.

BZIP2_DIR should contain the path of the BZIP2 directory. This means the following file/directory layout is expected:

    $(BZIP2_DIR)

        bzlib.h
        libbz2.dll
        libbz2.lib
        libbz2.pdb

        x64
            bzlib.h
            libbz2.dll
            libbz2.lib
            libbz2.pdb

When building a 64-bit (x64) version of Hercules the above 'x64' subdirectories are automatically searched, so as long as the above directory structure is adhered to then Hercules should build fine.

PCRE (Perl-Compatible Regular Expressions) is: "a set of functions that implement regular expression pattern matching using the same syntax and semantics as Perl 5. PCRE has its own native API, as well as a set of wrapper functions that correspond to the POSIX regular expression API. The PCRE library is free, even for building commercial software."

As a convenience, Fish has created a pre-packaged .zip file containing the necessary header and lib files and a pre-built version of the DLL to satisfy the Hercules build process which may be downloaded from here.

In source form, the Hercules project does not contain any PCRE source code at all.

In binary form however, the Hercules project may include an unmodified version of the PCRE runtime DLLs in addition to its own distribution binaries.

NOTE: the Perl-Compatible Regular Expressions library is needed only to support the Hercules Automatic Operator (HAO) Facility. If you do not plan to ever use the Hercules Automatic Operator facility, then you do not need to install PCRE support and may safely skip this step.

If 'PCRE_DIR' is undefined when you build Herc then it tries looking for it in a predefined default directory. If it doesn't find it then regular expression support will simply not be generated. Otherwise 'PCRE_DIR' must point to a valid directory where the PCRE package is installed.

PCRE_DIR should contain the path of the PCRE directory. This means the following file/directory layout is expected:

    $(PCRE_DIR)

        bin
            pcre3.dll
            pcre3.pdb
            pcreposix3.dll
            pcreposix3.pdb

        include
            pcre.h
            pcreposix.h

        lib
            pcre.lib
            pcreposix.lib

        x64
            bin
                pcre3.dll
                pcre3.pdb
                pcreposix3.dll
                pcreposix3.pdb

            include
                pcre.h
                pcreposix.h

            lib
                pcre.lib
                pcreposix.lib

When building a 64-bit (x64) version of Hercules the above 'x64' subdirectories are automatically searched, so as long as the above directory structure is adhered to then Hercules should build fine.

Rexx (Restructured Extended Executor) is an interpreted programming language developed at IBM by Mike Cowlishaw. It is a structured, high-level programming language designed for ease of learning and reading.

The Hercules build process checks to see if the directories created by the installation of the only two supported Rexx packages: Open Object Rexx and Regina Rexx. Of the two packages, the Open Object Rexx package is the receommended package since it is directly managed by the Rexx Language Association (RexxLA).

If either the 'REXX_HOME' or 'REGINA_LANG_DIR' (or both) environment variables are defined (which are the environment variable names that each package automatically defines when it is installed), then support for Rexx will be automatically built into Hercules. Installing both packages causes bimodal support to be generated wherein both packages are then supported, allowing you to choose at runtime which package you wish Hercules to use.

The standard/default Object Rexx installation installs everything into

     \ooRexx

     \ooRexx\api

     C:\Regina

     \Regina

     \Regina\include

Default Visual Studio 9.0 (Visual C++ 2008 Express) solution and project files are included as part of the Hercules source-code distribution.

Simply open the Hercules .sln Solution file, select your desired Solution Configuration and Solution Platform from Visual Studio's drop-down list boxes at the top of the screen (such as "Release|Win32" or "Release|x64") and then either and click your 'Build' or 'Rebuild All' toolbar button or select "Build Solution" or "Rebuild Solution" from Visual Studio's "Build" menu!

That's it!     It truly is that simple!    :)

When you click the Rebuild All button the makefile project simply invokes "makefile.bat" which in turn simply invokes the 'nmake' command for "makefile.msvc" after calling a few key batch files to setup the necessary Visual Studio build environment.

Note: "Release" builds may appear to 'stall' or 'hang' at the point when the following message appears during the build:

   Creating library msvc.dllmod.obj\hengine.lib and object msvc.dllmod.obj\hengine.exp
Generating code

Rather, the optimizer is simply very, very busy applying global optimizations to the Hercules engine code being generated. Depending on the speed of your system the process could take up to a minute or more. If the build does not continue after waiting several minutes, then something might be wrong (but I've personally never seen that happen).

Please also note that in order to build any of the "xxxx-All" configurations you will need to install Fish's "RunJobs" tool since all of the "xxxx-All" configurations are designed to build all of the selected configurations in parallel (which Microsoft unfortunately does not yet support). Under normal circumstances however you should only ever need to build one of the the plain "Release" configurations. Building "xxxx-ALL" configurations is really only for advanced Hercules development and not for ordinary casual building from source.

If you wish to build Hercules via the command-line rather than from the Visual Studio IDE, then simply open a Command Prompt window, navigate to the directory where your Hercules source code is, and enter the command:

  makefile.bat RETAIL-X64 makefile.msvc 32 -a

The same "xxxx-All" caveat mentioned above applies for command-line builds as well (i.e. if you want to build multiple configurations at once then you will need Fish's "RunJobs").

Enter the command   makefile.bat /?   for additional information on building from the command-line.

Starting with version 4.0 of Hercules, the build process now features the ability to override many of Hercules's default build settings without having to modify any of the Hercules header files themselves. On Windows you can also override virtually any of the compiler settings themselves as well.

To do this, simply define an environment variable called 'HQA_DIR' pointing to the directory containing your optional "hqa.h" header file and/or "HQA.msvc" makefile overrides.

Then, within your "hqa.h" override header, simply #define the 'HQA_SCENARIO' macro to one of the values already pre-defined in Hercules's "hqadefs.h" header file or #define your own scenario. The values you define will then override the defaults.

Additionally, on Windows, you can create a 'HQA.msvc' nmake !include file override to modify, for example, the $(cflags) variable to add, remove, or change whatever compiler option you wish.

As a convenience you can also specify the HQA directory on the "makefile.bat" command via the new "-hqa" option instead, rather than have to define an environment variable.

Well, that's pretty much it I guess.   <shrug>

If you have any questions or problems, feel free to ask the   hercules-390 group   for help.     (not me)

Enjoy!   :)