13. Building HammerDB from Source

Before building from source be aware that HammerDB already provides pre-compiled packages from the download page and therefore building from source is not required to run HammerDB. Instead building from source is for people who want to compile all of their own dependencies from the C code that HammerDB is built in.

Building from source also enables building a distribution with commits ahead of the current HammerDB release.

When building from source all of the dependent packages will be downloaded from www.hammerdb.com.

HammerDB build automation uses an adapted version of the BAWT package by Paul Obermeier . BAWT is copyrighted by Paul Obermeier and distributed under the 3-clause BSD license.

13.1. Compiler & Dependency Install on Linux

Install a development environment using the gcc compiler for Linux. You will also need the p7zip tool as well as the Xft font library and Cairo graphics development packages.  The build has been tested on x64 Red Hat 8.X and Ubuntu 20.04.X Linux, with the following example from Red Hat Linux.

yum install p7zip-16.02-20.el8.x86_64.rpm
sudo yum install libXft-devel
yum group install "Development Tools"

The HammerDB Oracle and ODBC for SQL Server client libraries will build without the respective Oracle and SQL Server client libraries, but will need them at runtime. However, the client or server must be installed for all of Db2, MariaDB, PostgreSQL and MySQL for the HammerDB build to be successful. The database installation must include both the include and lib directories. For Db2 either the server or client can be installed, for example v11.5.7_linuxx64_server_dec.tar.gz. HammerDB build automation will look for the Db2 installation in the location of the environment variable IBM_DB_DIR set using db2profile tool. Verify that this has been set as follows:

$ echo $IBM_DB_DIR
/home/ibm/sqllib

On Linux MariaDB, PostgreSQL and MySQL include a config command in the bin directory that returns details of the configuration. HammerDB uses these commands to find the headers and libraries needed for the build. Before running the build, environment variables MARIADB_CONFIG, PG_CONFIG and MYSQL_CONFIG must be set to the location of the respective config commands for each database in the terminal running the build.

$ export MARIADB_CONFIG=/opt/mariadb/mariadb-10.6.7-linux-systemd-x86_64/bin
$ export PG_CONFIG=/opt/postgresql/bin
$ export MYSQL_CONFIG=/opt/mysql/mysql-8.0.28-linux-glibc2.12-x86_64/bin

In addition the source build will expect to find the python3 and python3-config executables that would typically already be installed on a Linux system with for example python3 being installed by the python3-minimal package and python3-config by the python3-dev package on Ubuntu.

13.2. Compiler & Dependency Install on Windows

On Windows, download and install Visual Studio 2022, Visual Studio is free for open source developers. An additional gcc compiler will be downloaded and installed locally during the build. The build has been tested on x64 Windows 10 and 11. As with Linux it is also mandatory to install a database server or client including the development environment of headers and libraries for MariaDB, Db2, MySQL and PostgreSQL. For Db2 on Windows, there is no db2profile that sets the environment therefore the IBM_DB_DIR environment variable must be set to the location of the Db2 install. Similarly, the MariaDB and MySQL config commands are not available on Windows either and should also be set to the database or client installation directory rather than the bin directory. PostgreSQL for Windows does include the config command and therefore the environment configuration is the same as Linux. The source build will also require a Python installation from https://www.python.org/, this installation will need the include and libs directory for compilation and the Python DLL which is in the Python home directory at runtime. In the following example the PYTHONHOME environment variable should be set to C:\Users\username\AppData\Local\Programs\Python\Python310.

C:\Users\username\AppData\Local\Programs\Python\Python310
C:\Users\username\AppData\Local\Programs\Python\Python310\include
C:\Users\username\AppData\Local\Programs\Python\Python310\libs

With the following settings for all environments variables for the build.

set MARIADB_CONFIG=C:\Program Files\MariaDB\MariaDB Connector C 64-bit
set MYSQL_CONFIG=C:\Program Files\MySQL\MySQL Server 8.0
set PG_CONFIG=C:\Program Files\PostgreSQL\pgsql\bin
set IBM_DB_DIR=C:\Program Files\IBM\SQLLIB
set PYTHONHOME=C:\Users\username\AppData\Local\Programs\Python\Python310

For all database installations on Windows whether client or server verify that the installation has the include, bin and lib directories. On Windows in particular, some installations may not include all the required files for development.

13.3. Download HammerDB Source

At this stage you will have installed the compiler you need and database client/server installations for MariaDB, Db2, MySQL and PostgreSQL. To reiterate, HammerDB will not build correctly unless you have installed ALL the required database environments. Next download HammerDB from gitHub by either cloning or downloading. From the main HammerDB GitHub page use the clone URL or the Download Zip link from the master branch.

