Introduction

This document addresses OpenMS users and explains the installation procedure for building OpenMS from its sources. If you only want to use the OpenMS Proteomics Pipeline (TOPP), you are strongly encouraged to download the windows binary installer (see here), instead of building OpenMS from sources. For more information read the install instructions for the TOPP binaries.

This document especially considers the installation of several libraries which are required by OpenMS. Most of these libraries are made available in our "contrib-package" (see below).
If you encounter errors during configuring/compiling our software, have a look at our "Known Issues" section here, maybe the error is already known. If not, please write to the mailing list.

Notation of this tutorial

A string in <> is something the user needs to choose e.g. <path_to_contrib> means that this string should be replaced by the path where the user put the OpenMS contrib package. Usually all commands where this is necessary come with examples, so don't worry.
Whenever you added a path to your Windows PATH Environment variable, every Command Prompt which is already open will not be refreshed. You will need a to open a new one.

Setup of environment

Pre-Requisites (Software)

Have a Visual Studio 2015 or 2017 installed (The C++ Express editions should work as well, we tested VSE2015 Update 3).
Not supported are MinGW (g++ based compiler) and VS2013 (and earlier). Do not use a MinGW-enabled shell since CMake will get confused! Please use the Command Prompt of the Visual Studio version you want to build with. Other compilers which are close to the VS toolchain might work, but are not tested.
Have CMake 3.0.2 or greater installed (see http://www.cmake.org).
CMake's Generator (-G flag) must support your version of Visual Studio. If it doesn't, upgrade CMake.
To extract archives within submodules of the contrib you will need 7-Zip (see http://www.7-zip.org/)
7z.exe is searched in "C:/Program Files/7-Zip/" and "C:/Programme/7-Zip/". Make sure it is in either of these locations or add the installation directory to your PATH.

Installing required dependency libraries

OpenMS depends on several other libraries. On a windows system, these are usually not present.

Contrib installation

In order to make the installation of the remaining required libraries easier, we composed a "contrib-package" containing the libraries Boost, Eigen, WildMagic, libSVM, SeqAn, glpk, zlib, libbz2 and Xerces-C. This contrib package has several advantages over manual installation

You get all the libraries in versions tested with OpenMS.
It contains a batch script that builds all the libraries in one step.
You don't have to spend hours reading installation instructions of all the libraries.
We applied some patches to the libraries to fix some bugs.
These bugs may be fatal if you do not use the contrib package.

Download:

If you plan to use the development version of OpenMS, clone OpenMS and checkout the optional contrib submodule with

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

git submodule update --init contrib

to obtain the latest potentially unstable version. If you want to use a release version of OpenMS, use the corresponding Release-tagged version on GitHub (https://github.com/OpenMS/contrib/releases) or download the contrib source from a .tar.gz for older releases.

Installation:

After you got the source code for the contrib package follow these steps:

Open a VisualStudio Developer Command prompt (use the x64 version if you want 64 bit apps!)

Note
VS2015 does not provide a commandline shortcut for a 64bit Command Prompt. Call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 to get one!
Create a build directory for the OpenMS contrib
e.g. mkdir contrib_win64_build
Call CMake to build the contrib
Be aware that you can build 64bit apps even if your operating system is only 32bit (cross-compiling), but you will not be able to run 64bit apps in this case.

cd <path_to_contrib_build>
cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 -G "<generator>" "<path_to_contrib>"
The <generator> you use must be one of the Visual Studio Generators. This is because some contrib libs require Visual Studio to build. Be careful to specify the Generator suffixed with "Win64" if you want a 64bit contrib! Type cmake to see a list of available generators.

Example:
cd c:\dev\contrib_win64_build
cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 -G "Visual Studio 9 2008 Win64" "c:\dev\OpenMS\contrib"
Add the <path_to_contrib_build>/lib directory to your PATH Environment Variable (this is so Windows can find the DLL's when running our executables).

QT installation

Qt comes in two flavors: commercial or non-commercial - choose whatever is applicable to you: read more on the Qt website Recently (beginning with Qt 4.6) there are binary development versions available for VS2010 and VS2008. We found these to contain only 32bit compilations. If you are compiling for 32bit as well, you can download these and save a lot of time. They are incompatible for 64bit builds - compile Qt yourself in this case (or see if you can find 64bit builds on the Qt website). Make sure NOT to use the MinGW precompiled binaries, since they are incompatible with Visual Studio binaries.

To build Qt from sources, download Qt 4.8.7 (see below), which supports all VS versions up to VS 2015!

Note: Qt 5.X IS NOT SUPPORTED YET!

Follow this procedure if you want to compile Qt yourself:

non-commercial:
1. download Qt 4.8.7 source from https://download.qt.io/official_releases/qt/4.8/ as .zip or .tar.gz
2. extract zip file to a temp location (called <path-to-tmp-qt> henceforth)
3. [VS2015 only] Qt 4.8.7 will not compile with VS2015 out of the box (previous VS version should be fine). We have included a patch file in our contrib (see above) which should be applied to the extracted Qt sources, i.e.
  cd <path-to-tmp-qt>
  <path_to_contrib>\tools\patch.exe -p0 -b -N -l -i <path_to_contrib>\patches\qt\qt4.8.7_build_with_msvc2015.diff
4. open a Visual Studio Command Line (use x64 version if you want 64bit apps!)
5. cd <path-to-tmp-qt>
6. if you have multiple versions of VS installed you might need to provide the -platform param for the next configure command (e.g., -platform win32-msvc2012)
7. To save disk space, we use the -prefix switch do install only the required parts of Qt to a new directory of your choice (called <path-to-qt>, e.g. c:/dev/Qt4.8.7/).
  configure.exe -opensource -nomake demos -nomake examples -no-script -webkit -prefix <path-to-qt>
8. nmake
9. nmake install
10. all Qt files (libs, includes etc) are now in <path-to-qt> and sub-directories. You can delete <path-to-tmp-qt> (since it will consume quite a lot of disk space)
11. alternatively to nmake, you can download JOM (http://qt-project.org/wiki/jom) and type "jom" in your Qt build directory to use multiple cores (builds a lot faster usually)
commercial:
1. we have no experience here, but it should be possible to get the DLL's and Link-Libraries here as well.
add the <path-to-qt>/bin (!) directory to your PATH Environment Variable

Building the documentation (optional)

This section is optional. If you can live with the online documentation, you do not need to build your own.

In order to build the class documentation (doc & doc_internal targets), TOPP tutorials (doc_tutorials target) and more, you will need to install three programs:

Doxygen (version 1.5.8 and 1.8.2 are tested, others might work as well)
- Download the installer for Windows (http://www.doxygen.org)
- Execute the installer. It should automatically add doxygen.exe to the Windows PATH Environment (please recheck)
MikTeX (version 2.7 and 2.9 are tested, others might work as well) - basic version (for DVIPS, LATEX etc).
- Download binaries for Windows (http://miktex.org/)
- During installation tick "install missing packages on the fly = yes"
- The installer SHOULD add the bin directory of MikTeX automatically to the Windows PATH Environment (please recheck)
GPL Ghostscript (8.60) for Windows
- Download binaries for Windows (http://www.ghostscript.com/) and install
- Add the <path_to_GHOSTSCRIPT>/bin directory (e.g. c:/programs/gs/gs8.60/bin) to the Windows PATH Environment
Optional:
You can create dependency graphs using a doxygen plug-in called dot.
- Download binaries for windows from http://www.graphviz.org (we tested: graphviz-2.18.exe)
- The installer should have added dot.exe to the Windows PATH Environment (please recheck)

You should install the above apps prior to installing OpenMS (see below), because otherwise during the configuration step the documentation targets will be disabled. If you already have a working installation of OpenMS (without documentation), you can simply install the above programs and reconfigure OpenMS by calling cmake . in your build tree. No need to recompile the library!

Installing OpenMS

For development and cutting edge functionalities we recommend using the Git version from GitHub

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

Certain stable releases can found on the GitHub release page https://github.com/OpenMS/OpenMS/releases.

If you have not installed the libraries which OpenMS requires, please refer to the section Contrib installation above (and skip the clone step).

Now, we create the build system:

Open a Visual Studio Command Line (use x64 version if you want 64bit apps!)
Create a build directory for OpenMS, e.g. mkdir OpenMS_Win64
Note
Due to Windows restrictions concerning the maximum length of a file path (of 260 characters) and the rather deep folder hierarchies created by CMake and Visual Studio, we advise to restrict the length of the base path to your build directory. We suggest less than 40 characters if possible.
Call CMake to create the build system
cd <path_to_OpenMS_build>
cmake -D OPENMS_CONTRIB_LIBS="<path_to_contrib_build>" -G "<generator>" "<path_to_OpenMS>"
The choice of <generator> is dependent on your system. Type cmake to see a list of available generators.
Note
We strongly recommend the Visual Studio Generator and it should be identical to the one used for building the contrib. Other generators (such as nmake) are not tested! If you need compiling on the command line, you can use MSBuild also on VS solution files! Example:
cd c:\dev\OpenMS_Win64
cmake -D OPENMS_CONTRIB_LIBS="C:\dev\contrib_win64_build" -G "Visual Studio 9 2008 Win64" ..\OpenMS

Now there should be a OpenMS_host.sln file in your build directory, which you can open using Visual Studio. If you want to work on only a subset of OpenMS (e.g., OpenMS_GUI) you can open the specific solution that you will find in the src/ folder of your build folder and below (e.g., src/openms_gui/OpenMS_GUI.sln).

In Visual Studio execute the 'targets' project, which will show you the most prominent targets.

Try to build the OpenMS library - the target is called 'OpenMS'. This will create the OpenMS library dll. If you used the debug configuration it will be called OpenMSd.dll, in release mode its called OpenMS.dll.
As a last step you should add the location of the OpenMS.dll to your PATH environment. This makes calling TOPPView and TOPP tools more convenient if you are working the command line. Also, external projects (see External Code using OpenMS) require the OpenMS dll (OpenMS.dll or OpenMSd.dll) to be in the PATH. Depending on the generator and configuration used you will find the dll in [OpenMS_build]/bin/Release or [OpenMS_build]/bin/Debug (for VS) or just [OpenMS_build]/bin (nmake). In the same folder the TOPP tools will reside once build (see next section). Be aware that the order of directories in the PATH variable determines which dll or executable is used, if no absolute path was given when the executable was called. So the PATH might need to be updated (add/delete/reorder entries) if you are working with multiple installations or configurations of OpenMS.

Building the TOPP tools

TOPP is a toolset for the analysis of HPLC-MS data. It consists of several small applications that can be chained to create analysis pipelines tailored for a specific problem.

After you have built OpenMS, you can build the TOPP tools by building the "TOPP" project in the IDE.

Testing your OpenMS/TOPP installation

Each class in OpenMS and each TOPP tool has a unit test. The tests will be build with the complete solution. To specifically build and execute the tests, go to your OpenMS build_tree and further into ./src/tests/class_tests. There you'll find an OpenMS_class_tests.sln file, which you can open. For other generators an equivalent file with another suffix will be present. Now, build the 'ALL_BUILD' target and the 'RUN_TESTS' target. You can also run the tests in a command prompt in <OpenMS_build_tree> using ctest. Single tests can be run with ctest -R <testnameregex>, e.g. ctest -R Base64_test. For more syntax on CTest look at the online documentation at http://cmake.org/.

Building OpenMS on the commandline

The Visual Studio solution files can contain many targets, which makes the IDE a bit sluggish especially when starting up the first time. The OpenMS class tests are by far the largest.

If you just want to compile the library or executables, it's usually faster to use the commandline. Visual Studio solution files can be used here as well, as arguments to MSBuild.exe, e.g.

MSBuild.exe <solution.sln> /maxcpucount /target:<target> /p:Configuration=<Config>

Note: Since the call can be a bit lengthy, there is a batch file in OpenMS/tools/build.bat, which allows to build the most important targets (TOPP, UTILS, Gui, Tests, Doc) in Release or Debug using very short notation. Call it without arguments to see its usage help text.