Building OpenMS on GNU/Linux

This document describes how to build OpenMS on a GNU/Linux system from source.

If you encounter errors while configuring or compiling OpenMS, search in the issue tracker for a possible solution. If an existing issue can't be found please report the error using the same issue tracker.

Note

If you do not have root privileges on your system, make sure you read the section entitled 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.

Installing Dependencies

We recommend installing all dependencies using your distribution's package manager. However, If you would rather built all dependencies from source you can do so using the OpenMS contrib directory. Details can be found in the section entitled Using the contrib Package.

Ubuntu/Debian (>= 22.04)

The OpenMS continuous build system uses Ubuntu and therefore build instructions for Ubuntu will be the most accurate.

Dependencies can be installed using the following commands:

# Add "universe" and update:
sudo add-apt-repository universe
sudo apt update
 
# Required dependencies:
sudo apt-get -qq install -y \
  build-essential \
  cmake \
  autoconf \
  patch \
  libtool \
  git \
  automake \
  ninja-build \
  xvfb \
  ccache \
  qt6-base-dev \
  libqt6svg6-dev \
  libqt6opengl6-dev \
  libqt6openglwidgets6 \
  libgl-dev \
  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
 
  sudo apt update
  sudo apt-get install -y -V ca-certificates lsb-release wget
  wget https://packages.apache.org/artifactory/arrow/$(lsb_release --id --short | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
  sudo apt update
  sudo apt-get install -y -V ./apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
  sudo apt update
  sudo apt-get install -y --no-install-recommends \
        libarrow-dev \
        libparquet-dev \
 
# Optional dependencies:
sudo apt-get -qq install -y \
  doxygen \
  ghostscript \
  graphviz

Fedora/RHEL/CentOS

Note

These instructions are not currently maintained. If you find that they are incorrect please open a pull request or create an issue.

# 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 qt6-qtbase-gui qt6-qtbase-devel qt6-qtsvg-devel python-devel
# Get OPTIONAL installable contrib libraries preferably from our Contrib package in the next step.
## sudo yum install 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

Note

These instructions are not currently maintained. If you find that they are incorrect please open a pull request or create an issue.

# 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 libqt6-qtbase-devel libqt6-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

Building OpenMS

1. Begin by obtaining a copy of the OpenMS source code:

OPENMS_DIR=~/openms-development
mkdir -p "$OPENMS_DIR"
cd "$OPENMS_DIR"
git clone --recurse-submodules https://github.com/OpenMS/OpenMS

1. Then compile the source code:

mkdir -p "$OPENMS_DIR/openms_build"
cd "$OPENMS_DIR/openms_build"
cmake -DBOOST_USE_STATIC=OFF "$OPENMS_DIR/OpenMS"
make -j"$(nproc || sysctl -n hw.logicalcpu || echo 2)"

Note

After executing CMake you can list all of the make targets by running make targets.

1. The TOPP tools should now be ready to use.

   The applications are located in the $OPENMS_DIR/openms_build/bin directory.

   Note

   If you intend to use third party search engines like Comet, their binaries also need to be in the PATH environment variable. You can find pre-built binaries in the OpenMS THIRDPARTY directory. To use them set the PATH environment variable using the following command:

   export PATH="$OPENMS_DIR/OpenMS/THIRDPARTY/Linux/$(uname -m)/Comet:$PATH"

Additional CMake Flags

You can set more CMake variables adding -DVARIABLE=VALUE options when calling CMake.
The most important CMake variables are:

