This document describes how to build OpenMS on a GNU/Linux system from source. If you encounter errors during configuring/compiling our software, search in our issue tracker, maybe the error is already known. If not, please write to the mailing list or report the error on our issue tracker.

Note: If you do not have root privileges on your system, make sure you read the section Building without root privileges.

We are working on adding OpenMS to the repositories of the most popular distributions, but for many platforms the toolkit needs to be manually compiled on your system. The same applies if you want to use the most recent source files from our Git repository.

Checkout OpenMS repository

You can find the links to the release and development versions on the Downloads page of the OpenMS project. All source code, including the latest development version, is on GitHub and can be obtained via Git:

# Assuming you are in ~/Development

git clone https://github.com/OpenMS/OpenMS.git

From here on, the instructions assume you have either an extracted tar.gz of a release and are inside its top folder, or checked out the development (Git) version.

Next, we will take care of the dependencies upon which building OpenMS from source relies.

Dependencies obtainable in binary form

OpenMS requires several other libraries to be present on your system. Most of these should be available in the repositories of your GNU/Linux distribution.

For those libraries/versions often not found in the distribution's repositories, we provide sources and build scripts in a "contrib" submodule. The Release tar.gz archive contains these libraries in the contrib/ folder. If you build the development (Git) version, you will find an empty submodule in that folder that you have to update first with:

git submodule update --init contrib

Despite that, in the following is a list of all required packages and libraries:

Essential are gcc/g++ (>= 7.0) or similar ANSI C++ compiler with full C++17 support, CMake (>= 3.24), Qt5 (>= 5.6), patch, autoconf (> 2.60), automake (> 1.9), libtool (libtoolize/glibtoolize).
For the complete feature set to be enabled, OpenMS needs recent versions of Boost (>= 1.74), Eigen3 (>= 3.4.0), libHDF5, libSVM (2.91 or higher but not 3.15), glpk (>= 4.45) or CoinMP (>= 1.3.3), zlib, libbz2, and Xerces-C (>= 3.1.1). These should be built by our contrib build script in case they are not already installed via your package manager.
Building the documentation from the development version requires Doxygen (recommended: >= 1.8.13, required: > 1.5.4, some might be buggy in between) and pdflatex/texlive/texlive-full.
Building pyOpenMS, the Python bindings for OpenMS, requires Python, Cython and a few Python packages. See here for more detailed pyOpenMS build instructions.

For the most common distributions, we have compiled the commands which will install the required compatible libraries. There may be different libraries in your distribution's packaging system, but beware of version incompatibilities.

Fedora/RHEL/CentOS packages

   # In newer distros change yum to dnf
   sudo yum groupinstall 'Development Tools'
   sudo yum install git tar
   # Especially on older CentOS versions <= 6 add the EPEL repo with additional updated packages
   sudo yum install epel-release
   # Update repo list for the thirdparty repository EPEL
   sudo yum repolist
   # Get REQUIRED installable contrib libraries
   sudo yum install cmake3 qt5-qtbase-gui qt5-qtbase-devel qt5-qtsvg-devel python-devel
   # Get OPTIONAL installable contrib libraries preferably from our Contrib package in the next step.
   ## sudo yum boost-devel libsvm-devel libzip-devel zlib-devel xerces-c-devel bzip2-devel libhdf5-devel glpk-devel
   # NOTE that you might need to use cmake3 instead of cmake in the commands of the following steps.

openSUSE >= 13.2

     # register obs://build.opensuse.org/devel:libraries:c_c++
     # tools
     sudo zypper install cmake gcc-c++ autoconf git patch automake libtool
     # REQUIRED dependencies
     sudo zypper install libqt5-qtbase-devel libqt5-qtsvg-devel python-devel glpk-devel
     # OPTIONAL dependencies, preferably installed with our Contrib package in the next step
     ## sudo zypper install boost-devel libzip-devel zlib-devel \
     # libxerces-c-devel libbz2-devel libsvm-devel libhdf5-10

Ubuntu/Debian
(>= 20.04)

   # Include the Ubuntu "universe" repository and update:
   sudo add-apt-repository universe
   sudo apt update
   sudo apt-get install build-essential cmake autoconf patch libtool git automake
   sudo apt-get install qtbase5-dev libqt5svg5-dev libqt5opengl5-dev
   sudo apt-get install libeigen3-dev libboost-random-dev libboost-regex-dev \
     libboost-iostreams-dev libboost-date-time-dev libboost-math-dev libxerces-c-dev \
     zlib1g-dev libsvm-dev libbz2-dev coinor-libcoinmp-dev libhdf5-dev
   # This should eliminate the need for building contrib libraries. Note: installing libglpk-dev is optional.

