CMake script command line options begin with the prefix -D and consist of the option name, an equals sign ("="), and an option value.

These options are specific to the CMake scripts used to build Hercules.  Additional standard CMake options can be used; a description of selected options may be found on Standard CMake Build Options. For a complete list of standard CMake options, refer to the CMake documentation at cmake.org.

Most options are yes/no options. Yes/No options are case insensitive and may be written as Yes, Y, No, or N.

All Hercules CMake script options may be specified on the command lines. They may also be set as environment values by omitting the -D prefix.  For example, including -DHET-BZIP2=YES on the CMake command line has the same effect as setting the environment variable HET-BZIP2 to YES.

A bold option value in the list below indicates a default option. Where no default is shown, the default is determined by the capabilities of the target system. If the target supports the option, the default is yes, otherwise it is no.

Summary of Hercules CMake Script Options

ADD-CFLAGS Add compiler options
AUTOMATIC-OPERATOR Enable the Automatic Operator function
BZIP2 Include BZip2 compression capabilities
BZIP2_DIR Directory containing a previously-built BZip2 library
CAPABILITIES Enable fine-grained security for hercifc (UNIX-like only)
CCKD-BZIP2 Enable BZip2 compression for emulated disk volumes
CUSTOM Custom descriptive string describing the build
DEBUG Compile Hercules for debugging
EXTERNAL-GUI Enable interface to an external graphical user interface
EXTPKG_DIR Directory to contain required external packages
GETOPTWRAPPER Use a wrapper for the getopt() function (UNIX-like systems only)
GIT_CLONE Specify the protocol to be used when cloning repositories.
HELP Display help and exit
HET-BZIP2 Enable BZip2 compression for emulated tape volumes
HQA_DIR Hercules QA build header directory
INTERLOCKED-ACCESS-  
   FACILITY-2		 Enable the Interlocked Access Facility 2
IPV6 Include support for IP Version 6
LARGEFILE Enable/disable support for large files (>4GiB) if not natively supported
MULTI-CPU Enable support for multiple emulated CPUs
OBJECT-REXX Include support for Open Object Rexx in HAO and command scripts
OPTIMIZATION Specify compiler optimization flags
PCRE Include support for the Perl-Compatible Regular Expression Library (Windows only)
PCRE_DIR Directory containing a previously-built PCRE library (Windows only)
REGINA-REXX Include support for Regina Rexx in HAO and command scripts
S3FH_DIR Directory containing a previously-built SoftFloat-3a For Hercules library
SETUID-HERCIFC Install hercifc with setuid permissions (not supported for the nonce)
SYNCIO Dispatch I/O operations on a CPU thread (soon to be deprecated)
WINTARGET (Windows Only) Specify the version of Windows to be targeted by the build.
ZLIB Include ZLib compression capabilities
ZLIB_DIR Directory containing a previously-built ZLib library.

Options specific to one target system type are ignored when used for a different target system type. This allows a common set of options to be defined in a script, perhaps a REXX script, to be run on either Windows or UNIX-like systems.


Dictionary of Hercules CMake Script Options

Provide additional c compiler command line options. Any string provided here is appended to the end of the c compiler flags generated by CMake, including optimization flags. This option allows you to specify additional optimization flags, such as -O3, or to disable flags created by CMake. Flags added by -DADD_CFLAGS="" are shown in the summary of CMake build options displayed at the end of CMake generation.

If you need to add flags to the beginning of the c command line options list, for example include files or library directories, use the CMake standard option -DCMAKE_C_FLAGS. 


Enable the Hercules Automatic Operator feature. Regular expression support is required on the target system, and the existence of the header file regex.h is used in the test for that support. On Windows target systems, the Perl Compatible Regular Expressions library, PCRE, is used to provide regular expression support.

The Hercules Automatic Operator feature is described in more detail here.


Define whether Hercules should include BZip2 compression support, whether BZip2 should be built or used from a UNIX-like system's standard libraries.

YES

BZip2 support should be included in Hercules. This is the default.

Windows Systems: When option BZIP2_DIR is not specified, BZip2 will be obtained from the h390BZip repository of the Hercules-390 project and built when Hercules is built.

UNIX-like systems: When option BZIP2_DIR is not specified, BZip2 is not installed in the system's libraries, or the installed version is older than the version available in the Hercules-390 project, BZip2 will be obtained from the h390BZip repository of the Hercules-390 project and built when Hercules is built.

NO

BZip2 support is not included in Hercules.

HERCULES

BZIP2=HERCULES is ignored if BZIP2_DIR is specified.