Figure 1.28. Download Source

Download Source

$ git clone https://github.com/TPC-Council/HammerDB.git
Cloning into 'HammerDB'...
remote: Enumerating objects: 8099, done.
remote: Total 8099 (delta 0), reused 0 (delta 0), pack-reused 8099
Receiving objects: 100% (8099/8099), 40.41 MiB | 8.39 MiB/s, done.
Resolving deltas: 100% (2564/2564), done.

If cloning you will have a directory called “HammerDB” or extracting the zipfile a directory called “HammerDB-master”.

13.4. Running the Build

Navigate to the Build\Bawt-2.1.0 directory with the command line for both Linux and Windows. Note that during the build an InputLibs directory will be created and all HammerDB libraries downloaded and under the Build directory a BawtBuild directory will be created where the installation will take place. Therefore, sufficient disk space and permissions must be available for the build to take place. Within the command line you are running the build make sure that you have correctly set all the MARIADB_CONFIG, MYSQL_CONFIG, PG_CONFIG, and IBM_DB_DIR environment variables used during the build and run the Build-Linux.sh command for Linux.

./Build-Linux.sh x64 Setup/HammerDB-Linux.bawt update

and make sure PYTHONHOME is set to the correct directory of the Python installation and run the Build-Windows.bat commands for Windows

./Build-Windows.bat x64 vs2022+gcc Setup/HammerDB-Windows.bawt update

the command sequence will look similar to the following on Linux:

$ export MYSQL_CONFIG=/opt/mysql-8.0.20-linux-glibc2.12-x86_64/bin
$ export MARIADB_CONFIG=/opt/mariadb-10.8.1-linux-x86_64/bin/
$ export PG_CONFIG=/opt/postgresql-14.1/bin
$ echo $IBM_DB_DIR
/opt/ibm/sqllib
$ ./Build-Linux.sh x64 Setup/HammerDB-Linux.bawt update

and the following on Windows:

set MARIADB_CONFIG=C:\Program Files\MariaDB\MariaDB Connector C 64-bit
set MYSQL_CONFIG=C:\Program Files\MySQL\MySQL Server 8.0
set PG_CONFIG=C:\Program Files\PostgreSQL\pgsql\bin
set IBM_DB_DIR=C:\Program Files\IBM\SQLLIB
set PYTHONHOME=C:\Users\username\AppData\Local\Programs\Python\Python310
Build-Windows.bat x64 vs2022+gcc Setup\HammerDB-Windows.bawt update

The first step the build will take is to download the required packages and build instructions from www.hammerdb.com, On Windows the MYSYS/MinGW package will also be downloaded. These will be stored in the Bawt-2.1.0/InputLibs directory. Both checksums and modification times are verified with the remote packages. If a package is already present with the same checksum and modification time, it will not be downloaded again if already present. Also some packages such as Tcl have been modified from the original and therefore only the packages from www.hammerdb.com should be used. In some cases different packages are used on Linux and Windows and therefore the package listing differs between the OS environments, this is expected and the following listing shows a Linux example.

awthemes-9.3.1.7z  libressl-2.6.4.7z  pgtcl-2.1.1.7z  tcltls-1.7.22.7z
awthemes.bawt      libressl.bawt      pgtcl.bawt      tcltls.bawt
clearlooks-1.0.7z  mariatcl-0.1.7z    redis-0.1.7z    Tk-8.6.12.7z
clearlooks.bawt    mariatcl.bawt      redis.bawt      Tk.bawt
db2tcl-2.0.1.7z    mysqltcl-3.052.7z  Tcl-8.6.12.7z   tkblt-3.2.23.7z
db2tcl.bawt        mysqltcl.bawt      Tcl.bawt        tkblt.bawt
expect-5.45.4.7z   oratcl-4.6.7z      tclpy-0.4.7z    tksvg-0.5.7z
expect.bawt        oratcl.bawt        tclpy.bawt      tksvg.bawt

Allow the build to complete. A summary will be given of the packages built and the location of the build given, for example for Linux as follows:

17:31:43 > Creating Distribution tar.gz in /opt/HammerDB-master/Build/BawtBuild/Linux/x64/Release/Distribution
17:31:43 >   TarGzip
               Source directory: /opt/HammerDB-master/Build/BawtBuild/Linux/x64/Release/Distribution/HammerDB-4.6
               Tar file        : /opt/HammerDB-master/Build/BawtBuild/Linux/x64/Release/Distribution/HammerDB-4.6-Linux.tar.gz
17:31:43 > End FinalizeStage

