QUICK START: Build Hercules for Windows Using CMake

Why should I use CMake to build Hercules for Windows?

Hercules Windows Build Development Status

Changes From the makefile.bat Build

Current Limitations of the CMake Build

What To Do When it Fails


  1. Open a Visual Studio x64 Native Tools command prompt (Replace x64 with x86 for 32-bit systems)
  2. If you have previously used the old makefile.bat build and used environment variables to point to the directories containing the BZlib2, PCRE, and Zlib packages, unset those variables:

    bzlib_dir pcre_dir zlib_dir

  3. Download: git clone --depth 1 https://github.com/hercules-390/hyperion

    Omit --depth 1 if you wish to review Hyperion change history. The change history requires about 1.75GB of additional disk space.

  4. Create a build directory anywhere you wish, so long as the directory is writable, and change to that directory.
  5. Configure: cmake <hyperion-source-dir> -G "<generator-name>"

    Choose the values for -G "<generator-name>" using the following table. Be sure to include the quotes. NMake and JOM build either a 32-bit or a 64-bit Hercules based on the command prompt being used. The entries for Visual Studio apply to both command line builds and builds using the Visual Studio IDE.

    System type and build tool <generator-name>
    64-bit, Visual Studio 2017 -G "Visual Studio 15 2017 Win64"
    32-bit, Visual Studio 2017 -G "Visual Studio 15 2017"
    64-bit, Visual Studio 2015 -G "Visual Studio 14 2015 Win64"
    32-bit, Visual Studio 2015 -G "Visual Studio 14 2015"
    NMake (command line) -G "NMake Makefiles"
    JOM (command line) -G "NMake Makefiles JOM"

    Running cmake --help from the command prompt will return a complete list of CMake options including the names of every generator available within CMake.

  6. Build: cmake --build . --config release
  7. Test: ctest -C release

That's it. BZip2, PCRE, SoftFloat-3a, and Zlib will be cloned from the Hercules-390 repository and built inside the Hercules build directory, and Hercules will be built.

Should you experience difficulties using CMake to build Hercules please follow the guidance provided in What To Do When it Fails and use the Installation Using Legacy Tools below to build Hercules.

Begin by following steps 1-5 above. Be sure you select a <generator name> that corresponds to the version of Visual Studio you plan to use. Note that you cannot use the command line generators with Visual Studio.

  1. Open the Visual Studio application
  2. Open the solution created by the CMake configure step: File, Open, Project/Solution. Navigate to the build directory and open Hercules.sln.

    3. Note: If you see files named Hercules_VS*.sln, check to make sure you did not navigate to the source directory by mischance.

  3. Visual Studio by default offers the alphabetically first configuration, Debug. Use the drop-down on the line below the menu bar to change this to Release.
  4. Using the menu bar, build the solution: Build, Build Solution.
  5. When the build has completed, you may run the Hercules tests by scrolling to the project RUN_TESTS in the Solucion Explorer on the right-hand side of the Visual Studio application window, right-mouse clicking on it, and selecting Build.

Hercules may be installed using a command prompt or using the Visual Studio IDE. The command prompt may be but does not need to be a Visual Studio command prompt. If you wish to install Hercules in a system location, including the default location of C:\Program Files\Hercules, you should use a standard command prompt with administrative privileges.

The CMake configure option -DCMAKE_INSTALL_PREFIX can be used to change the default installation directory. It is recommended to install Hercules in a separate subdirectory when installing in Windows.

While it is possible to start Visual Studio with administrative privileges and use it to install, the command prompt is the recommended approach.

Installing Hercules
  1. Open a command prompt. If you are installing to a system location, open a command prompt with administrative privileges.
  2. Navigate to the build directory.
  3. Issue the following command:

    cmake -P cmake_install.cmake

    If you wish to install Hercules in a directory other than the one that was used in the CMake configure step, say, for example %userprofile%\hercules, you can override that directory with the following form of the install command:

    cmake -DCMAKE_INSTALL_PREFIX="%userprofile%\hercules" -P cmake_install.cmake

Uninstalling Hercules

Uninstallation can be easily performed by deleting the installation directory. All Hercules components and external packages are by default installed in a separate directory in C:\Program Files.

If you have installed Hercules in a subdirectory that contains other applications, files, or data, you can use the following steps to remove just the Hercules files.

This procedure removes Hercules file by file from its last installed location. It uses a manifest of full path names that is re-created in the build directory on each install of Hercules. So if you install to the wrong location and then install to the right location, this procedure will remove Hercules from the right location.

  1. Open a command prompt. If you previously installed Hercules to a system location, open a command prompt with administrative privileges.
  2. Navigate to the build directory.
  3. Issue the following command:

    cmake -P cmake_uninstall.cmake




Before the CMake scripts, Hercules was built using makefile.bat. The command makefile.bat was used whether one built from a command prompt or using the Visual Studio IDE. Internally, makefile.bat used NMake, an older Microsoft build tool, and required win32.mak.

For comparison purposes, here is a synopsis of the makefile.bat command: 

makefile.bat  {build-type}  {makefile-name}  {num-cpu-engines}  ^
              [-help]                                           ^
              [-asm]                                            ^
              [-title "custom build title"]                     ^
              [-hqa {directory}]                                ^
              [-a |clean]                                       ^
              [{nmake-option}]