BZip2 support should be included in Hercules and built from the h390BZip repository in the Hercules-390 project regardless of any BZip2 version that may be installed on the target system.

On Windows systems, HERCULES has the same meaning as YES.

SYSTEM

BZIP2=SYSTEM is ignored if BZIP2_DIR is specified.

BZIP2=SYSTEM is not allowed on Windows builds of Hercules.

BZip2 support should be included in Hercules and included from the system's libraries regardless the version that may be installed in those libraries.

If BZIP2_DIR= is coded, the Hercules CMake script does not clone and build the BZip2 library into the directory specified by extpkg_dir.  If this option is omitted, the Hercules CMake script will generate build tool scripting to clone and build a copy of the BZip2 library in the directory specified by or defaulted to by the extpkg_dir option.

This option is most useful for developers who are testing an uplevel version of the BZip2 Library. The option allows developers to test changes in the uplevel BZip2 library and their integration with Hercules build prior to those changes being committed to the h390BZip repository in the Hercules-390 project.

For more information about external packages used by Hercules and how the CMake script for Hercules builds those packages, see Controlling the Automatic Build of External Packages


Define the build or the installation directory for the BZip2 library, relative or absolute. A relative directory is relative to the Hercules build directory. The BZip2 library must have been previously built. Either an installation directory or a build directory may be specified by this option.

This option must be omitted if BZIP2=NO.

This option overrides BZIP2=SYSTEM and BZIP2=HERCULES.

If BZIP2_DIR= is coded, the CMake script does not clone and build the BZip2 library. If this option is omitted, the CMake will script create build scripting to clone and build a copy of the BZip2 library in the directory specified by or defaulted to by the extpkg_dir option.

This option is most useful for developers who are testing an uplevel version of the BZip2 Library. The option allows developers to test changes in the uplevel BZip2 library and their integration with Hercules build prior to those changes being committed to the h390BZip repository in the Hercules-390 project.

For more information about external packages used by Hercules and how the CMake script for Hercules builds those packages, see Controlling the Automatic Build of External Packages


Enable support for fine grained privileges for the HERCIFC utility. Fine grained privileges allow HERCIFC to configure network interfaces for Channel-to-Channel operations without having system root privileges.

Fine grained privileges are not available on all systems. The existence of header file sys/capability.h and, on targets that require it, libcap is tested to determine if capabilities can be enabled.

This option is ignored for Windows target systems.


Enable support for bzip2 compression for emulated DASD volumes.

If the BZip2 external package is excluded when building Hercules (-DBZIP2=NO on the CMake command line or BZIP2=NO set as an environment variable), then the default is NO. Otherwise, the default is yes.

The -bz2 command line option of the dasdcopy, dasdnint, and dasdload utilities must be used to create an emulated DASD volume with BZip2 compression.


Provide a custom description for this build. This description is included in the config.h file generated by the CMake build script for Hercules. The custom description is displayed at Hercules startup in message HHC01417I.

This option can be helpful if you build multiple copies of Hercules and wish to confirm the identity of the copy that is being executed.


Enable the Hercules debugging macros TRACE, VERIFY, and ASSERT macros)

This option may be useful for developers or if requested as part of diagnosing an issue. It is not required for normal use of Hercules.


Enable the interface to an external graphical user interface. Hercules Studio (open source systems and mac OS) and HercGUI (Windows) require this option.

EXTERNAL-GUI=YES is not required to use the Hercules internal web server.


<pkg_dir> may be absolute or relative to the Hercules build directory.

The -DEXTPKG_DIR=<pkg_dir> option is most useful to Hercules developers who may have multiple Hercules build directories, or who wish to erase and recreate the build directory without rebuilding all external packages. Note that if a single <pkg_dir> directory is shared between multiple Hercules build directories, all Hercules build directories must be built using the same build tool and architecture (32-bit or 64-bit). It is not possible for a Hercules build that uses, say, Ninja, to reference an EXTPKG_DIR that is used by a Hercules build directory that uses Makefiles.

This option specifies the directory that the CMake build will use as the root of all package directories for those external packages that CMake will build. The external package directory structure looks like this:

extpkg/ All external packages are placed in extpkg/, with a separate subdirectory per package
extpkg/<pkgname>/ directory for one external package, named "pkgname"
extpkg/<pkgname>/pkgsrc source directory, generally from a git repository.
extpkg/<pkgname>/build build directory for an external package.
extpkg/<pkgname>/install install directory for the built package