Building remaining dependencies

You can and should check which dependencies you still need by attempting to configure OpenMS (see the next section); it will complain about anything unusual/missing.

Warning: Do not install libraries from our contrib package if it is installed on your system in a compatible version already. If you have an incompatible version, we suggest to update or uninstall and use the contrib version.

Note: In most cases, the only dependency left unresolved (e.g. unavailable through your distributions packaging system) at this point is CoinOR. Contact us if you still have trouble with the dependencies after these instructions.

The tar.gz of the Release contains the scripts for building all dependencies in the contrib/ folder. For the development (Git) version, this so called submodule folder will be empty and has to be checked out separately.

# Assuming you are in ~/Development/OpenMS
git submodule update --init contrib
cd ..
mkdir contrib-build
cd contrib-build

For the contrib as well as for OpenMS we suggest to use out-of-source builds.

Note: Generally all files generated while building OpenMS have to go somewhere. In case of in-source-builds all files will be generated alongside the source code. While this is easy and a well known practice from the regular ./configure + make approach it also changes your build tree. It also prohibits building multiple configurations (e.g., Debug and Release or different compiler versions). As an alternative CMake offers the possibility to perform so called out-of-source builds. Here all build files, binaries, libraries, etc. are generated in a separate directory.

From the ./contrib-build/ folder, execute the following command to show the available build types

cmake -DBUILD_TYPE=LIST ../OpenMS/contrib

OpenMS

Main OpenMS namespace.

Definition: openswathalgo/include/OpenMS/OPENSWATHALGO/DATAACCESS/ISpectrumAccess.h:19

and then build Eigen:

cmake -DBUILD_TYPE=EIGEN ../OpenMS/contrib

To avoid problems while building the libraries contained in the contrib package, the path to your contrib-build directory should not have any spaces in it. In case your distribution does not provide some of the packages (or in different versions than expected), it is sometimes easier to build all dependencies manually which can solve issues with incompatible versions:

cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 ../OpenMS/contrib

OpenMS::HasRangeType::ALL

@ ALL

all dimensions are filled

Building without root privileges

If you are on a system without root access (e.g. a shared cluster), there are some additional considerations, especially regarding dependencies. Specifically, some older Red Hat systems have older libraries installed that may interfere with the newer versions that OpenMS requires. The recommended installation procedure is to use the contrib package to compile all dependencies from source:

cmake -DBUILD_TYPE=LIST ../OpenMS/contrib

cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 ../OpenMS/contrib

Alternatively, you can build one package after the other by providing -DBUILD_TYPE=... with the appropriate argument. In addition, you may have to compile Qt yourself which you can get from http://download.qt.io/official_releases/qt (use version >5.5), if it is not provided on your server or the version on your environment is too old. Then you can use the traditional ./configure –prefix=/path && make && make install sequence to compile and install Qt (note that you should set the –prefix=/path to a local directory assuming you don't have root privileges).

Configuring and building OpenMS/TOPP

It is assumed that you have successfully built and installed all dependencies and are in the root folder of the OpenMS tree (see above in Checkout OpenMS repository for instructions how to obtain OpenMS sources either from a release version or from the most recent development branch).

The next step is to create a build directory beside the OpenMS root directory e.g., OpenMS-build (see above note on out-of-source builds).

# Assuming you are in ~/Development and OpenMS is also located in
# ~/Development
mkdir OpenMS-build
cd OpenMS-build

In the OpenMS build directory we execute CMake to configure OpenMS. You should substitute /PATH/TO/contrib-build/ with the above path to the built contrib. Make sure you use the absolute (and not relative) path for the contrib to avoid any potential issues.

Note: Since static versions of the boost library are on some systems (e.g. Ubuntu) compiled with different settings you have to set BOOST_USE_STATIC to OFF or compile it with our contrib.
cmake -DOPENMS_CONTRIB_LIBS="/PATH/TO/contrib-build" -DBOOST_USE_STATIC=OFF ../OpenMS

If CMake has problems finding system libraries, you might consider adding:

-DCMAKE_PREFIX_PATH="/usr;/usr/local"

DCMAKE_PREFIX_PATH