makefile.bat Option CMake Configure Step Option Comments
-help -DHELP=YES Neither makefile.bat nor CMake take any action to build Hercules after displaying command help. 
{build-type} -DCMAKE_BUILD_TYPE= For CMake, only specifies the build type, not the bitness, 32 or 64, of the built Hercules.  (The bitness of the command prompt used to run CMake determines bitness,

May be "RELEASE" or "DEBUG"
{makefile-name} Not required CMake always uses file CMakeLists.txt in the source file as the build script.
{num-cpu-engines} -DMULTI-CPU=<nn> If ommitted, support for the Windows maximum of 64 CPUs is generated by CMake. 

It is not clear what the makefile.bat default was when doing a command prompt build.  When using makefile.bat within the Visual Studio IDE, 32 and 64 CPUs were supported for 32- and 64-bit systems respectively. 
-asm -DASSEMBLY_LISTINGS=YES  
-title "text" -DCUSTOM="text"
-hqa {directory} -DHQA_DIR="<directory>"  
-a | clean --clean-first Note: This option is used on the CMake build command, step six in the command prompt build instructions above, not the CMake configure command. 

The CMake build for Hercules does not support "rebuild all" without also cleaning the build directory. 
{nmake-option} --     {nmake-option} Note: This option is used on the CMake build command, step six in the command prompt build instructions above, not the CMake configure command. 

To pass options to the build tool, code all CMake build options followed by two hyphens, then code the build tool options. 

For example, to enable multiple CPU builds using MSBuild, use:

cmake --build . --config release -- /m:4

To enable multiple CPU builds using JOM, use:

cmake --build . --config release -- -j 8

When building Hercules using CMake on Windows, the external packages BZip2, PCRE, and Zlib will normally be built at the same time and in the Hercules build directory from github repositories that are part of the Hercules-390 project. DLLs for these applications will be installed as part of Hercules in the Hercules installation directory.

Older pre-built versions of these external packages cannot be used when building Hercules on Windows using CMake. This applies to versions of these packages built from other sources or libraries installed from Zip archives found in sundry locations on the web (including the binaries included in Hercules 4.0 Release Candidate 0 ).

The Hercules-390 repositories for the BZip2, PCRE, and Zlib cannot be used to build packages for the makefile.bat build because the directory structures differ from that required for makefile.bat.

The sources for these packages in the Hercules-390 project are at the latest release, incorporate corrections and security updates not found in binaries available in other locations, and are otherwise unmodified from the originals. They are used subject to the terms of their original licenses, which are included in the repositories.

For additional information about the Hercules-specific builds for these packages, please see the repositories for the packages at:

Three environment variables are used by the makefile.bat build and by the CMake build for Hercules on Windows that creates a compatibility issue. The three environment variables are:

Note that Windows environment variables are case-insensitive.

Both the makefile.bat and CMake builds for Hercules allows these variables to point to directories containing the respective packages. But because CMake requires a different directory layout from that used by makefile.bat, one cannot use the same directory for both makefile.bat and CMake builds.

If makefile.bat finds these variables un-set, it looks for the BZip2, PCRE, and Zlib packages in a "winbuild" directory tree at the same level as the Hyperion source directory. If makefile.bat does not find the packages in that default location, the capabilities avaiable in the packages are excluded from Hercules.

If the CMake build for Hercules finds these variables un-set, it clones each of the three packages from repositories in the Hercules-390 project, builds the packages in a subdirectory of the Hercules build tree, and uses those the newly-built packages when building Hercules.

The recommendation is to un-set the variables, and you will find this recommendation included in the QUICK START section above.

If you wish to preserve the ability to build Hercules using makefiles.bat, move the directories for the legacy versions of BZip2, PCRE, and Zlib into a winbuild directory at the same level as the Hercules-390 source directory. Alternatively, you may install all three packages in the needed winbuild structure using the Windows Support Files link (downloads an exe) included with Hercules 4.0 Release Candidate 0.

The build tree created by a Hercules build using CMake is substantially different from that created by the makefiles.bat build.

The makefile.bat build creates a set of five or six subdirectories in the source tree, with one set created for 32-bit Hercules and a second set for 64-bit Hercules. Each directory holds one type of build result: generated include files, object files, linkage editor maps, executables and DLLs, and debugging databases (program databases, or PDB files) for executable shared libraries. and optionally assembly listings. A single consolidated compilation program database (PDB) is created in the object directory.

Note: the single compilation program database is only possible because makefile.bat only allows for single-threaded compilations.

When CMake is used to create the build scripts for Hercules, a subdirectory is created for each executable and DLL that will be built. All object modules, assembler listings, and source program databases are created in this subdirectory. If Visual Studio or MSBuild is used to build Hercules, then these components are stored in a Release or Debug subdirectory. Executables, DLLs, linkage maps, linkage editor program databases, DLL import libraries, and export files (.exp) are created in the build directory (Release or Debug subdirectory if using Visual Studio or MSBuild).

Hercules has had a Visual Studio "solution" for Hercules since a native Windows build was first developed in the late 2000's. This solution included a single project and enabled two things:

  1. Source file editing using Visual Studio
  2. Execution of the makefile.bat build script

All source files were children of the single project. There is no connection between the source files, the header files they require, or the executables and DLLs that they end up creating.

When CMake is used to configure and build Hercules, it creates a separate Visual Studio solution in the build directory. This solution includes one project per executable, DLL (shared library), or external package. Additional projects are created to run tests (RUN_TESTS) and to ensure that if the CMake scripts change, they are re-run before Hercules is built.

This solution can be used to build Hercules using the Visual Studio application or using a Visual Studio command prompt with MSBuild. It can also be used to edit files in the source directory.



Please create a github issue in Hercules-390/hyperion. The following information will be needed and can be posted to the issue in a tarball:


This web page Copyright © 2018 by Stephen R. Orso.

This work is licensed under the Creative Commons Attribution- ShareAlike 4.0 International License.

To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.