The default value for this directory is <herc_build_dir>/extpkg, which causes CMake to build all external packages in the Hercules build directory tree. This default enables a casual builder to build Hercules without having to be aware of external packages at all. And should the casual builder tire of Hercules, deleting the build directory also deletes the external package repositories, builds, and installation directories.

Each time Hercules is built, the packages in the external package directory are checked for updates, either from the upstream repository or as a result of editing of source files in the local pkgsrc directory, and each updated package is rebuilt. Packages that are not updated are not rebuilt when Hercules is rebuilt.

For more information about external packages used by Hercules and how the CMake script for Hercules builds those packages, see Controlling the Automatic Build of External Packages


Certain (older?) UNIX-like systems generate linker errors when an executable uses getopt() and uses a shared library that also uses getopt().

This option, when YES, causes Hercules executables to call an internal routine in the shared library that in turn calls getopt().

CMake does not (yet) test for the requirement to use a wrapper for getopt(). If you receive linker error messages when building Hercules, please add this option and rebuild. Should this option address the linker error messages, please open an issue so CMake code can be developed and tested.


Specify the protocol to be used when cloning repositories. This option is needed only when the default protocol, https:, does not work.

The CMake scripts will clone repositories containing external packages required to build Hercules, and the generated build scripts will update the local clones of those external package repositories. See the git protocol documentation for descriptions of the differences between the two protocols.

https:

Use the https: protocol to clone repositories. This is the default.

git:

Use the git: protocol to clone repositories. The git: protocol can be used on systems that do not support https: or do not have current certificate stores. The git: protocol requires outbound access using TCP/IP port 9418, and higher-numbered ports are often blocked on corporate networks.


Display summary help for the CMake script that builds Hercules and exit. Build tool scripts needed to build Hercules are not created.


Enable support for bzip2 compression for emulated tape volumes.

If the BZip2 external package is excluded when building Hercules (-DBZIP2=NO on the CMake command line or BZIP2=NO set as an environment variable), then the default is NO. Otherwise, the default is YES.

The -b command line option of the hetupd utility must be used to convert an emulated tape volume to one with BZip2 compression. No option exists in hetinit to create an emulated tape volume that uses BZip2 compression.


Define the directory containing the optional header hqa.h.


