.. _how-to-compile-the-software: Compiling and installing from source ==================================== .. note:: 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. .. rubric:: 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: * ``EXTERN_BOOST_INCLUDE_PREFIX`` * ``EXTERN_BOOST_LIB_PREFIX`` * ``EXTERN_PUGIXML_INCLUDE_PREFIX`` * ``EXTERN_PUGIXML_LIB_PREFIX`` E.g: .. code-block:: sh make EXTERN_BOOST_INCLUDE_PREFIX=/path/to/boost/include EXTERN_BOOST_LIB_PREFIX=/path/to/boost/lib .. rubric:: 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. Instructions ------------ 1. **Install the prerequisites**, as discussed above. For example: * **SLC6**: Building BOOST and pugiXML from archive files in repository .. code-block:: sh 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 .. code-block:: sh 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 .. code-block:: sh 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 .. code-block:: sh 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) .. code-block:: sh 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** .. code-block:: sh git clone --depth=1 -b v2.8.13 --recurse-submodules https://github.com/ipbus/ipbus-software.git cd ipbus-software make .. note:: 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 Description Default value ===================== =============================================================================================== ====================== ``Set`` Selects which main components will be built; possible values: ``all``, ``controlhub``, ``uhal`` ``all`` ``BUILD_UHAL_GUI`` Selects whether Python GUI built (``O`` or ``1``) ``1`` ``BUILD_UHAL_PYTHON`` Selects whether Python bindings built (``O`` or ``1``) ``1`` ``PYTHON`` Sets name/path of Python command used; determines Python version for which bindings are built ``python`` ``CXX`` Compiler command ``g++`` ``CXXFLAGS`` Flags for compilation ``LD`` Linker command ``${CXX}`` ``LDFLAGS`` 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: .. code-block:: sh make rpm sudo yum localinstall `find . -iname "*.rpm"` Otherwise, run the following distribution-agnostic install command: .. code-block:: sh sudo make install .. note:: 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 Description Default value =============== ================================================= ====================== ``prefix`` Root install directory ``/opt/cactus`` ``exec_prefix`` Root install directory for libraries and binaries ``$(prefix)`` ``bindir`` Directory containing binaries and scripts ``$(exec_prefix)/bin`` ``libdir`` Directory containing libraries ``$(exec_prefix)/lib`` ``includedir`` Directory containing C++ header files ``$(prefix)/include`` ``sysconfdir`` Directory containing additional config/test files ``$(prefix)/etc`` =============== ================================================= ====================== For example, to install it under ``/opt/another-directory``: .. code-block:: sh sudo make install prefix=/opt/another-directory Or, to install the headers under ``/usr/local/include``, but all other files under ``/opt/another-directory``: .. code-block:: sh sudo make install prefix=/opt/another-directory includedir=/usr/local/include