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 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, search in our issue tracker, already known. If not, please write to the mailing list (open-ms-general AT lists.sourceforge.net) or report the error on our issue tracker.

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)

Microsoft Visual C++ Compiler: Comes with Microsoft Visual Studio Build Tools. Scroll to the bottom of the page to get the build tools only. If you want, you can also download the full Visual Studio (Community/Pro/Enterprise) IDE.
OpenMS requires at least Visual Studio 2019 (version 16.8.4 from January 2021) or later. Earlier versions have compiler bugs and may not compile without modifications.
Not supported (or at least not tested) is MinGW (g++ based compiler). 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 or load vcvarsall.sh (see below). Other compilers which are close to the VS toolchain might work, but are not tested.
CMake: Have CMake (>= 3.24) installed (see http://www.cmake.org).
If you are using Visual Studio 2019+ as IDE, make sure CMake's Generator (-G flag) supports your version of Visual Studio. If it doesn't, please upgrade CMake.
7-Zip: 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, CoinMP, libSVM, libHDF5, 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
cd 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 (by default you will get a 32-bit environment which you most likely do not want; use a x64 environment if you want 64 bit apps!)

Note
VS2019 and above have a (well hidden) batch-file which correctly configures your environment for 64bit builds. It should be located at "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat". (Same goes for VS2022)
Use our tools/load_vcvarsall.sh if you are building in bash on Windows.
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. You might also need to disable incremental linking due to the smaller address space.

cd <path_to_contrib_build>

cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 -G "<generator>" -A x64 "<path_to_contrib>"

OpenMS::HasRangeType::ALL
@ ALL
all dimensions are filled

The <generator> you use must be one of the Visual Studio Generators. This is because some contrib libs require Visual Studio to build. If you are lucky, CMake chooses the correct Generator even without specifying. Default architecture/platform is the same as your Windows. Use the -A x64 flag to build 64-bit libraries for the contrib to make double sure you build 64-bit. (32-bit does not really make any sense for LC-MS data processing) Type cmake -help 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 16 2019" -A x64 "c:\dev\OpenMS\contrib"

OpenMS::Constants::c
const double c
Definition: Constants.h:188
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. For several recent Qt5 versions, there are binary development versions available for the most recent compilers.

Installation of Qt5 via the Qt5 installer (requires an admin account):
Go to https://www.qt.io/download and click on "Go open source" at the end of the right column to download the installer. Follow steps, download, save and run the installer. Create a Qt account. Choose a folder like "C:\dev\QT". From the components choose a matching version, e.g. QT 5.12.2 and the MSVC component that fits your Visual Studio version and architecture (most likely only 64bit is supported; if your Visual Studio version is more recent than the VS offered by the Qt installer, choose the closest available – they should be compatible). You can deselect QtCreator under Tools. Accept the license, choose startmenu entries if wanted and install. Resulting files appear under "c:\dev\QT\$VERSION".

Alternatively (no admin account required), compile Qt from sources by following the steps below:

non-commercial:
1. install perl (e.g. Strawberry Perl), Python and git
2. open a Visual Studio Command Line (use x64 version if you want 64bit apps!)
3. Make sure that Python, Perl (both required to build Qt5) and git are in your PATH, e.g.
  where python
  
  and if python is not found, then add it. e.g.
  set PATH=%PATH%;C:\Python27\
  
  Warning: APPEND these directories to your PATH (like shown above); do NOT PREPEND them, since some versions of Perl ship their own link.exe, which should not be listed before the VS's native link.exe.
4. download Qt5 source via git or as a source package from the website:
  git clone https://code.qt.io/qt/qt5.git
  
  cd qt5
  
  git checkout 5.15
5. activate the needed modules via:
  perl init-repository --module-subset="essential,qtsvg" --branch
6. To save disk space, we use the -prefix switch to install only the required parts of Qt to a new directory of your choice (called <path-to-qt>, e.g. c:/dev/qt_5.15_build/). The git source repository of Qt5 can be deleted safely at the very end.
7. 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)
8. Check more options and supported compilers here: http://doc.qt.io/qt-5/configure-options.html (especially for developers).
  configure -opensource -skip speech -skip location -nomake tests -nomake examples -confirm-license -opengl dynamic -platform win32-msvc -prefix <path-to-qt_build>
  
  OpenMS::StringUtils::prefix
  static String prefix(const String &this_s, size_t length)
  Definition: StringUtilsSimple.h:122
9. nmake
10. nmake install
11. all Qt files (libs, includes etc) are now in <path-to-qt> and sub-directories.
12. alternatively to nmake, you can download JOM (http://qt-project.org/wiki/jom) and type "jom" and subsequently "jom install" 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, so the dlls are found during runtime.
set the environment variable QT_QPA_PLATFORM_PLUGIN_PATH to <path-to-qt>/plugins/platforms, otherwise you might get an error "This application failed to start because it could not find or load the Qt platform plugin 'windows'". Alternatively, you can copy the entire platforms-folder into the folder where your OpenMS executables will be created (but they will depend on the build-type, i.e. release, debug etc.).

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 (1.8.16 is tested, others might work as well; older versions might produce errors or incomplete documentation due to lack of support for certain commands or bugs)
- 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, texlive is an option, too) - 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 (e.g. 8.60, 9.19) 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. Since you already cloned OpenMS above when building the contrib, you can usually skip this step:

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 – and yes, you want that!)
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>" -D CMAKE_PREFIX_PATH=<path_to_QT5_prefix> -G "<generator>" -A x64 -T host=x64 "<path_to_OpenMS>"

