QUICK START: Build Hercules Using CMake

Why should I use CMake to build Hercules?

CMake Build Scripts Development Status

Changes From the GNU Autotools Build

Current Limitations of the CMake Scripts

What To Do When it Fails


To build Hercules on your computer using CMake, you need the following software installed:

Do the following to build Hercules using CMake on GNU/Linux or BSD open source systems or on Solaris.

  1. Clone or update your local clone of Hyperion, as needed.
  2. Create a build directory and make that directory your current working directory. You can create the build directory anywhere you wish, so long as the directory is writable.
  3. Configure: cmake <hyperion-source-dir>
  4. Build: cmake --build .
  5. Run Tests: ctest
  6. Install: cmake -P cmake_install.cmake      (if you wish)

That's it. SoftFloat-3a will be cloned 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.

Helpful pages:




--enable-xxx is replaced with -DXXX=yyy

XXX is the configure.ac -enable option in caps.

For example --enable-ipv6, as a configure.ac command line option, would be specified on the CMake command line as -DIPV6=YES; code>--disable-ipv6 as -DIPV6=NO. The -D prefix identifies a CMake command line option, and what follows it is made available to CMake in much the same way that -D is used by a c compiler.

So these two command lines have the same effect on the Hercules build:

Autotools:       configure --disable-largefile
CMake: cmake -DLARGEFILE=NO

All command line options may be specified as environment variables. Omit the -D when setting an environment variable. The following two lines set the same option for the CMake build:

export SYNCIO=NO
cmake -DSYNCIO=NO

--help is replaced with -DHELP=YES

To see all supported options, use:

cmake <source-dir> -DHELP=YES

If you use -DHELP=YES, no build files are created.

-DADD-CFLAGS

If you need to set compiler options or define macros that are passed directly to the c compiler, use -DADD-CFLAGS="<flags> " where <flags> is replaced with the string of options and macros. For example:

cmake <source-dir> -DADD-CFLAGS="-DNO_ASM_BYTESWAP"

Compiler flags passed via -DADD-CFLAGS="" are appended to the flags set up by CMake, which gives the builder the opportunity to turn off things CMake may have turned on. The default is a null string, which adds no additional c flags.

See the Alphabetical List of CMake Hercules Build Command-Line Options for more information about Hercules-specific options that can control the build when using CMake.

See Standard CMake Build Options for more information about general CMake options that can be useful when building Hercules.

-DEXTPKG_DIR=<path>

Defines an absolute or relative path of the top level directory to be used for any external package that will be built by the Hercules build. If a relative path, it is relative to the Hercules build directory. If the path does not exist, it is created. The relative directory extpkg/ is used as a default.

See Controlling the Automatic Build of External Packages for more information about -DEXTPKG_DIR= and controlling the building of external packages.


As of this writing, the Ninja build tool cannot be used to build Hercules-390 on FreeBSD.

Ninja on FreeBSD is unable to resolve the dependency of Hercules on the SoftFloat-3a For Hercules static library. Specific coding, a single option, is required in the CMake script to use static libraries created by external projects, and this specific coding works on GNU/Linux target systems. It is not clear whether this is a Ninja issue, a CMake issue, or an issue in the CMake scripts used to build Hercules-390. Further investigation is needed.

In the meantime, use the CMake generator "UNIX Makefiles" when building Hercules-390 on FreeBSD.

As of this writing, the runtest.rexx command, used to run tests when using CMake to build Hercules-390, fails when run on Windows Subsystem for Linux (WSL) using Regina Rexx. Regina Rexx is the only REXX interpreter included in the WSL repositories, just as it is in native Ubuntu repositories.

The Rexx Utilities package included with Regina Rexx is unable to identify directories in the WSL file system. The runtest.rexx command uses the Rexx Utilities package to check the validity of directory names included in command line arguments provided to runtest.rexx. Oddly, the Regina Rexx Utilities package has no difficulty returning a valid list of files in a directory of the WSL file system.

To use make test on WSL, you will need to build Open Object Rexx (ooRexx) from source. The current stable production version of ooRexx has been tested.

The issue previously noted on this page regarding the use of Open Object Rexx 4.2.0 and Hercules has been addressed in commit cd05efa. CMake may be used to build Hercules integrated with Open Object Rexx without error.

The current release of Open Object Rexx, 4.2.0, fails when integrated with Hercules built using CMake on Leap 42.2 and Ubuntu 16.04. The failure has been reproduced using a simple c program that dynamically loads the shared ooRexx libraries and attempts to run a sample REXX script script based on the example on page 376-377 of the Hercules User Reference.

Open Object Rexx integrates without issue to Hercules when built with GNU Autotools. The ooRexx 5.0.0 beta as of August 2017 can be used to run the simple c program without error. The beta version operates without issue when integrated with Hercules build using CMake.

One might speculate that ooRexx 4.2.0 has an issue when called dynamically from programs that are not built to use libtool. Further research would be needed to verify this, specifically building the small c program using libtool.

The alternatives for this issue are:


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 © 2017 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.