Using CMake to Build Hercules Version 4.0

What is a Hercules External Package?

List of Hercules External Packages

How and When External Packages are Built

Controlling Where External Packages are Built

Letting the CMake Script Build External Packages

Require the CMake Script to Build an External Packages

Require the Use of a System-Installed External Package

Build External Package(s) Yourself

What is a Hercules External Package?

A Hercules External Package meets at least one of the following criteria:

The package provides functionality not available on one of the platforms that Hercules supports. BZip2, PCRE, and Zlip fit this criterion because they are not included in the Windows distribution.
Modifications were required to a generally available package to adapt it to the specific requirements of mainframe emulation. SoftFloat-3a fits this criterion.

Packages that require no special action when building Hercules, such as the Microsoft Visual C Runtime or pthreads on UNIX-like systems, are not considered "Hercules External Packages." While logically external to Hercules, packages like the C runtime and pthreads are readily available, are normally part of their respective host systems, and do not require alteration, customization, or specific build parameters. Likewise, neither Open Object Rexx nor Regina Rexx are considered Hercules External Packages from the standpoint of building Hercules.

If you do not code any of the options available to control building of external packages for Hercules, the CMake build will build all required external packages within a subdirectory of the build directory. On subsequent rebuilds of Hercules, each external package clone is checked for updates and rebuilt only if needed. Updates include changes to the Hercules-390 repository for the package and any changes made on the local system.

Shared libraries created for external packages are given Hercules-specific names and will be installed with Hercules. On UNIX-like systems, this could mean that external packages will be installed in system standard directories such as /usr/local/lib. The Hercules-specific names prevents conflicts with standard versions of those packages.

This approach allows you build Hercules without having to be aware of external packages at all. Should you wish to delete the Hercules build directory, the deletion also deletes the clone and build directories for every external package.

If this is acceptable—and, often, it is—you need not read this page any further unless you are curious. Or are a Hercules Developer or wish to become one.

List of Hercules External Packages

The following external packages are used by Hercules:

Package	Hercules Usage	Hercules-390 Repository & Upstream URL
BZip2	A data compression library. Required only to provide support for BZip2-compressed emulated tape and disk volumes. Only the compression and decompression functions are used. The command-line utilities are not used.	https://github.com/hercules-390/h390BZip http://www.bzip.org/
PCRE	Perl-Compatible Regular Expressions Required to support regular expressions in Hercules Automatic Operator expressions, and only on the Windows platform. Hercules uses the built-in userland support for regular expressions available in UNIX-like systems. Only the 8-bit character set version without Unicode nor UTF-8 is needed. The executable test programs are not needed.	https://github.com/hercules-390/h390PCRE http://www.pcre.org/
SoftFloat-3a For Hercules	Binary floating point library. Required. This is a modified version of Dr. John Hauser's SoftFloat binary floating point package. The modifications adapt SoftFloat version 3a to the specifics of IBM binary floating point, as defined in the z/Architecture Principles of Operation, SA22-7832-11.	https://github.com/hercules-390/SoftFloat-3a http://www.jhauser.us/arithmetic/SoftFloat.html
Zlib	A data compression library. Required only to provide support for Zlib-compressed emulated tape and disk volumes. The command-line examples are not needed.	https://github.com/hercules-390/h390Zlib http://www.zlib.net/

When and How External Packages are Built

The CMake script for Hercules will build an external package when all of the following are true:

The package was not specifically excluded. For example, -DBZIP2=NO is not included on the CMake command line.
A build or install directory location has not been specified using a CMake option. For example -DBZIP2_DIR=<build-tree> is not included on the CMake command line.
(UNIX-like systems only) A version of the package is not installed in the system's standard libraries, or the version that is installed is older than the version maintained in the Hercules-390 project.

When the CMake script for Hercules builds an external package, it uses the same build tool, architecture (32-bit or 64-bit), and build configuration (release or debug) as is being used for Hercules. Defaults are taken for all other external package build options, and because any Hercules-built external package is cloned from the Hercules-390 project, the defaults are appropriate.

When Hercules is rebuilt, perhaps due to development activity, all external packages built by the CMake script are checked for updates. Updates include changes committed to the external package repository in the Hercules-390 project or changes to the external package source as a result of development activity on the external package.

Normally, external packages are not rebuilt when Hercules is rebuilt.

Controlling Where and When External Packages are Built

Let the CMake Script Build External Packages

The CMake script for Hercules will clone and build all required external packages into the location specified or defaulted to in -DEXTPKG_DIR. This option specifies the path that the CMake script will use as the root of all package directories for those external packages that will be built by the script.

The -DEXTPKG_DIR=<extpkg_dir> option probably 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. If multiple Hercules build directories are created using the same -DEXTPKG_DIR= directory, all of those build directories must use the same build tool, architecture (32-bit or 64-bit), and configuration type (release or debug).

The external package directory structure looks like this:

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

The default value for this directory is <build-dir>/extpkg, which causes CMake to build all external packages in the Hercules build directory tree.

The CMake script for Hercules will clone and configure each external package, and it will generate instructions in the Hercules build script to update the clone, configure if needed, and build the external package. An install of the external package is not done. The CMake script for Hercules uses the build directory of the external package. Instructions are added to the Hercules build script to include any external package shared libraries in the Hercules install.

Require the CMake Script to Build an External Package

On UNIX-like systems, the CMake script to build Hercules will use the system-installed version of an external package if the system-installed version is newer than the one in the Hercules-390 project.

To force the CMake script to build an external package even when the UNIX-like target system has a newer version, use one of the following build options. These options facilitate validation of each Hercules-390 external package repository.

`-DBZIP2=HERCULES`	Build the BZip2 compression library from the Hercules-390 project
`-DZLIB=HERCULES`	Build the Zlib compression library from the Hercules-390 project

Notes: PCRE is never built by the CMake script for Hercules on UNIX-like systems. SoftFloat-3a is always built by the CMake script for Hercules. Options may be used to force the CMake script to build one or both of the above external packages.

Require the Use of a System-Installed External Package

To force the CMake script to use system-installed external package even when the UNIX-like target system has an older version, use one of the following build options. These options facilitate validation of Hercules using external packages provided by the UNIX-like distribution.

`-DBZIP2=SYSTEM`	Use the BZip2 compression library from the target system
`-DZLIB=SYSTEM`	Use the Zlib compression library from the target system

Build External Package(s) Yourself

While the CMake script to build Hercules will build each external package, each external package has a separate CMake build script and may be built independently of Hercules.

If you are doing development work on an external package, say SoftFloat-3a, or implementing a new release of an upstream package, say, Zlib, you should create your own source directory for the package, build it yourself using instructions in the Hercules-390 package repository, and then tell the CMake script for Hercules where to find that package using any or all of the following options.

`-DBZIP2_DIR=<dirname>`	Replace `<dirname>`with the build or install directory of the BZip2 compression library that you built.
`-DPCRE_DIR=<dirname>`	Replace `<dirname>`with the build or install directory of the PCRE regular expression library that you built.
`-DS3FH_DIR=<dirname>`	Replace `<dirname>`with the build or install directory of the SoftFloat-3a For Hercules binary floating point library that you built.
`-DZLIB_DIR=<dirname>`	Replace `<dirname>`with the build or install directory of the Zlib compression library that you built.

There is no requirement to install the external package into a separate install directory. The CMake script for Hercules can incorporate an external package from a build directory tree or an install directory tree.

There is no requirement to build all external packages. You can build one external package yourself and let the CMake script for Hercules build any remaining packages in the external package directory.

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.