- Ninja issues on FreeBSD
- Windows Subsystem for Linux, Regina Rexx, and runtest.rexx
- (Resolved) Open Object Rexx and Hercules
QUICK START: Build Hercules Using CMake
To build Hercules on your computer using CMake, you need the following software installed:
CMake version 3.4 or better:
cmake --version. (CMake older than 3.4? See these instructions.)
- A git client version 22.214.171.124 or better:
- A c compiler. Both gcc and clang have been tested.
- If you wish to use
- A REXX interpreter,
either Regina Rexx or Open Object Rexx,
if you wish to run
make test, the CMake equivalent of
- Not required: autoconf, automake, flex, gawk, grep, m4, nor perl. Although there is no issue if these are installed on the system being used to build Hercules-390.
Do the following to build Hercules using CMake on GNU/Linux or BSD open source systems or on Solaris.
- Clone or update your local clone of Hyperion, as needed.
- 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.
cmake --build .
- Run Tests:
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.
- Build Options - information on CMake build options that are specific to building Hercules.
- CMake Build Options, - information on standard CMake options may be used when building Hercules.
- An Overview of CMake - provides, unsurprisingly, an overview of the CMake application and its approach to building applications.
- External Packages - how to control how and where CMake builds SoftFloat-3a and other external packages needed by Hercules-390.
- FAQ - Frequently Asked Questions. See the FAQ if you wish to use 1Stop with CMake.
Why should I use CMake to build Hercules on UNIX-like systems?
- You can build in any directory that is not the Hercules source directory. There is no specific directory structure requirement.
- There is no need to run autogen.sh in the source directory before building.
- The CMake scripts will take care of all SoftFloat-3a build requirements. The build scripts generated by the CMake scripts will build SoftFloat-3a and any other needed external packages in a subdirectory of the build directory. Options are provided to build external packages in another directory, to share one external package build directory with multiple CMake Hercules build directories, or to use one or more previously-built external packages.
- CMake can generate build scripts for either GNU make or BSD make. There is no need to install GNU make on a FreeBSD system.
- CMake can generate build scripts for Ninja, a replacement for make.
- There is no need to have GNU Autotools (autoconf, automake, libtool) installed on build system. You just need git 126.96.36.199 or better, CMake 3.4.3 or better, a build tool such as GNU Makefiles, BSD Makefiles, or Ninja, and gcc or clang.
CMake Build Scripts Development Status
- CMake may be used for Hercules UNIX-like system builds as an alternative to GNU Autotools (autogen.sh followed by configure, make, and make install).
- The CMake scripts to build Hercules have been tested on GNU/Linux (Debian, Ubuntu, Leap), FreeBSD, Windows Subsystem For Linux, and Solaris.
- Apple build support has been coded but testing on macOS 10.10 Yosemite fails in the make command for Hercules; SoftFloat-3a builds successfully, and the CMake scripts complete without error.
- AIX builds have not been tested.
- Windows builds are supported. See Building Hercules for Windows to find out how.
- Apple macOS native Xcode builds have not been tested.
Changes From the Autotools Build
- Libtool is not used. Shared libraries are always built. See below for the issue this creates with Open Object Rexx.
-O3is never included in automatic optimization flags. You may, if you wish, include
-O3in either the
OPTIMIZATIONoption or the
make checktarget is not generated. Use
Detailed test results from make test are not displayed on the console.
Instead, detailed results for each test group are saved in files in the
- Ninja is supported as a generator and has been tested (multiple versions on multiple target systems).
Command Line Option Changes
--enable-xxx is replaced with
XXX is the configure.ac -enable option in caps.
as a configure.ac command line option,
would be specified on the CMake command line as
-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:
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:
--help is replaced with
To see all supported options, use:
cmake <source-dir> -DHELP=YES
If you use
-DHELP=YES, no build files are created.
Command Line Option Additions
If you need to set compiler options or define macros that are passed directly to the c compiler,
<flags> is replaced with the string of options and macros.
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.
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
and controlling the building of external packages.
Current Limitations of the CMake Scripts
- No support for AIX builds. Test subject needed.
- No Support for Cygwin/MinGW. Formerly deprecated, now gone.
- No support for creating an installation or source tarball. Future activity.
- No support for making hercifc setuid from within the build. You will have to do this manually.
Ninja issues on FreeBSD
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.
Windows Subsystem for Linux, Regina Rexx, and runtest.rexx
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.
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.
Open Object Rexx and Hercules
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
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:
- Use the 5.0.0 beta version of Open Object Rexx.
- Use Regina Rexx as the REXX interpreter integrated with Hercules.
What To Do When it Fails
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:
- CMake console log
- Make console log
- Contents of the Testing/Temporary/ directory if the failure occurred during make test
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.