(for the original Visual Studio 2008 instructions, click here)

Hercules Windows Build Instructions

(Visual Studio 2015 or greater)


Introduction


This document provides instructions on how to build the Windows "MSVC" version of SDL Hercules 4.x Hyperion.

To build the Windows MSVC version of Hercules you need to first download and install Microsoft's free Visual Studio 2017 Community Edition product followed by a few additional very important things:


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 five steps, with only the first two steps being required and the other three steps being optional but recommended:

  1. (required)  Download and install Visual Studio 2017.


  2. (required)  Define the "INCLUDE" and "VS150COMNTOOLS" environment variables, and fix Visual Studio's "Property Sheets".


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


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


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




1. Download and Install Visual Studio


Click the download button for the "Community" edition from the Visual Studio download web page using the above link to download a small installer stub. Run the installer and select which components you wish to install, and then let the installer install your selected components.

The install takes quite a while to finish, so get yourself a cup of coffee while you wait.

IMPORTANT!

You must select the "Windows XP Support for C++" option!






Once Visual Studio is installed, then you only need to do two other important things: You need to manually define some very important environment variables and then fix Visual Studio's "Property Sheets" to add the INCLUDE directories (where the "win32.mak" file lives). This is explained in the next step.



2. Define Environment Variables and Fix Property Sheets


The first environment variable you need to define is the "INCLUDE" environment variable which defines an additional list of compiler search directories. You must add the directory where the "win32.mak" file lives to this list. (The "Windows XP support" install option is what installed the "win32.mak" file for us.) This directory varies depending on where you installed Visual Studio of course, but for most people it will be "C:\Program Files (x86)\Microsoft SDKs\Windows\v7.1A\Include".



The second environment variable you need to define is the "VSnnnCOMNTOOLS" variable, where 'nnn' is the internal version number of Visual Studio ('140' for Visual Studio 2015 and '150' for Visual Studio 2017). In earlier versions of Visual Studio the installer automatically defined this environment variable for you, but in later versions of Visual Studio the installer no longer does this, so you need to do it yourself.

The environment variable is called "VS140COMNTOOLS" for VS2015 and "VS150COMNTOOLS" for VS2017. It defines the Visual Studio "...\Common7\Tools" directory, which allows Hercules to locate the necessary batch files to initialize Visual Studio's build environment.

For most people this directory will be: "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\Tools".



The last thing we need to fix is Visual Studio's "Property Sheets" (one for 32-bit and another for 64-bit), which tells Visual Studio what value to initialize the "INCLUDE" environment variable to. For some reason I am unable to fathom it purposely ignores whatever "INCLUDE environment variable you already have defined, and completely replaces it with its own list of directories, so we need to fix things so that it doesn't do that. (The "INCLUDE" environment variable we defined earlier above is very important in that it defines the location where the "win32.mak" file lives, which Hercules needs to initialize its build settings.)

Visual Studio's Property Sheets live in the C:\Users\<username>\AppData\Local\Microsoft\MSBuild\v4.0 directory. The two Property Sheets that we need to modify are the "Microsoft.Cpp.Win32.user.props" and "Microsoft.Cpp.x64.user.props" sheets. Edit both files in Notepad and replace line 6 ("<PropertyGroup />") with the following three lines:
        <PropertyGroup>
          <IncludePath>$(VC_IncludePath);$(WindowsSDK_IncludePath);$(INCLUDE);</IncludePath>
        </PropertyGroup>
As you can see all we are doing is appending the "INCLUDE" directory to the end of Visual Studio's default INCLUDE directories. This allows Hercules to find the all important "win32.mak" file.

Save your changes and you are done. Once you have Visual Studio installed and have defined the two environment variables and fixed the Property Sheets, then you are finished with the Visual Studio installation portion of the setup.



Special Instructions for Windows 10: Before your newly defined environment variables can take effect, you will need to first logoff and then log back on again! Earlier versions of Windows are smart enough to dynamically update the environment immediately after being modified, but Windows 10 is different! You have to logoff and logon again (or reboot) before the new environment variables will take effect!



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



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



5. 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 Studio 2015 or 2017 Community Edition and have finished setting up your build environment, you can then easily build Hercules via the provided Visual Studio solution and project files included as part of the Hercules source-code distribution.

Simply open the provided "Hercules_VS2015.sln" or "Hercules_VS2017.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.