Compiling and installing from source


The IPbus software source code only needs to be compiled by end-users if you’re using an operating system for which an YUM repositories are not currently provided, or if the uHAL libraries must be compiled using a different version of compiler, boost, or pugixml than is used to create the RPMs.

Prerequisites for uHAL

The uHAL libraries are implemented in C++, built on top of the BOOST and pugiXML libraries, and should work successfully with the following versions:

  • BOOST: v1.53.0 onwards

  • pugiXML: v1.8 onwards

We suggest that you use the system version of these libraries (i.e. the default version that can be installed with your operating system) provided that the system version of that library satisfies the constraints listed above - unless of course, other versions must be used for compatibilty with experiment/other frameworks. Finally, in order to compile uHAL, the header files for Python must be also be installed.

Specifying header and library paths for BOOST and pugiXML

If the BOOST or pugiXML header files and/or libraries that you want to use are not installated under the standard paths, then you can specify the corresponding include paths when compiling uHAL using the following makefile variables:






make EXTERN_BOOST_INCLUDE_PREFIX=/path/to/boost/include EXTERN_BOOST_LIB_PREFIX=/path/to/boost/lib

Building BOOST/pugiXML from archives in git repository

The IPbus software git repository contains the source code for BOOST v1.53 and pugiXML v1.2; by default, these versions are only compiled and used on SLC6, but in case you’re using another OS on which the system versions of BOOST and/or pugiXML are older than 1.48 or 1.0 respectively, you can force these versions to be built and used by setting the BUILD_BOOST and/or BUILD_PUGIXML make variables to 1 - e.g. make BUILD_PUGIXML=1.

Prerequisites for the ControlHub

The ControlHub is implemented in Erlang. We recommend using the system version of Erlang to compile the ControlHub, provided that it is equal to or higher than major version R16B01.

Choosing what you build

By default, both uHAL and the ControlHub are built/installed when running make from the top-level directory of the git repository. If you only want to build uHAL, then you should add Set=uhal at the end of any make commands that you run; conversely, if you only want to build the ControlHub, you should add Set=controlhub to your make commands.


  1. Install the prerequisites, as discussed above. For example:

    • SLC6: Building BOOST and pugiXML from archive files in repository

      sudo yum -y install make tar rpm-build git-core m4 gcc-c++ zlib-devel bzip2-devel ncurses-devel openssl-devel python-devel
    • CentOS7: System version of BOOST, pugiXML & Erlang

      sudo yum -y install make rpm-build git-core erlang gcc-c++ boost-devel pugixml-devel python-devel
    • CentOS8: System version of BOOST, pugiXML & Erlang

      sudo dnf -y install make rpm-build git-core erlang gcc-c++-8.* boost-devel pugixml-devel    python36-devel

      You may want to change python36-devel to python38-devel for example, if you want to build the uHAL Python bindings for a different Python version.

    • Debian 9: System version of BOOST, pugiXML & Erlang

      sudo apt-get install make erlang g++ libboost-all-dev libpugixml-dev python-all-dev
    • Ubuntu 16: System version of BOOST, pugiXML & Erlang (the touch commands fix a minor bug in the Ubuntu 16 packaging of Erlang)

      sudo apt-get install -y make erlang g++ libboost-all-dev libpugixml-dev python-all-dev rsyslog
      sudo touch /usr/lib/erlang/man/man1/x86_64-linux-gnu-gcov-tool.1.gz
      sudo touch /usr/lib/erlang/man/man1/gcov-tool.1.gz
  2. Checkout from git and compile

    git clone --depth=1 -b v2.8.13 --recurse-submodules
    cd ipbus-software


    You can customise the build process in a number of ways by specifying one of the following variables by setting one of the variables for the above make command (e.g. make Set=uhal)

    Variable name


    Default value


    Selects which main components will be built; possible values: all, controlhub, uhal



    Selects whether Python GUI built (O or 1)



    Selects whether Python bindings built (O or 1)



    Sets name/path of Python command used; determines Python version for which bindings are built



    Compiler command



    Flags for compilation


    Linker command



    Flags for linker commands

  3. Install the software

    If you’re using an RPM-based linux distribution (e.g. red hat / CentOS), then create and install the RPMs, as follows:

    make rpm
    sudo yum localinstall `find . -iname "*.rpm"`

    Otherwise, run the following distribution-agnostic install command:

    sudo make install


By default, sudo make install will install uHAL and the ControlHub within /opt/cactus; if you want to install the files in another directory, you can set the values of one of the following make variables:

Variable name


Default value


Root install directory



Root install directory for libraries and binaries



Directory containing binaries and scripts



Directory containing libraries



Directory containing C++ header files



Directory containing additional config/test files


For example, to install it under /opt/another-directory:

sudo make install prefix=/opt/another-directory

Or, to install the headers under /usr/local/include, but all other files under /opt/another-directory:

sudo make install prefix=/opt/another-directory includedir=/usr/local/include