You can set more CMake variables adding< code > linking and adding include directories</td ></tr >< tr >< td valign="top"> c CMAKE_PREFIX_PATH</td >< td > Additional search path for the contrib libraries[MacOSX only] If you want to use libraries installed via Homebrew or MacPorts you might need to provide the corresponding paths< code > DCMAKE_PREFIX_PATH

Definition: common-cmake-parameters.doxygen:19

to the CMake options.

If CMake has problems finding Qt5 (Qt5SvgConfig.cmake is usually the first to fail), you might consider adding:

-DQt5_DIR=/PATH/TO/qt/5.9.7/gcc_64/lib/cmake/Qt5

to the CMake options, where /PATH/TO/qt/5.9.7/gcc_64 depends on your system settings and Qt version.

When configuring OpenMS, consider setting WITH_GUI=Off and HAS_XSERVER=Off, especially as you may not have compiled Qt with OpenGL and you may not have an X server.

You can set more CMake variables adding <code>-DVARIABLE=VALUE</code> options when calling CMake.
 
The most important CMake variables are:
 
<table style="border-style:solid; border-collapse:collapse; border-color:#c0c0c0;">
  <tr>
    <td valign="top">\c OPENMS_CONTRIB_LIBS</td>
    <td>Separate search path for the contrib libraries from github.com/OpenMS/contrib that is internally considered before
    CMAKE_PREFIX_PATH for searching, linking and adding include directories.</td>
  </tr>
  <tr>
    <td valign="top">\c CMAKE_PREFIX_PATH</td>
    <td>Additional search path for the contrib libraries.
 
    [MacOSX only]
    If you want to use libraries installed via Homebrew or MacPorts you might
    need to provide the corresponding paths
 
    <code>-DCMAKE_PREFIX_PATH=/usr/local/Cellar</code> for Homebrew
    <code>-DCMAKE_PREFIX_PATH=/opt/local</code> for MacPorts
 
    Please keep in mind that both Homebrew and MacPorts do not provide all libraries so
    you also need to specify the path to your self-build contrib via -DOPENMS_CONTRIB_LIBS
    </td>
  </tr>
  <tr>
    <td valign="top">\c Qt5_DIR</td>
    <td>Additional search path for the Qt5 CMake files. Use <tt>/PATH/TO/QT_INSTALLATION/lib/cmake/Qt5</tt> as value.</td>
  </tr>
  <tr>
    <td valign="top">\c HAS_XSERVER=On/Off</td>
    <td>[Linux/MacOS only] Defines if a running X Server is available when building %OpenMS.
    As building parts of the documentation and running certain tests requires
    a running X Server, this flag can be used to disable those parts of the
    documentation and the tests that need an X Server. (Default: On)</td>
  </tr>
  <tr>
    <td valign="top">\c ADDRESS_SANITIZER=On/Off</td>
    <td>[g++/clang only] Enables/Disables Address Sanitizer (ASAN) to find access violations and other bugs.</td>
  </tr>
  <tr>
    <td valign="top">\c WITH_GUI=On/Off</td>
    <td>Defines if the %OpenMS GUI tools (TOPPView, TOPPAS) should be built or
    not. If you plan to use %OpenMS without a GUI, set this flag to "Off" (Default: On)</td>
  </tr>
  <tr>
    <td valign="top">\c ENABLE_DOCS=On/Off</td>
    <td>Enables documentation targets, allowing to build the %OpenMS documentation.
    (Default: On)</td>
  </tr>
  <tr>
    <td valign="top">\c GIT_TRACKING=On/Off</td>
    <td>Embed Git checksum into the library.
    (Default: On)</td>
  </tr>
  <tr>
    <td valign="top">\c ENABLE_UPDATE_CHECK=On/Off</td>
    <td>Check online for %OpenMS Updates upon invocation of any TOPP tool.
    (Default: On)</td>
  </tr>
  <tr>
    <td valign="top">\c CMAKE_BUILD_TYPE</td>
    <td>[makefiles only; does not apply for XCode or VS] Should be either 'Release' (optimization enabled)
        or 'Debug' (debug info and precondition/postcondition checks enabled).
        @n The default is 'Release'.</td>
  </tr>
  <tr>
    <td valign="top">\c CMAKE_CXX_COMPILER</td>
    <td>Defines the C++ compiler to use.</td>
  </tr>
  <tr>
    <td valign="top">\c MY_CXX_FLAGS</td>
    <td>Additional custom C++ compile options you would like to add (must fit your chosen compiler). 
        This might be useful, for example, for adding debug symbols to a Release build, or for performance 
        analysis (e.g. for '... -DMY_CXX_FLAGS="-Og;-ggdb;-g3;-fno-omit-frame-pointer" ...')</td>
  </tr>
  <tr>
    <td valign="top">\c CMAKE_C_COMPILER</td>
    <td>Defines the C compiler to use. This should match the C++ compiler.
    Mixing compilers (e.g., <i>clang++</i> for C++ and <i>gcc</i> for C) can
    lead to undefined behaviour as some internal settings (e.g., %OpenMP
    support) are determined using the C compiler and are assumed to be the
    same for the C++ compiler.</td>
  </tr>
  <tr>
    <td valign="top">\c SEARCH_ENGINES_DIRECTORY (optional)</td>
    <td>The location where thirdparty search engines (X!Tandem, MSGF+)
    are located. This directory should have the same structure as the example
    in the search engine repository at https://github.com/OpenMS/THIRDPARTY after flattening for your platform.
    /.
    This directory is only needed to include thirdparty tools in the installer for %OpenMS.
  </tr>
  <tr>
    <td valign="top">\c PYOPENMS=Off/On</td>
    <td>Create Python bindings, see also @ref pyOpenMS (Default: Off)</td>
  </tr>
  <tr>
    <td valign="top">\c CMAKE_INSTALL_PREFIX</td>
    <td>the path where the bin/ and lib/ directories should be installed to
        (when <pre>sudo make install</pre> is wished for a system-wide
        install: e.g. -DCMAKE_INSTALL_PREFIX=/usr/local/)
        <BR>
        <b>Note:</b> Moving these directories after installing is not supported.
 
        <b>For development, install prefixes are not supported. In this case %OpenMS must
         be built in place!</b>
   </td>
  </tr>
