QUICK START: Build Hercules for macOS Using CMake

Why should I use CMake to build Hercules for macOS?

Hercules macOS Build Development Status

What To Do When it Fails


  1. Open a command line application, either Terminal on the Mac or using SSH from a remote computer.
  2. Clone or update your local clone of Hyperion, as needed.
  3. Create a build directory anywhere you wish, so long as the directory is writable, and change to that directory.
  4. 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.

    Build tool <generator-name>
    Xcode IDE -G "Xcode"
    GNU make -G "UNIX Makefiles"
    Ninja -G "Ninja"

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

  5. Build: cmake --build . --config Release

    The --config Release is required for the Xcode build tools and optional for Ninja and GNU Make.

    The option value Release must be written with an upper-case R; --config release will not work.

  6. Test: ctest -C Release

    7. As with the build step above, the option value Release must be written with an upper-case R.

That's it. SoftFloat-3a, and Zlib will be cloned from the Hercules-390 repository and built inside the Hercules build directory. If BZip2 and/or Zlib are newer than the versions installed on the target system, they will be cloned from the Hercules-390 repository and built inside the Hercules build directory. Once that is done, 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 one through four above. Be sure you use -G "Xcode" in Step four.

  1. Open the Xcode application
  2. Open the Xcode project created by the CMake configure step: navigate to the build directory and open Hercules.Xcodeproj.
  3. Xcode by default builds for "Testing," which corresponds to a CMake Debug configuration. Change this if desired: Product, Build For, Release.
  4. Build the solution: Product, Build.
  5. When the build has completed, you may run the Hercules tests by building the RUN_TESTS scheme: Product, Scheme, RUN_TEST, followed by Product, Build.

Hercules may be installed using a command line or using the Xcode IDE.

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

The CMake configure option -DCMAKE_INSTALL_PREFIX can be used to change the default installation directory.

Installing Hercules
  1. Open a command prompt.
  2. Navigate to the build directory.
  3. Issue the following command. Use sudo if needed.

    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 /home/userid/hercules, you can override that directory with the following form of the install command:

    cmake -DCMAKE_INSTALL_PREFIX="/home/userid/hercules" -P cmake_install.cmake

Uninstalling Hercules

Uninstallation can be easily performed by deleting the installation directory.

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.
  2. Navigate to the build directory.
  3. Issue the following command. Use sudo if needed.

    cmake -P cmake_uninstall.cmake




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:

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.