The CMAKE_PREFIX_PATH should hold the path to your Qt5 build directory (see example below). Note that it is NOT the main Qt5 directory, but the subfolder which is named after the toolchain it was build with (e.g. "5.6/msvc2015_64").
Note
If you build Qt5 from source, the build directories will be located at <path_to_qt>\mkspecs. Here you will need to choose the matching directory for your architecture and Visual Studio version.

Example CMAKE_PREFIX_PATH: C:\dev\qt-5.9\mkspecs\winrt-x64-msvc2017

The choice of <generator> depends on your system. Type cmake –help 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 supported! If you need compiling on the command line, you can use MSBuild also on VS solution files! Use the -A x64 flag to build a 64-bit OpenMS library and TOPP executables (32-bit does not really make any sense for LC-MS data processing)! The -T host=x64 flag instructs Visual Studio to use a 64bit compiler and linker toolchain to avoid linker errors (LNK1210: exceeded internal ILK size limit; link with /INCREMNTAL:NO) during development (if the flag is omitted the 32bit toolchain is used to generate 64bit binaries).

Example:
cd c:\dev\OpenMS_Win64

cmake -D OPENMS_CONTRIB_LIBS="C:/dev/contrib_win64_build" -D CMAKE_PREFIX_PATH=c:/dev/Qt5.6.2/5.6/msvc2015_64/ -G "Visual Studio 16 2019" -A x64 -T host=x64 ../OpenMS

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>

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.dll library. 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>

Example:

MSBuild.exe OpenMS_host.sln

Note: Since the call can be a bit lengthy, there is a batch file in OpenMS/tools/build.bat and in the root of your build tree (copied there by cmake for convenience), which allows to build the most important targets (TOPP, Gui, Tests, Doc) in Release or Debug using very short notation. Call it without arguments to see its usage help text. For example to build only the OpenMS library in release mode, call

build OpenMS r

Advanced: Building OpenMS in any IDE (Example: Visual Studio Code)

This section is for users that already have a little experience with IDEs like VS Code or JetBrains CLion. Especially the first step requires to read through the beginning of this documentation.

Download and install requirements (Git, CMake, 7zip, VS Build Tools, Qt) and make sure they are in your PATH
Download and install VS Code
Install C++ Extension Pack, CMake Tools, CMake Test Explorer and potentially some GitHub extensions
Ctrl+Shift+P and find Git: clone, then type and search for OpenMS/OpenMS. Select a folder. Wait for clone to finish. Open clone. Trust authors.
Open bash Terminal from within VS Code and type source tools/loadvcvarsall.sh && load_msenv && git submodule update –init contrib && mkdir contrib-build && cd contrib-build && cmake -DBUILD_TYPE=ALL ../contrib
Adapt (to your paths) and add
"cmake.configureArgs": [

"-DOPENMS_CONTRIB_LIBS=C:\\git\\contrib-build",

"-DCMAKE_PREFIX_PATH=C:\\dev\\Qt\\5.15.2\\msvc2019_64"

]

to your settings or configure manually in your user-config.yml or via the VS Code command runner.
Ctrl+Shift+P and find > CMake: Select Kit, select preferably "Visual Studio Build Tools Release 2022 - amd64"
Ctrl+Shift+P and find > CMake: Configure
Select a build configuration and a target in the VS Code task bar (the usually blue bar on the very bottom of the program). The default target is all. Then press the gear for building, the play button for building and running (if it is an executable target), or the bug button for debugging.
Happy coding!
Bonus points for setting up Remote development for the Windows Subsystem for Linux and building for Windows and Linux in parallel. Beware of Windows line endings!

Creating an installer

Download NSIS (we tested nsis-3.06.1 successfully) and extract it somewhere
Install the large-string-build NSIS installer on top (just extract into the same directory as NSIS; and use a matching version!). This is required for PATH manipulation of up to 8k length; the default NSIS handles up to 1k strings, which might be too short and potentially leads to a broken PATH environment variable.
Install the UltraModernUI-plugin on top (just extract into the same directory as NSIS). We tested version 2.0b6 successfully.
Add the NSIS folder (which contains 'makensis.exe') to your PATH, so CMake can find it.
Checkout the THIRDPARTY GitHub Repository and flatten the structure for the target platform, e.g. copy all subdirectories in ./all/ to ./Windows/64bit/.
Configure OpenMS as usual with additional flags SEARCH_ENGINES_DIRECTORY (for the flattened THIRDPARTY directory) and PACKAGE_TYPE="nsis", e.g.

cd <build-tree>

cmake ... -DSEARCH_ENGINES_DIRECTORY=C:/dev/THIRDPARTY/Windows/64bit -DPACKAGE_TYPE="nsis" <path-to-source-tree>
Build all targets (incl. 'doc' and 'doc_tutorials') in Release mode (copy the Qt5 plugin to the [OpenMS_build]/bin/Release and [OpenMS_build]/doc/doxygen/parameters/Release/ directories first)
cd <build-tree>

build.bat - r
Create the installer package
cd <build-tree>

cmake --build . --target dist