Building Xerus

Obtaining Xerus

You can get the source-code of the xerus library via git or as an archiv. For example to clone the repository with the latest stable version under linux simply type

git clone https://git.hemio.de/xerus/xerus.git

Dependencies and Configuration

Xerus depends on several well established libraries, usually pre-installed or available through the standard package managers. In particular lapacke, CXSparse, binutils, boost and their dependencies. Also note that at least version 4.8 of the GCC is required, as this is the first version to offer support for all C++11 functionality used in xerus. Make sure that all these are installed on your system before proceeding.

E.g. to install all dependencies on a fedora system execute

dnf install gcc-c++ openblas-devel suitesparse-devel lapack-devel boost-devel binutils-devel

To build the python bindings you will furthermore need the python development headers, numpy as well as boost-python or boost-python3 depending on the python version you wish to use. E.g. for a fedora system and if you want to use python 2 simply execute

dnf install python2-numpy python-devel

To build the documentation (i.e. this homepage) locally you will need jekyll and doxygen.

After downloading the source it is necessary to set a number of options that are somewhat individual to your system and needs. All following build steps assume that these options are set in the config.mk file. Reasonable default values can be found in the config.mk.default file.

In particular the optimization level is interesting and the paths or standard flags for the required libraries need to be set. This way the xerus library can be compiled with any blas compatible library for the matrix operations. For more details see the description in the config.mk.default file

cp config.mk.default config.mk
nano config.mk

Ensure Everything Works as Intended

The sources include a number of unit tests that ensure that everything works as intended. To perform them simply input

make test -j4

(where -j4 allows make to use up to 4 threads for the compilation). If all options were set correctly in the config.mk it should compile a test executable and launch it. The output of this executable should then list a number of passed tests and end with something similar to

|
|                       total summary 149 of 149 passed
-------------------------------------------------------------------------------
|
|                       Total time elapsed: 5594.088 ms
-------------------------------------------------------------------------------

Note in particular, that all tests were passed. Should this not be the case please file a bug report with as many details as you can in our issuetracker or write us an email.

Building the Library

If all tests were passed you can build the library simply by calling make shared or make static depending on whether you want to build shared or static library objects. To build all shared objects as well as the python bindings use make python. After the compilation you should have a build/ directory with a libxerus_misc.a/.so (suffix depending on build type), a libxerus.a/.so and the xerus.so for python in case you also built the python bindings.

You can use these objects directly by setting your environment variables accordingly or you can install the library to a path already included in these variables. To do so simply set the path in config.mk and call (as root if necessary) make install.

Compiling your own Applications Using Xerus

If xerus is properly installed on your system, compiling your own applications using xerus is as simple as using any other library. Just include -lxerus in your linker call and make sure to use -std=c++11 or -std=c++14 in all compilation units that include xerus.h and everything should work fine.

If you want to use the static version of xerus you also have to include all libraries xerus depends on in your linker call. In particular these are lapacke (-llapacke), lapack (-llapack), blas (-lblas or -lopenblas or similar), suitesparse (-lcholmod -lspqr) and binutils (-lbfd). On some old system one has to manually include the dependencys of binutils (-liberty -lz -ldl).

You can test this by trying to compile one of the examples (here without the installed xerus library)

g++ -std=c++11 doc/_include/examples/qtt.cpp build/libxerus.a build/libxerus_misc.a -llapacke -llapack -lopenblas -lgfortran -lcholmod -lspqr -lbfd -liberty -lz -ldl

or with the shared objects and correctly set environment variables

g++ -std=c++11 doc/_include/examples/qtt.cpp -lxerus

Within python you should be able to simply use

import xerus

if everything is set up correctly.