Home  · Classes  · Annotated Classes  · Modules  · Members  · Namespaces  · Related Pages
Building OpenMS on GNU/Linux

This document describes how to build OpenMS on a GNU/Linux system from source. If you encounter errors during configuring/compiling our software, have a look at our Known Issues section and 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

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 root, or checked out the development (git) version.

Next, we will care for 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 distro repositories, we provide sources and build scripts. The Release tar.gz archive contains the libraries in the contrib/ folder, if you build the development (git) version, you'll have to check them out separately (see below in Building remaining dependencies and in Building without root privileges).

Here is a list of required packages and libraries:

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

Fedora packages
    sudo yum groupinstall 'Development Tools'
    sudo yum install git tar
    sudo yum install epel-release
    # Update repo list for the thirdparty repository EPEL
    sudo yum repolist
    # Get installable contrib libraries
    sudo yum install qt4 qt4-devel qt4-webkit-devel python-devel boost-devel \
        libsvm-devel glpk-devel libzip-devel zlib-devel xerces-c-devel bzip2-devel
    
openSUSE
      # register obs://build.opensuse.org/devel:libraries:c_c++
      sudo zypper install cmake gcc-c++ autoconf libqt4-devel \
        libQtWebKit-devel python-devel boost-devel  glpk-devel \
        libzip-devel zlib-devel libxerces-c-devel libbz2-devel \
        git patch automake libtool libsvm-devel
      
Ubuntu/Debian
(> 10.04 <= 15)
    sudo apt-get install cmake g++ autoconf qt4-dev-tools patch libtool make git \
      libqt4-core libqt4-dev libqt4-gui libqt4-opengl-dev automake libqtwebkit-dev
    sudo apt-get install libboost-regex-dev libboost-iostreams-dev \
      libboost-date-time-dev libboost-math-dev libsvm-dev \
      libglpk-dev libzip-dev zlib1g-dev libxerces-c-dev libbz2-dev
    
Ubuntu/Debian
(>= 16.04 <= 16.10)
    sudo apt-get install build-essential cmake autoconf patch libtool automake
    sudo apt-get install qt4-default libqtwebkit-dev
    sudo apt-get install libeigen3-dev libwildmagic-dev \
      libxerces-c-dev libboost-all-dev libsvn-dev libgsl-dev libbz2-dev
    # use from contrib for compatibility: SEQAN ; COINOR; ZLIB ; WILDMAGIC
      

Building remaining dependencies

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

Note
In most cases, the only dependencies left unresolved (e.g. inavailable through your distributions packaging system) at this point are SeqAn and WildMagic. Contact us if you still have trouble with the dependencies after these instructions.

The tar.gz of the Release contains the sources of all dependencies in the contrib/ folder. For the development (git) version, this folder is not included, and has to be checked out separately. We generally recommend to keep the contrib separate from the OpenMS source code. Assuming you have extracted the the OpenMS source code in a folder ~/Development (i.e., ~/Development/OpenMS) we suggest to also put the contrib there (i.e., ~/Development/contrib).

# Assuming you are in ~/Development
git clone https://github.com/OpenMS/contrib.git
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 ../contrib

and then build SeqAn (the other build scripts may or may not be needed to be executed depending on if your distribution does not provide a package for the dependency):

cmake -DBUILD_TYPE=SEQAN ../contrib
cmake -DBUILD_TYPE=WILDMAGIC ../contrib
cmake -DBUILD_TYPE=EIGEN ../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 ../contrib

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 ../contrib
cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 ../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 a 4.x version), 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 && gmake && gmake 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).

When configuring OpenMS (see next section), 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. If you want to use your own qt installation, be sure to set the QT_QMAKE_EXECUTABLE=/path/to/qmake flag when using cmake to configure OpenMS.

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 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/ with the above path to the build contrib. Make sure you use the absolute (and not relative) path for the contrib to avoid any potential issues. If you encounter problems with previously installed system libraries, consider removing the /usr;/usr/local part of the path:

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"

to the CMake options.

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

make

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- or inference engines like XTandem or Fido, their binaries also need to be in the PATH. Build them or download them from our thirdparty git repo and adapt the following for every thirdparty tool you want to use (shown for XTandem):
export PATH=${YOUR_CLONED_THIRDPARTY_GIT_REPO}/${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.




Advanced Options

Advanced users can list the separate make targets by calling:

make targets

You can set more CMake variables adding -DVARIABLE=VALUE options in step Configuring and building OpenMS/TOPP.

The most important CMake variables are:

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!

OPENMS_CONTRIB_LIBS Seperate 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.
QT_QMAKE_EXECUTABLE Defines the Qt 'qmake' application. The corresponding Qt installation is used.
CMAKE_BUILD_TYPE 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.
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.
HAS_XSERVER 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)
WITH_GUI Defines if the OpenMS GUI tools (TOPPView, TOPPAS) should be built or not. These components need Qt > 4.7 which may not be available on some systems (specifically older CentOS / RHEL servers). If you plan to use OpenMS without a GUI, set this flag to "Off" (Default: On)
ENABLE_TUTORIALS Defines if OpenMS should build and install the pdf tutorials. (Default: On)
SEARCH_ENGINES_DIRECTORY (optional) The location where thirdparty search engines (X!Tandem, OMSSA, MyriMatch, MSGF+, Fido) are located. This directory should have the same structure as the example in the search engine repository at https://open-ms.svn.sourceforge.net/svnroot/open-ms/THIRDPARTY/SEARCHENGINES/. This directory is only needed to include thirdparty tools in the installer for OpenMS. For using/running thirdparty tools, see section Getting your environment ready to use OpenMS
PYOPENMS Use ON to also build the Python bindings, see also pyOpenMS (Python bindings).

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)


Testing your OpenMS/TOPP installation

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

make test

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

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

make

OpenMS / TOPP release 2.2.0 Documentation generated on Mon Oct 9 2017 05:05:04 using doxygen 1.8.8