My experience of building Hercules from source on Ubuntu Linux ============================================================== Author: Dave Edwards Original date: Jun 25, 2007 Last updated: Jun 25, 2007 (c) Copyright by Dave Edwards, 2007. All rights reserved. I would like to share my experience of building Hercules 3.04.1 from source on Ubuntu Linux. Hercules (www.hercules-390.org) is an open-source application that emulates an IBM S/370 or ESA/390 mainframe computer. 1. Installing Linux 2. Building Hercules from the source 3. Using Hercules - - - - - - - 1. Installing Linux ------------------- I installed the workstation version of Ubuntu 6.06 (also called "Dapper Drake") from a bootable CD, on a Pentium III machine with 256 MB of memory, an 800 MHz processor, and a 20 GB hard disk. Ubuntu workstation provides a graphical desktop (GNOME) similar to Windows, The Linux kernel is version 2.6.15. Originally the machine's Windows 2000 system occupied all of the disk, so I used the free gparted 0.3-1 (http://gparted.sourceforge.net) live (i.e. bootable) CD to reduce the size of the Windows partition, to make room for a 1 GB Linux swap partition and a 9 GB Linux root (ext3 file system) partition. Both are "primary" partitions; their "mount points" are "swap" and "/" (root), respectively; you create them during the Ubuntu install. My Windows partition is FAT32, but reportedly gparted can also resize NTFS partitions. Before using gparted, it was necessary to do some file cleanup on Windows (delete temporary files and some large files or temporarily copy them to another machine) and defragment the C: drive a couple of times. It's also a good idea to make backup copies of any important files. Linux is dual-boot with Windows, using the GRUB loader that Ubuntu installs. In such a setup, be sure to install Linux AFTER installing Windows. Otherwise a Windows install may wipe out the Linux GRUB entry. The Ubuntu install is fairly simple. Be sure to select "Manually edit partition table". This lets you create the Linux partitions without wiping out Windows. After installing Ubuntu, reboot and use the GUI desktop to customize some things, such as your ethernet network settings, screen resolution, etc. The text editor command in Ubuntu is gedit, which is similar to Notepad in Windows. Immediately after install, Ubuntu occupied about 2.5 GB of the root partition, leaving about 6.5 GB free. I installed Ubuntu from a bootable CD that dates from June 2006. You can ask www.ubuntu.com for a free copy to be mailed to you, or you can download it. Ubuntu is based on Debian Linux. There is also a server version of Ubuntu, but I wanted the graphical desktop. However, this means you do not automatically have tools such as the gcc C compiler, make, ftpd, etc. Some of them can be installed from the Ubuntu CD: Start up the Synaptic Package Manager (in System / Admin), place the CD in the drive, click on "Add CDROM", and "Reload". The new packages available from the CD will then be listable in Synaptic. Don't forget to click on "Apply" after selecting the packages for install. I installed GNU make (3.80+3.81.b4-1), gcc (4.0.3-1ubuntu5), and g++ (4:4.0.3-1). This automatically installs a few other "dependencies" (packages required by those packages). Note on g++: It's not obvious that you need the g++ compiler (GNU C++ language) for building Hercules. As far as I can see, none of the Hercules source uses C++. But, without it, the ./configure step (see below) fails. If anyone's interested, here's the last part of the configure output I got on my first try: checking whether we are using the GNU C++ compiler... no checking whether g++ accepts -g... no checking dependency style of g++... none checking how to run the C++ preprocessor... /lib/cpp configure: error: C++ preprocessor "/lib/cpp" fails sanity check See 'config.log' for more details. So I went back and installed the g++ package from the Ubuntu CD, then ./configure worked. I should tell you that my Linux machine is not connected to the Internet, but is connected to my main Windows XP machine via my local LAN. Ubuntu supports Windows file sharing, and can access the files on my Windows main machine. So, to install other packages, I download the package files (.deb) to Windows XP and then copy them to Ubuntu. Ubuntu uses the Debian package infrastructure, but has its own versions of most packages. In fact, because of dependencies, it is best to stick with the packages for your version of Ubuntu (in my case, Dapper). Later versions are Edgy, Feisty, and Gutsy. If you try packages from later versions, you often find that they depend on a higher version of libc6 (the C run-time library) than you have. I suspect some of these dependencies are bogus, but a package will refuse to install if its dependencies are not satisfied. This can be a pain! It seems best not to replace your libc6 (Dapper's is 2.3.6-0Ubuntu20). Almost all other programs depend on libc6. I have seen several horror stories on the Ubuntu discussion groups of broken systems resulting from attempts to upgrade libc6. The best repository for Ubuntu packages seems to be http://packages.ubuntu.com. Unfortunately, the Ubuntu home page www.ubuntu.com does not currently tell you this, for some strange reason, and the Synaptic package manager in Ubuntu (6.06 anyway) does not automatically use it. I found that my MSIE 6.0 browser does not display a package's dependencies list correctly: not all the bullets are displayed and the icons do not line up. The Firefox browser gets it right. With MSIE you can see a better display by saving a local copy of the page (html only) and then opening the local copy. After downloading a package's .deb file, install it by the command: sudo dpkg -i xxx.deb Note the use of the "sudo" command to run a command that needs root privileges. Ubuntu uses this instead of requiring you to log on to the root id. Be sure to check the package's dependencies and install those first, if Synaptic says you do not already have them. Something else to watch out for is that, for a given package xxx, there is often a development version of the package called xxx-dev, which provides .h, .a and .so files needed if you are compiling and linking a program that uses the package. So you may need both. For example, if a gcc command uses the linker option -lyyy, you need the shared library file libyyy.so (usually in /lib or /usr/lib directory). Often the libyyy.so is actually a symbolic link to a version-specific library file. By the way, in order to compile and link a C program that uses math functions such as sqrt(), sin(), exp(), you need to use the -lm option on the gcc command. In addition to the packages (see above) from the Ubuntu CD, I downloaded and installed the following packages: - ssl-cert_1.0.13_all.deb (needed by vsftpd) - vsftpd_2.0.4-0ubuntu4_i386.deb (FTP server) - openssh-server_4.2p1-7ubuntu3_i386.deb - zlib1g-dev_1.2.3-6ubuntu4_i386.deb - gawk_3.1.5-2build1_i386.deb - m4_1.4.4-1_i386.deb (needed by flex) - flex_2.5.31-38ubuntu1_i386.deb - autoconf_2.59a-7_all.deb (needed by automake) - autotools-dev_20050803.1_all.deb (needed by automake) - automake1.9_1.9.6-1_all.deb - libbz2-dev_1.0.3-0ubuntu2_i386.deb - libgpg-error-dev_1.1-4_i386.deb (needed by libgcrypt11-dev) - libgcrypt11-dev_1.2.2-1_i386.deb - libgcrypt11-doc_1.2.2-1_all.deb (documentation) To configure vsftpd or openssh-server on Linux, see the documentation or man files that come with them. To control the server program (daemon), use the command "sudo /etc/init.d/xx yy" where xx is the program (vsftpd or ssh) and yy is one of the options stop, start, or restart. For example, a restart is needed after changing the program's configuration file. For file transfer and a remote terminal shell, I use the SSH Secure Shell client 3.2.9 for Windows (www.ssh.com). This works well with the openssh-server (which listens on TCP port 22) that I installed on Ubuntu. This lets me do most of my Linux work remotely, from my main Windows XP machine. It can even correctly handle conversion of line endings between Windows (CRLF) and Unix (LF) for text files; be careful with make files, however! The Hercules documentation says that cvs (a source control and versioning system) is needed for Hercules build, but cvs is not needed unless you want to download the latest bleeding-edge source. Also, the libiconv package it refers to is actually the iconv command, which my Ubuntu system already has (version 2.3.6). 2. Building Hercules from the source ------------------------------------ I downloaded file hercules-3.04.1.tar.gz from the Hercules home page and copied it to a subdirectory called installs of my Ubuntu home directory. (For use on Linux, 3.04.1 seems to be equivalent to 3.04; version 3.04.1 only adds a fix needed for Mac systems.) Change to that installs directory, and enter the following command to unpack the files: tar -xzf hercules-3.04.1.tar.gz The "-" before the options can be omitted. You can also add the v (verbose) option if you like (-xvzf), which lists the (many) file names. Note: you can also use WinZip (or similar) on Windows to extract and view the files (for example the INSTALL and README files and the html documentation), but do not use such extracted files directly on Linux, since (by default) WinZip converts line endings when extracting text files from a tar archive. A note about precompiled Hercules packages for Linux: Depending on your particular Linux system, you may be able to install a Hercules package (.rpm, .deb, etc.), instead of building it from the original source. That may be easier, but then you loose the customization and possible optimization done by the configure program (see below), and you have to worry about package dependencies. For example, in my case, I found a .deb package for Ubuntu Dapper, but it was an older version (3.03.1) of Hercules. I also found a Hercules 3.04.1 .deb package for Ubuntu Gutsy, but that would have required upgrading my libc6, which I preferred not to do. The tar command creates a subdirectory called hercules-3.04.1, containing all the extracted files. Change to that subdirectory, then enter the command: ./configure The very large and complex configure program uses the autoconf/automake utilities to examine your Linux machine and software components. Based on what it finds, if there are no errors, it creates various Makefile files and the config.h header file (settings for the compiles). It took a couple of minutes to run. The configure program is powerful, but also complicated. If something goes wrong, it may not be obvious how to fix it. If, like me, you had never heard of autoconf and automake before building Hercules, the learning curve is steep if you want to really understand it. It makes me nostalgic for the old days when a software project consisted of a few .c and .h files and a relatively simple makefile, and all you had to do was (possibly) adjust a few #define's in one of the .h files and run "make". The next step is to compile and build all the Hercules components, using the files which configure generated. You do this by the command: make This took about 40 minutes on my system. I expect a more modern machine would be considerably faster. Assuming there were no errors from the above (you may see a few compiler warnings flash by), the final step in the build is to copy the various executables, libraries, and documentation files from your working directories to the appropriate system directories (normally /usr/local/lib, /usr/local/bin, /usr/local/share). You do this by the command: sudo make install This is quick, only a minute or so. You can then do a brief test by entering the command hercules with no parameters, which should display some version and build info, and then stop because no Hercules config file was specified. 3. Using Hercules ----------------- Once Hercules is installed on Linux, using it is very similar to usage under Windows. You must prepare a configuration file for the mainframe operating system you want to run, and set up disk volume files for the operating system. Refer to the documentation on the Hercules home page, or the html files it installed in the /usr/local/share/hercules directory. Various mainframe operating systems are available for running under Hercules, including OS/360, MVS 3.8, DOS/VS, VM/370, and MUSIC/SP. In the config file, of course, use Linux-style path names for the volume files, e.g. /home/dave/myherc/musicx.vol. If you change any of the tcp/ip port numbers, it is advisable to use numbers higher than 1024, so that Hercules does not need root privileges to listen on them. You can enable the built-in web server that is part of Hercules, and serve files from a specified web root directory of Linux. This is done by the HTTPPORT and HTTPROOT commands in the config file. You will also need a telnet client for the operator console of the mainframe system you are running under Hercules, and a tn3270 client for logging in to your mainframe system after it is IPL'ed. For the telnet client, I usually use Windows telnet.exe, with local echo on: "set localecho", then "open herculesipaddr portnumber". For the tn3270 (telnet 3270) client, various free ones are available for Windows and Linux. The command to start Hercules is: hercules -f configfilename - - - - - - -