- Building from source on Windows
- Building from source on Mac OS X
- Building from source on Linux and macOS (High Sierra and newer)
By far easiest and most direct way to build Hercules is to use Bill Lewis's fantastic Hercules Helper tool, and not the below manual method.
Hercules Helper (for both Windows and non-Windows) completely automates the entire build process of downloading and installing all of the needed pieces and running all of needed commands to create a working Hercules. Simply download Bill's tool and enter a few simple commands, and within minutes you should have a working Hercules on your system.
If you wish to build Hercules yourself manually however, the procedure is as follows:
git clone https://github.com/SDL-Hercules-390/hyperion.git <directory-name>
If you don't have git
on your system, you will need to install it.
Note: By downloading the source code .zip file (discouraged!)
or by cloning the repository (recommended)
you agree to the terms of the Hercules Q Public Licence.
Important - Not Recently Tested. May be obsolete.
brew install gnu-sed
Important: Please read everything before doing anything. Don't be bashful about asking for help.
Important:
You must use at least version 6.2.0 of the gcc compiler and associated glibc2 library.
Refer to the
Hercules Frequently-Asked Questions page for required
compiler and other software levels.
git clone https://github.com/SDL-Hercules-390/hyperion.git <directory-name>
Note: By downloading the .zip file (or cloning the repository) you agree to the terms
of the Q Public Licence.
sudo apt-get -y install git wget time
sudo apt-get -y install build-essential cmake flex gawk m4 autoconf automake libtool-bin libltdl-dev
sudo apt-get -y install libbz2-dev zlib1g-dev
sudo apt-get -y install libcap2-bin
Note: For Regina REXX to run the included tests:
sudo apt-get -y install libregina3-dev
sudo apt-get -y install git wget time
sudo apt-get -y install build-essential cmake flex gawk m4 autoconf automake libtool
sudo apt-get -y install bzip2 zlib
sudo apt-get -y install libcap
sudo pacman -S --needed --noconfirm git wget
sudo pacman -S --needed --noconfirm base-devel make cmake flex gawk m4 autoconf automake
sudo pacman -S --needed --noconfirm bzip2 zlib
sudo dnf -y install git wget
sudo dnf -y install gcc make cmake flex gawk m4 autoconf automake libtool-ltdl-devel
sudo dnf -y install bzip2-devel zlib-devel
sudo yum -y install git wget time
sudo yum -y install gcc make cmake flex gawk m4 autoconf automake libtool-ltdl-devel
sudo yum -y install bzip2-devel zlib-devel
Note: On CentOS 9, the following command is required before installing the packages:
sudo yum config-manager --set-enabled crb
Note: On Red Hat RHEL 9, the following command is required before installing the packages:
(refer here for more information)
sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
sudo yum -y install git wget
sudo yum -y install gcc make flex gawk m4 autoconf automake libtool-ltdl-devel
sudo yum -y install bzip2-devel zlib-devel
Note: On CentOS 7, there is no package for CMAKE 3.x, it must be built from source.
sudo zypper install -y git
sudo zypper install -y -t pattern devel_basis autoconf automake cmake flex gawk m4 libtool
sudo zypper install -y -t pattern bzip2 libz1 zlib-devel
sudo zypper install -y libcap-progs
brew install wget gsed
xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install cmake autoconf automake libtool
Note: So configure/make will find ltdl.h and libltdl:
export CFLAGS="$CFLAGS -I$(find $(brew --cellar libtool) -type d -name "include" | sort -n | tail -n 1)"
export LDFLAGS="$LDFLAGS -L$(find $(brew --cellar libtool) -type d -name "lib" | sort -n | tail -n 1)"
And include these options to configure:
--disable-getoptwrapper
--without-included-ltdl
Information on installing MacPorts may be found here.
sudo port install wget gsed
sudo port install cmake autoconf automake libtool
Note: So configure/make will find ltdl.h and libltdl:
export CFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib
sudo pkg install -y bash git wget
sudo pkg install -y gmake autoconf automake cmake flex gawk m4 libltdl
sudo pkg install -y bzip2
Note: Bash is required by parts of the build apparatus.
Note: So configure/make will find ltdl.h and libltdl:
export CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib
./util/bldlvlck
Please note that SDL Hyperion comes pre-delivered with an already pre-generated
./configure
script, so doing a ./autogen.sh
is
not necessary and is in fact now strongly discouraged.
An autogen would only be necessary if you were to manually make some changes
to the Hercules default Makefile.am
and/or configure.ac
files (which under normal circumstances you should never need to do).
./configure
By default, the configure script will attempt to guess appropriate
compiler optimization flags for your system. If its guesses
turn out to be wrong, you can either specify your own optimization
flags with
(preferred) or else as a last resort disable all optimization
by passing the
option
instead (not recommended). For additional configuration
options, run: ./configure
.
For Apple macOS, these additional configure switches are recommended:
--disable-getoptwrapper
--without-included-ltdl
make
sudo make install
This is an optional step because once Hercules is built, you should be able to run Hercules directly from the Hercules build directory itself without needing to install anything beforehand. But if you want to officially install it somewhere, then by all means do so.
It should be mentioned however, that if you do decide to run directly out of the build directory, you should first set the 'cap_sys_nice' capabilities on the Hercules executables and start Hercules as root. This will allow Hercules to properly set the priorities of its internal threads:
sudo setcap 'cap_sys_nice=eip' ./hercules sudo setcap 'cap_sys_nice=eip' ./herclin sudo setcap 'cap_net_admin+ep' ./hercifcYou don't need to do this if you do
sudo make install
however
since the makefile does this for you. You only need to do this when you decide
to not install the results of the build and run directly out of the build
directory instead.
You will need to amend the configuration file hercules.cnf to reflect your device layout and intended mode of operation (S/370, ESA/390, or z/Architecture). See the Hercules Configuration File page for a complete description.
The Creating Hercules DASD page describes various methods of creating and loading virtual DASD volumes. The compressed CKD DASD support is described in this page.
Note! If you intend to run any licensed software on your PC using Hercules, it is your responsibility to ensure that you do not violate the software vendor's licensing terms! |
Note: Hercules requires privileged access to your host's networking devices in order for Hercules networking to work properly. If your configuration contains any networking devices, then Hercules must be started with Administrative (root) privileges. If Hercules is not started with Administrative (root) privileges then initialization of your networking devices will fail and your guest's networking will not work properly. If your guest does not need access to your host's network Hercules should be run as a normal unprivileged user (the default). |
Hercules can operate in either of two modes: (semi-)graphical "panel" mode or simple non-graphical standard command-line mode.
The default semi-graphical "panel" mode of operation is invoked by the "hercules.exe" executable, and the non-graphical standard command-line mode by the "herclin.exe" executable. They are both exactly identical except for how the terminal screen is managed.
In the normal (default) semi-graphical "panel" mode, hercules.exe draws
to screen directly itself, and does not rely on any terminal manager
functionality (Terminal or Command-Prompt program). It paints (draws)
messages and other information (such as its command line and CPU status
line) on specific screen lines starting at specific columns, etc:
It relies on certain keystrokes (such as the PageUp and PageDown keys,
etc) to perform actions such as displaying previously issued messages
and switching to its alternate semi-graphical display panel via the Esc.
key (which shows an overall summary of the machine's state, such as its
current set of register values, list of devices, etc):
When started in standard command-line mode via "herclin.exe", the terminal
screen is managed completely by your host operating system's terminal
management software. Hercules does not paint the screen itself at all. It simply
issues messages to "stdout" just like any other command-line program and your operating
system's terminal management software decides where on the screen that line
will be displayed. Additionally, Hercules does not read directly from the
command-ine itself either. Instead, it simply reads from "stdin" and processes
the commands it reads. Your host operating system's terminal manager is in charge
of managing the command-line, not Hercules:
In standard "herclin.exe" command-line mode, Hercules operates just like any other
normal command-line program, and you can use the Terminal's scroll bar (if it has
one) and/or your mouse's scroll wheel to scroll the screen backward or forward to
see previously issued messages and/or commands and their responses. Your host
operating system's terminal manager is in charge of painting the screen and reading
the command line, not Hercules.
To start Hercules in the default "panel" operating mode, enter this command at the host's command prompt:
hercules [ -f filename ] | [ --config=filename ]
[ -o logfile] | [ --output=logfile ] | [ --logfile=logfile ]
[ -r rcfile ] | [ --rcfile=rcfile ]
[ -b logofile ] | [ --herclogo=logofile ]
[ -d ] DEPRECATED | [ --daemon ] DEPRECATED
[ -n ] | [ --NoUI ]
[ -e ] | [ --externalgui ]
[ -p modpath ] | [ --modpath=modpath ]
[ -l modname ] ... | [ --ldmod=modname ] ...
[ -s symbol=value ] ... | [ --defsym=symbol=value ] ...
[ -v ] | [ --verbose ]
[ -h ] | [ --help[=type] ]
[ -t[factor]] | [ --test[=factor]]
[ > logfile ]
where:
filename
- is the name of the configuration file. The default, if none is specified, is hercules.cnf. The default may be overridden via the "
HERCULES_CNF
" environment variable. If the value "none" is specified as the name of the configuration file, then Hercules is started without a configuration file using internal default values and no devices. Alternatively, specifying the filename as "NUL
" on Windows or "/dev/null
" on Linux means the same thing as specifying "none".
logfile
- is the name of the optional log file. A log file receives a copy of all messages displayed on the Hercules control panel. PLEASE NOTE: providing a logfile is extremely important for bug reporting and problem analysis purposes! It is strongly recommended that you always specify this option!
rcfile
- is the name of the Hercules .rc run commands file. The run commands file automatically executes panel commands upon startup. If not specified, the value of the "
HERCULES_RC
" environment variable is used. If no environment variable is defined, the default value "hercules.rc" is used. If the default "hercules.rc" file is not found, then the value "none" is used, indicating an .rc file will not be used.
logofile
- is the name of the Hercules logo file. The logo file is the initial welcome screen presented when a TN 3270 terminal connects to a hercules 3270 device.
--daemon
(deprecated)- This option has been deprecated due to its confusing name. Please use the below
'--NoUI'
option instead.
--NoUI
- specifies that Hercules is to be run invisibly in "No User Interface" mode, wherein it runs in the backgroud without any attached console or keyboard.
Please Note that Hercules's "No User Interface mode" is not the same as e.g. Linux's daemon mode. It is quite different. Refer to our "Running Hercules in "No User Interface" mode" web page for more information.
--externalgui
- indicates Hercules is to be controlled by an External GUI.
modpath
- is the directory from which dynamic modules are to be loaded. This option overrides both the
MODPATH
configuration file statement and system defaults. The system default varies depending on the host platform where Hercules is being run.
modname
- is the name of an additional dynamic module to be loaded at startup. More than one additional module may be specified, although each must be preceded with the
-l
option specifier.
symbol=value
- the name of a symbol and its associated value to be used in configuration file processing or panel commands. See the command 'defsym' for more information on using symbols. The '-s' option may be repeated. Note: 'value' may be quoted to contain embedded blanks.
--verbose
- sets the message-level to verbose. This is the same as entering the command
msglvl +verbose
.
--help[=type]
- displays help regarding the syntax of command-line arguments and, optionally, other information as well if the optional help
type
is also specified.The optional
type
value identifies what type of help you want to display. Valid values are:short
,long
,version
orbuild
. Additionally,all
andfull
are also accepted as aliases forlong
.The
short
help option displays just the syntax of the the command line arguments. Theversion
help option displays version information. Thebuild
option displays some of the more important optional features that Hercules was either built with or without. Thelong
,all
andfull
options displays all three types. The default isshort
(i.e. only the command-line syntax is shown).
--test[=factor]
- starts Hercules in test mode, activating special .rc file script commands used only by QA test scripts. Normal Hercules use should never specify this switch.
factor
is an optional test timeout factor within the range 1.0 to 14.3. The test timeout factor is used to adjust each test script's specified timeout value to compensate for the speed of the system on which they are running.Use a factor greater than 1.0 on slower systems to slightly increase timeout values giving each test more time to complete.
Please note that due to manner in which command line arguments are parsed this option must be specified as one argument. Thus "-t2.0" is correct whereas "-t 2.0" is not. Oftentimes it is easier to use the long
--test=factor
syntax instead.Test timeout values (specified as optional arguments on the special runtest script command) are a safety feature designed to prevent runaway tests from never ending. Normally tests end automatically the very moment they are done.
logfile
- is the name of the optional (but highly recommended!) log file. The log file receives a copy of all messages displayed on the control panel and is extremely important to have for problem analysis and bug reporting.
Next connect a tn3270 client to the console port (normally port 3270). The client will be connected to the first 3270 device address specified in the configuration file (this should be the master console address). If your master console is a 1052 or 3215, connect a telnet client instead of a tn3270 client.
Now you can enter an ipl command from the control panel.
In the default "panel" operating mode, the main Hercules screen contains a scrollable list of messages with a command input area and system status line at the bottom of the screen. (see further above)
To scroll through the messages, use either the Page Up or Page Down keys, the Ctrl + Up Arrow or Ctrl + Down Arrow keys, or the Home or End and/or the Ctrl + Home or Ctrl + End keys.
Use the Insert key to switch between insert and overlay mode when typing in the command input area. Use the Home and End keys to move to the first or last character of the command you are typing, or the use the left/right arrow keys to move to a specific character. Use the Escape key to erase the input area.
Pressing Escape when the command input area is already empty causes the screen to switch to the semi-graphical "New Panel" display mode, which shows the overall status of the system and devices.
When in the semi-graphical "New Panel" display mode there is no command input
area. Instead, single character "hot keys" are used to issue some of the more
common functions such as starting or stopping the CPU. The hot-keys are those
which are highlighted. Pressing the '?' key displays brief help information
on how to use the semi-graphical panel.
Normal cursor handling | |
---|---|
Key | Action |
Esc | Erases the contents of the command input area. If the command input area is already empty, switches to semi-graphical New Panel. |
Del | Deletes the character at the cursor position. |
Backspace | Erases the previous character. |
Insert | Toggles between insert mode and overlay mode. |
Tab | Attempts to complete the partial file name at the cursor position in the command input area. If more than one possible file exists, a list of matching file names is displayed. |
Home | Moves the cursor to the start of the input in the command input area. If the command input area is empty, scrolls the message area to the top. |
End | Moves the cursor to the end of the input in the command input area. If the command input area is empty, scrolls the message area to the bottom. |
Page Up | Scrolls the message area up one screen. |
Page Down | Scrolls the message area down one screen. |
Up arrow | Recalls previous command into the input area. |
Down arrow | Recalls next command into the input area. |
Right arrow | Moves cursor to next character of input area. |
Left arrow | Moves cursor to previous character of input area. |
Ctrl + Up arrow | Scrolls the message area up one line. |
Ctrl + Down arrow | Scrolls the message area down one line. |
Ctrl + Home | Scrolls the message area to the top. |
Ctrl + End | Scrolls the message area to the bottom. |