17:31:43 > Summary
           Setup file     : /opt/HammerDB-master/Build/Bawt-2.1.0/Setup/HammerDB-Linux.bawt
           Build directory: /opt/HammerDB-master/Build/BawtBuild/Linux/x64/Release/Build
           Architecture   : x64
           Compilers      : gcc
           Global stages  : Finalize
           #  : Library Name         Version    Build time      Stages
           ----------------------------------------------------------------------
             1: Tcl                  8.6.12     1.54 minutes    Clean Extract Configure Compile Distribute
             2: Tk                   8.6.12     0.36 minutes    Clean Extract Configure Compile Distribute
             3: awthemes             9.3.1      0.00 minutes    Clean Extract Configure Compile Distribute
             4: clearlooks           1.0        0.00 minutes    Clean Extract Configure Compile Distribute
             5: db2tcl               2.0.1      0.10 minutes    Clean Extract Configure Compile Distribute
             6: expect               5.45.4     0.12 minutes    Clean Extract Configure Compile Distribute
             7: libressl             2.6.4      0.94 minutes    Clean Extract Configure Compile Distribute
             8: mariatcl             0.1        0.04 minutes    Clean Extract Configure Compile Distribute
             9: mysqltcl             3.052      0.04 minutes    Clean Extract Configure Compile Distribute
            10: oratcl               4.6        0.05 minutes    Clean Extract Configure Compile Distribute
            11: pgtcl                2.1.1      0.05 minutes    Clean Extract Configure Compile Distribute
            12: redis                0.1        0.00 minutes    Clean Extract Configure Compile Distribute
            13: tclpy                0.4        0.01 minutes    Clean Extract Configure Compile Distribute
            14: tcltls               1.7.22     0.18 minutes    Clean Extract Configure Compile Distribute
            15: tkblt                3.2.23     0.21 minutes    Clean Extract Configure Compile Distribute
            16: tksvg                0.5        0.05 minutes    Clean Extract Configure Compile Distribute
           ----------------------------------------------------------------------
           Total: 3.70 minutes

On Windows a graphical viewer monitors the progress of the build.

Figure 1.29. Windows build

Windows build

On Windows both Visual Studio and gcc compilers are used with Visual Studio for performance critical packages (i.e. Tcl, Tk and databases interfaces) and gcc for other packages. For this reason Tcl and Tk are compiled twice with both Visual Studio and gcc for the respective dependent packages to be compiled against, however the final distribution only includes the Tcl and Tk builds compiled with Visual Studio. For this reason the Windows build takes more time than the comparative Linux build.

You now have your own distribution of HammerDB with the latest source code.

This will be in the following directory on Linux:

HammerDB/Build/BawtBuild/Linux/x64/Release/Distribution

and the following directory on Windows:

HammerDB-master\Build\BawtBuild\vs2022\x64\Release\Distribution

Note that the entire distribution including the HammerDB source is built and installed in this directory and therefore you should run or copy the distribution from this location. If trying to run HammerDB from the HammerDB source root directory it will not run correctly instead copy or run the built distribution from the locations above.

Alongside the HammerDB distribution directory is also a tar.gz file on Linux and zip file on Windows of the directory.

You can run the hammerdbcli librarycheck command to verify that the libraries built correctly.

/opt/HammerDB/Build/BawtBuild/Linux/x64/Release/Distribution$ ls
HammerDB-4.6  HammerDB-4.6-Linux.tar.gz
$ cd HammerDB-4.6
/opt/HammerDB/Build/BawtBuild/Linux/x64/Release/Distribution/HammerDB-4.6$ ./hammerdbcli
HammerDB CLI v4.6
Copyright (C) 2003-2022 Steve Shaw
Type "help" for a list of commands
hammerdb>librarycheck
Checking database library for Oracle
Success ... loaded library Oratcl for Oracle
Checking database library for MSSQLServer
Success ... loaded library tdbc::odbc for MSSQLServer
Checking database library for Db2
Success ... loaded library db2tcl for Db2
Checking database library for MySQL
Success ... loaded library mysqltcl for MySQL
Checking database library for PostgreSQL
Success ... loaded library Pgtcl for PostgreSQL
Checking database library for MariaDB
Success ... loaded library mariatcl for MariaDB

You can also browse all of the C source code for the libraries you have built in the Build directory for example:

HammerDB/Build/BawtBuild/Linux/x64/Release/Build

13.5. HammerDB License

HammerDB is copyrighted and distributed under the GNU General Public License Version 3.0 (GPL v3). When building from source this copyright remains and any distributions must be made under GPLv3 complying to the following requirements.

1. Include a copy of the full license text

2. State all significant changes made to the original software

3. Make available the original source code when you distribute any binaries based on the licensed work

4. Include a copy of the original copyright notice

it is not permitted to modify the license on a build from source distribution.