</table>

A full list of the CMake variables is shown when you execute

ccmake .

This works only after having executed cmake once (see Configuring and building OpenMS/TOPP)

In order to build the OpenMS library, the TOPP tools, tests, and this documentation, execute the following command:

make

Advanced users can list the separate make targets by calling:

make targets

Getting your environment ready to use OpenMS

The previous step takes the most time, in the meanwhile you can prepare your environment for easy OpenMS usage:

Make sure to add /PATH/TO/OpenMS/lib/ (e.g. /home/smith/OpenMS/lib/) to the environment variable LD_LIBRARY_PATH. The best way is to edit $HOME/.bashrc and add the following

export LD_LIBRARY_PATH="/PATH/TO/OpenMS/lib:$LD_LIBRARY_PATH"

The TOPP tools will be built in the /PATH/TO/OpenMS/bin/ folder. Add this path to the environment variable PATH to use the commands anywhere on your system.

This is necessary to use the TOPP tools from TOPPView.

You can do this by appending the following also to your $HOME/.bashrc (Do not use the tilde character ~ to abbreviate your home folder)

export PATH=$PATH:/PATH/TO/OpenMS/bin

Apply both changes by executing

source ~/.bashrc

Note: When you intend to use thirdparty search engines like X!Tandem, their binaries also need to be in the PATH. Build them or check out prebuilt executables of the versions supported at the time of the release with
git submodule update --init THIRDPARTY

and adapt the following for every thirdparty tool you want to use (shown for XTandem):
export PATH=~/Development/OpenMS/THIRDPARTY/${FOLDER_FOR_YOUR_OS_ARCH}/XTandem:${PATH}

If you want to enable the corresponding tests in CMake, this has to happen before you configure and build the project.

Running OpenMS

If the build from Configuring and building OpenMS/TOPP is ready, you can now run a GNU/Linux OpenMS tool by e.g. executing

FileInfo

From here on you should be good to go! See below for advanced installation and configuration options.

Note: Once OpenMS is built, some thirdparty software used via adapter tools in OpenMS might also require an installed JavaVM.

Testing your OpenMS/TOPP installation

After you have installed OpenMS and TOPP, you should test your installation by executing the following command:

make test

OpenMS::Internal::ClassTest::test

bool test

Status of the current subsection.

or

ctest

Using ctest you can also execute only a subset of tests by using the -R [REGEX] option and run tests in parallel using the -j parameter. For more information, consult ctest man page.

ctest -R TOPP_ -j 4

OpenMS::Constants::R

const double R

Definition: Constants.h:149

Will run all TOPP test using 4 jobs. Make sure that you have build all tests beforehand by executing

make