Skip to content

CMake Overview

Jump to bottom Edit New page
Stephen Orso edited this page May 13, 2018 · 1 revision

Wiki ▸ CMake Build Logic ▸ CMake Overview

Supported Target Systems

The CMake build scripts for Hercules supports the compilation of Hercules on the following systems:

  • Windows 64-bit or newer using Visual Studio 2008 or newer.
  • GNU/Linux systems, such as Debian, Fedora, and Leap using GNU Make
  • Other UNIX-like systems, including FreeBSD and Solaris, using BSD Make
  • macOS using Xcode or Xcode Command Line Tools.

The Ninja build tool is supported in all environments. On Windows, the Visual Studio 2017 Build Tools may be used, and the JOM build tool may be used in place of the NMake or MSBuild build tool.

Systems Known to be Unsupported

NetBSD: A number of changes are needed to enable builds of Hercules on NetBSD. These are under investigation.

OpenBSD: OpenBSD does not support Thread-Level Storage (TLS). SoftFloat-3a For Hercules requires TLS.

Supported Build Tools

The CMake scripts for Hercules will create build scripts and configuration files for any of the following build tools:

Tool Config System Notes
BSD Make Single BSD, macOS N/A
GNU Make Single BSD, Linux, macOS, Solaris N/A
JOM Single Windows https://wiki.qt.io/Jom. A replacement for NMake that includes support for parallel builds.
Ninja Single BSD, Linux, macOS, Solaris, Windows https://ninja-build.org. An alternative to Make with a focus on speed. It is faster; give it a try
NMake Single Windows A stand-alone build tool provided with older Microsoft Software Development Kits, older and current versions of Visual Studio, and with Visual C Express Edition 2008.
Visual Studio Multiple Windows Can use the command line build tool devenv or MSBuild, or build in the IDE. Visual Studio 2017 Build Tools can be used.
Xcode Multiple macOS Can use the command line build tool Xcode-build or build in the IDE. Xcode Command Line Tools can be used.

CMake should be able to create build scripts and configuration files for any build tool supported on the target system by CMake. But the above build tools have been tested.

Build Configurations

The CMake scripts for Hercules support two build configurations:

Release: Optimization at the O2 level with debugging information and symbols. This really matches the configuration that would be expected with RelWithDebInfo.

Debug: No optimization (O0) with debugging information and symbols.

Release is set up as RelWithDebInfo because Hercules-390 is under development. A future activity would be to add RelWithDebInfo as a configuration type and make it the default.

When using a single-configuration build tool (GNU or BSD Make, JOM, Ninja, NMake), the build configuration is fixed when CMake is run. To build a different configuration, CMake must be re-run.

When using a multi-configuration build tool (Visual C Express Edition, Visual Studio, Xcode), The build configuration is selected when the build tool is invoked. CMake need not be re-run to build a different build configuration.

The CMake scripts for Hercules are coded as if the build tool supports multiple configurations, and unique options are set for each supported configuration. When a single-configuration build tool is being used, the CMake package ensures the options used in the created build tool script reflect the configuration specified when CMake is run.

Note: on macOS, the build configuration passed to CMake or CTest is case sensitive; release is not the same as Release. On Windows, the build configuration name is not case sensitive.

External Packages

Hercules uses the following external packages. SoftFloat-3a For Hercules is required. All others are optional, and if omitted, certain Hercules capabilities will not be included. Build options exist to use previously-built external packages, and a build option allows multiple Hercules builds to share external package builds. Absent options, external packages are built in the Hercules build directory.

All external packages built by Hercules are retrieved from repositories in the Hercules-390 github project. The repositories contain the external package and CMake scripts to build that package with the options required for Hercules. The scripts also create import targets to simplify the connection from the Hercules CMake scripts to the contents of the packages. The shared libraries built by the package scripts have Hercules-specific prefixes so that they can be installed with Hercules in a standard system directory, perhaps /usr/local/bin, without impairing the system's use of the corresponding general purpose library. For example, h390zlib.so is used instead of zlib.so.

SoftFloat-3a: The build scripts will clone and build SoftFloat-3a For Hercules from the Hercules-390 github project, or it will use a previously built SoftFloat-3a For Hercules if -DS3FH_DIR points to it.

BZip (h390BZip): If the system-installed version of the BZip2 development library is at least as new as the version in the Hercules-390 project, it is used. If BZip2 is not installed or is older than the version in the Hercules-390 project, the Hercules-390 repository for BZip2 is cloned and built during the Hercules build. Build options exist to force use of the system-installed BZip2.

Zlib (h390Zlib): If the version of the Zlib development library is at least as new as the version in the Hercules-390 project, it is used. If Zlib is not installed or is older than that in the Hercules-390 project, the Hercules-390 repository for Zlib is cloned and built during the Hercules build. Build options exist to force use of the system-installed Zlib.

PCRE (h390PCRE) (Windows only; not required for UNIX-like or macOS target systems.) PCRE provides regular expression support to the Hercules Automatic Operator, which allows regular expressions in message definitions. The build scripts will clone and build PCRE from the Hercules-390 github project, or it will use a previously built PCRE if -DPCRE_DIR points to it.

Each external package is built with the same build tool and for the same configuration as Hercules itself.

The External Package Directory

The Hercules CMake scripts normally create an external package directory within the Hercules build directory. This package directory is used for the source directory tree and the build directory tree for each external package.

A Hercules build option -DEXTPKG_DIR= can be used to relocate the external package directory outside of the Hercules build tree. This option can also be used to share a single external package directory with several Hercules build trees. There are restrictions on sharing an external package directory. The following conditions apply:

  • Every Hercules build tree sharing an external package directory must use the same build tool. It is not possible for a build tree that uses Ninja to share an external package directory with a build tree that uses GNU Make.
  • For single-configuration build tools, the same configuration must be built.

REXX Packages

The CMake scripts use REXX to execute the test programs in the tests directory (runtest.rexx)and to reduce the Hercules log output to test results (redtest.rexx). Hercules will also optionally allows REXX scripts to be run from the Hercules console. Either of two REXX packages are supported: Open Object Rexx and Regina Rexx. Other REXX packages might work with the .rexx scripts, but Hercules-390 cannot integrated with other REXX packages.

On UNIX-like systems and macOS, the CMake scripts expect the REXX package(s) to be installed in standard system locations such as /usr/bin or /usr/local/bin depending on the distribution being used.

On Windows, the CMake scripts query the Windows Registry to find the installation directory for each REXX package. If building a 32-bit Hercules on a 64-bit system, the scripts look for a 32-bit version of each REXX package.

Error Message Display

All errors detected by the CMake scripts are displayed at the end of the CMake configure step. CMake can generate a lot of output as it performs its probes of the system, compiler, and userland. As errors are detected, they are stored in an array by the function herc_Save_Error in Herc00_Includes.cmake.

After compiler options have been set by the appropriate Herc31 routine, CMakeLists.txt checks the error message count. If it is non-zero, all error messages are listed and the build is terminated.

This Wiki 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.

Add a custom footer

Welcome to Hercules

Building & Running

For Developers

Problem Determination

CMake Build Logic

Clone this wiki locally