Hercules Windows Build Instructions

(Visual Studio 2008)


Introduction


This document provides instructions on how to manually build the Windows "MSVC" version of SDL Hercules 4.x Hyperion using Visual Studio 2008. For the Visual Studio 2015 or greater instructions, click here.

To manually 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 few simple minor things to finish setting up your build environment:


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!


Summary of Steps Involved


The overall setup of your build environment is very simple, consisting of four steps, with only the first step being required and the other three steps being optional but recommended:

  1. (required)  Download and install Visual C++ 2008 Express (see links listed in the Introduction section above).


  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.


Detailed Instructions


1. Download and Install Visual Studio


Download both the Visual Studio 2008 Express Edition and Microsoft Visual Studio 2008 Service Pack 1 .iso files using the links at the beginning of this page, and install each of them in turn. The install takes quite a while to finish, so get yourself a cup of coffee while you wait.


2. Setting up ZLIB Support


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

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.


3. Setting up BZIP2 Support


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.

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.


4. Setting up PCRE Support


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

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.

Building Hercules using the Visual Studio IDE


Once you have installed Microsoft's Visual C++ 2008 Express Edition and have finished setting up your build environment, you can then easily build Hercules via the provided Visual Studio 9.0 solution and project files included as part of the Hercules source-code distribution.

Simply open the provided "Hercules_VS2008.sln" Solution file in Visual Studio, select your desired Solution and Platform build configuration from the dropdown list boxes on your toolbar at the top of the screen (Debug/Win32, Release/Win32, Debug/x64, or Release/x64) and then click the "Rebuild Solution" button!  (Or select the equivalent "Rebuild Solution" command from the "Build" menu)

That's it!

It truly is that simple!    :)

When you click the "Rebuild Solution" button, Visual Studio simply invokes Hercules's "makefile.bat" script, which in turn invokes the 'nmake' command for the make file called "makefile.msvc" (after calling a few helper batch scripts to first define the Visual Studio build environment). All of the actual building (compiling and linking) is controlled by the "makefile.msvc" make file (which, as explained, is invoked automatically by Visual Studio when you click the "Rebuild Solution" button).

Building Hercules via the Command Prompt

If you wish to build Hercules via the command-line instead, simply use the provided "makefile.bat" batch file included as part of the source code distribution. Enter the command "makefile.bat /?" for help information regarding the various required batch file parameters.