OPENMS_CONTRIB_LIBS	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.
CMAKE_PREFIX_PATH	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 -DCMAKE_PREFIX_PATH=/usr/local/Cellar for Homebrew -DCMAKE_PREFIX_PATH=/opt/local 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
Qt6_DIR	Additional search path for the Qt6 CMake files. Use /PATH/TO/QT_INSTALLATION/lib/cmake/Qt6 as value, e.g. C:\dev\qt6\6.7.1\msvc2019_64\lib\cmake\Qt6
HAS_XSERVER=On/Off	[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)
ADDRESS_SANITIZER=On/Off	[g++/clang only] Enables/Disables Address Sanitizer (ASAN) to find access violations and other bugs.
WITH_GUI=On/Off	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)
ENABLE_DOCS=On/Off	Enables documentation targets, allowing to build the OpenMS documentation. (Default: On)
GIT_TRACKING=On/Off	Embed Git checksum into the library. (Default: On)
ENABLE_UPDATE_CHECK=On/Off	Check online for OpenMS Updates upon invocation of any TOPP tool. (Default: On)
CMAKE_BUILD_TYPE	[makefiles only; does not apply for XCode or VS] Should be either 'Release' (optimization enabled) or 'Debug' (debug info and precondition/postcondition checks enabled). The default is Release.
CMAKE_CXX_COMPILER	Defines the C++ compiler to use.
MY_CXX_FLAGS	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" ...)
CMAKE_C_COMPILER	Defines the C compiler to use. This should match the C++ compiler. Mixing compilers (e.g., clang++ for C++ and gcc 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.
SEARCH_ENGINES_DIRECTORY (optional)	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.
PYOPENMS=Off/On	Create Python bindings, see also pyOpenMS (Default: Off)
CMAKE_INSTALL_PREFIX	the path where the bin/ and lib/ directories should be installed to (when sudo make install is wished for a system-wide install: e.g. -DCMAKE_INSTALL_PREFIX=/usr/local/) Note: Moving these directories after installing is not supported. For development, install prefixes are not supported. In this case OpenMS must be built in place!

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

ccmake .

This works only after having executed `cmake` at least once.

Testing the OpenMS/TOPP Installation

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

make test

or

ctest

By using `ctest` you can also execute a subset of tests by using the `-R SUBSTRING` option and run tests in parallel using the `-j` option. For example,

ctest -R TOPP_ -j 4

will run all TOPP test using 4 jobs.For more information, consult the `ctest` [man page][ctest].[ctest]: http://manpages.ubuntu.com/manpages/hardy/man1/ctest.1.html

Using the contrib Package

Under certain circumstances you may want to build all dependencies from source code. In order to facilitate the installation of the libraries required for OpenMS we provide a "contrib" package containing the following libraries: Boost, Eigen, libSVM, libHDF5, glpk, zlib, bzip2, CoinMP and Xerces-C.The following commands can be used to build all of these dependencies (assuming you have already cloned the OpenMS repository using the commands previously used in this document):

mkdir -p "$OPENMS_DIR/contrib_build"
cd "$OPENMS_DIR/contrib_build"
cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=8 "$OPENMS_DIR/OpenMS/contrib"

Alternatively, you can build one dependency at a time by using the `BUILD_TYPE` flag. For example:

cmake \
  -DBUILD_TYPE=LIBSVM \
  -DNUMBER_OF_JOBS="$(nproc || sysctl -n hw.logicalcpu || echo 2)" \
  "$OPENMS_DIR/OpenMS/contrib"

If everything worked, the following sub-directories were created under the `contrib` build directory:

• `lib`: containing the libraries needed by OpenMS.
• `include`: containing the header files needed for OpenMS.

You can now build OpenMS with the instructions in this document by adding the following flag to `cmake`:

-DOPENMS_CONTRIB_LIBS="$OPENMS_DIR/contrib_build"

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. Details can be found in the section entitled Using the contrib Package.

Common Issues with Qt

If the graphical TOPP tools fail to start or exit with an error message related to Qt you may need to set the QT_QPA_PLATFORM environment variable. This is especially true if you are executing the graphical tools remotely over a SSH-forwarded X11 connection.

Setting the QT_QPA_PLATFORM environment variable to minimal before running a TOPP tool should help. For example:

export QT_QPA_PLATFORM=minimal
$OPENMS_DIR/openms_build/bin/TOPPView