Enable the Interlocked-Access Facility 2, as defined in the z/Architecture Principles of Operation (SA22-7832-10, pages 1-16 and in the descriptions of each instruction affected by the presence of the Interlocked-Access Facility 2.

Any of three target system and c compiler capabilities must be present to enable the Interlocked-Access Facility 2. In order of preference, they are:

  1. C11-standard atomic intrinsic functions
  2. Microsoft atomic intrinsic functions (Windows only; Visual Studio 2015 or newer only)
  3. __atomic built-in functions
  4. __sync built-in functions

If none of the above capabilities exists in the target system, Hercules will be built without the Interlocked-Access Facility 2 and without comment.

Is this what happens when Hercules is built using GNU Autotools?

Yes, this is what happens when GNU Autotools is used to build Hercules on a target system that does not support any of the above capabilities.


Include IPV6 support in Hercules.

If this option is not specified and the target system includes IPV6 support, then Hercules will be built with IPV6 support.


Enable support for large files (greater than 4GB) on UNIX-like systems that do not natively support large files but have the capability to do so.

Some UNIX-like systems support large files natively and do not require special macros or coding to do so. Such systems include FreeBSD since version 2 (ca. 1994) and most (all?) 64-bit open source systems.

This option is ignored when Hercules is built for a Windows target system. Such systems always support large files and that support cannot be disabled.

The default is LARGEFILE=YES on UNIX-like target systems that offer some form of large file support (native, specifically enabled, or transitional) and LARGEFILE=NO on systems that have no large file support.

LARGEFILE=NO is rejected for those systems that support large files natively; large file support cannot be disabled on such systems.

Large file support is required when using emulated 3390-9 or larger DASD volumes, when using DASD with very large shadow files, or when using emulated tape volumes that are much larger than would have been supported on real (reel?) hardware.

See the document created by the Large File Summit for details about how non-native large file support came to be a part of The Single UNIX Specification Version 2, in 1996.


Specify the maximum number of CPUs that can be specified on the numcpu Hercules command.

YES

Generate support for eight processors.

NO

Generate support for a single CPU.

<number>

Generate support for the specified number of processors. For Windows systems, 32-bit UNIX-like systems, and any system that does not support the uint128_t type, the maximum is 64. For 64-bit UNIX-like systems that include the uint128_t type, the maximum value is 128.

If omitted, Hercules will be built to support 64 CPUs on systems without the uint128_t and 128 CPUs on systems that have the type.


Enable support for Open Object Rexx support.

If this option is not specified and Open Object Rexx is installed, Hercules is built with Open Object Rexx support.

If header files rexx.h and oorexxapi.h are present, then Open Object is presumed to be installed.

It is perfectly reasonable to include support for both Open Object Rexx and Regina Rexx in a single Hercules build. . If both are installed on the target system and neither has been excluded, then Hercules will be built with the capability to use either REXX language. The Hercules rexx command can be used to specify which REXX interpreter should be used at any given time.


Enable automatic optimization, or specify c compiler optimization flags.

Automatic optimization is possible only for c compilers that the CMake build recognizes. These include clang, gcc, and Microsoft Visual Studio C (MSVC).

If you wish to build with a c compiler that the CMake build for Hercules does not recognize, you can use the OPTIMIZE and ADD-CFLAGS options to specify compiler options, including optimization options.


(Windows target systems only.) Define whether Hercules should include PCRE regular expression support, and whether PCRE should be built by Hercules. This option is needed only when Hercules is built for Windows and is ignored for other systems.

When Hercules is built on a UNIX-like system, it uses the regular expression support provided by the host system, and the PCRE library is not required and will not be built.

YES

PCRE support should be included in Hercules. This is the default.

When option PCRE_DIR is not specified, PCRE will be obtained from the h390PCRE repository of the Hercules-390 project and built when Hercules is built.

On UNIX-like systems this option is ignored.

NO

PCRE support is not included in Hercules.

HERCULES

PCRE=HERCULES is ignored if PCRE_DIR is specified.

PCRE support should be included in Hercules and built from the h390PCRE repository in the Hercules-390 project regardless of any PCRE version that may be installed on the target system.

HERCULES has the same meaning as YES.

If PCRE_DIR= is coded, the CMake build does not clone and build the PCRE library into the directory specified by extpkg_dir.  If this option is omitted, Hercules will clone and build a copy of the PCRE library in the directory specified by or defaulted to by the extpkg_dir option.

This option is most useful for developers who are testing an uplevel version of the PCRE Library. The option allows developers to test changes in the uplevel PCRE library and their integration with Hercules build prior to those changes being committed to the h390PCRE repository in the Hercules-390 project.

For more information about external packages used by Hercules and how the CMake script for Hercules builds those packages, see Controlling the Automatic Build of External Packages


Define the build or the installation directory for the PCRE library, relative or absolute. A relative directory is relative to the Hercules build directory. The PCRE library must have been previously built. Either an installation directory or a build directory may be specified by this option.

This option must be omitted when PCRE=NO and Hercules is being configured for a Windows target system.

This option overrides PCRE=SYSTEM and PCRE=HERCULES.

If PCRE_DIR= is coded, the CMake script does not clone and build the PCRE library. If this option is omitted, the CMake script will create build scripting to clone and build a copy of the PCRE library in the directory specified by or defaulted to by the extpkg_dir option.

This option is most useful for developers who are testing an uplevel version of the PCRE Library. The option allows developers to test changes in the uplevel PCRE library and their integration with Hercules build prior to those changes being committed to the h390PCRE repository in the Hercules-390 project.

For more information about external packages used by Hercules and how the CMake script for Hercules builds those packages, see Controlling the Automatic Build of External Packages


Enable support for Regina Rexx support.

If this option is not specified and Regina Rexx is installed, Hercules is built to include Regina Rexx support.

If header file rexxsaa.h is present, then Regina Rexx is presumed to be installed on the target system.

It is perfectly reasonable to include support for both Open Object Rexx and Regina Rexx in a single Hercules build.  If both are installed on the target system and neither has been excluded, then Hercules will be built with the capability to use either REXX language. The Hercules rexx command can be used to specify which REXX interpreter should be used at any given time.


Define the build or the installation directory for the SoftFloat-3a For Hercules library, relative or absolute. A relative directory is relative to the Hercules build directory. The SoftFloat-3a For Hercules library must have been previously built. Either an installation directory or a build directory may be specified by this option.

If S3FH_DIR= is coded, the CMake script does not clone and build the SoftFloat-3a For Hercules library. If this option is omitted, the CMake script will create build scripting to clone and build a copy of the SoftFloat-3a For Hercules library in the directory specified by or defaulted to by the extpkg_dir option.

This option is most useful for developers who are testing an uplevel version of the SoftFloat-3a For Hercules Library. The option allows developers to test changes in the modified library and their integration with Hercules build prior to those changes being committed to the SoftFloat-3a repository in the Hercules-390 project.

For more information about external packages used by Hercules and how the CMake script for Hercules builds those packages, see Controlling the Automatic Build of External Packages


Install hercifc as setuid root.

Note: SETUID-HERCIFC=<groupname> is not presently supported. You must manually issue the command to set the group owner of hercifc.


The SYNCIO command line option enables or disables Syncio.  Syncio refers to the processing of certain emulated I/O operations by the process thread that is emulating the CPU that executed the I/O instruction rather than dispatching an I/O thread.

Syncio is deprecated and will be withdrawn from Hercules in the future, and all I/O operation emulation will be performed by an I/O thread.

The default of YES will be changed in the near future. To see whether there are any impacts on your use of Hercules, it is suggested that you define the environment variable SYNCIO=NO.


Windows target systems only. On UNIX-like systems this option is ignored.

Specify the version of Windows to be targeted by the build. As a general rule, targeting for a given version of Windows will include support for future versions of Windows, although Microsoft has been known to break this from time to time.

TARGET

Target Hercules for the Windows version running on the system on which Hercules is being built. This is the default.

Note: If you specify this option or accept it as a default, the header sdkddkver.h must be available in the Windows Software Development Kit (SDK) used when building Hercules.

DIST

Target Hercules for oldest version of Windows that Hercules supports, Windows XP Professional 64-bit Service Pack 3 (WINXP364).

Builds targeting WINXP364 can be run on newer 32-bit and 64-bit versions of Windows through at least Windows 10.

WINXP364

Target Hercules for Windows XP Professional 64-bit Service Pack 3 (WINXP364). Builds that target WINXP364 can be run on newer 32-bit and 64-bit versions of Windows through at least Windows 10.

WINVISTA

Target Hercules for Windows Vista.

WIN7

Target Hercules for Windows 7.

WIN8

Target Hercules for Windows 8 (and 8.1).

WIN10

Target Hercules for Windows 10.


Define whether Hercules should include Zlib compression support, whether Zlib should be built, built if needed, or used from a UNIX-like system's standard libraries.

YES

Zlib support should be included in Hercules. This is the default.

On Windows systems when option ZLIB_DIR is not specified, Zlib will be obtained from the h390Zlib repository of the Hercules-390 project and built when Hercules is built.

On UNIX-like systems when option ZLIB_DIR is not specified, if Zlib is not installed in the system's libraries, or the installed version is older than the version available in the Hercules-390 project, Zlib will be obtained from the h390Zlib repository of the Hercules-390 project and built when Hercules is built.

NO

Zlib support is not included in Hercules.

HERCULES

ZLIB=HERCULES is ignored if ZLIB_DIR is specified.

Zlib support should be included in Hercules and built from the h390Zlib repository in the Hercules-390 project regardless of any Zlib version that may be installed on the target system.

On Windows systems, HERCULES has the same meaning as YES.

SYSTEM

ZLIB=SYSTEM is ignored if ZLIB_DIR is specified.

ZLIB=SYSTEM is not allowed on Windows builds of Hercules.

Zlib support should be included in Hercules and included from the system's libraries regardless the version that may be installed in those libraries.

If ZLIB_DIR= is coded, the CMake build does not clone and build the Zlib library into the directory specified by extpkg_dir.  If this option is omitted, Hercules will clone and build a copy of the Zlib library in the directory specified by or defaulted to by the extpkg_dir option.

This option is most useful for developers who are testing an uplevel version of the Zlib Library. The option allows developers to test changes in the uplevel Zlib library and their integration with Hercules build prior to those changes being committed to the h390Zlib repository in the Hercules-390 project.

For more information about external packages used by Hercules and how the CMake script for Hercules builds those packages, see Controlling the Automatic Build of External Packages


Define the build or the installation directory for the Zlib library, relative or absolute. A relative directory is relative to the Hercules build directory. The Zlib library must have been previously built. Either an installation directory or a build directory may be specified by this option.

This option must be omitted if ZLIB=NO.

This option overrides ZLIB=SYSTEM and ZLIB=HERCULES.

If ZLIB_DIR= is coded, the CMake script does not clone and build the Zlib library. If this option is omitted, the CMake will script create build scripting to clone and build a copy of the Zlib library in the directory specified by or defaulted to by the extpkg_dir option.

This option is most useful for developers who are testing an uplevel version of the Zlib Library. The option allows developers to test changes in the uplevel Zlib library and their integration with Hercules build prior to those changes being committed to the h390Zlib repository in the Hercules-390 project.

For more information about external packages used by Hercules and how the CMake script for Hercules builds those packages, see Controlling the Automatic Build of External Packages


This web page Copyright © 2017-2019 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.