 |
OpenMS
|
This document describes how to build OpenMS from source obtaining most dependencies automatically by using vcpkg. If you only want to use the OpenMS PiPeline (TOPP), you are strongly encouraged to download the binary installer from the OpenMS website instead of building OpenMS 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.
OpenMS can obtain its third-party dependencies (Boost, Eigen, Apache Arrow, etc.) through vcpkg, Microsoft's cross-platform C/C++ package manager. vcpkg resolves the manifest and builds or restores packages as needed in a fixed, reproducible configuration, which make it the easiest way to get a consistent set of libraries across Linux, macOS and Windows.
OpenMS need an underlying compiler, build generator, and (because some vcpkg ports build upstream projects using an autotools build system, and because WITH_GUI is on by default) the autotools chain and GUI/OpenGL prerequisites below.
The minimum supported compilers on GNU/Linux are:
You should install system dependencies using the following commands:
Apple Clang is the officially supported compiler on macOS for building OpenMS (GCC can be used at your own risk). OpenMS is tested with the Apple Clang toolchain that ships with the last three Xcode releases. Xcode 16 or later is required for C++23 support.
A minimal installation of Apple Clang is achieved by downloading Apple's "Command Line Tools". However we suggest using a full Xcode installation from the Mac App Store. More details can be found on the Apple Developer Site.
For installing dependencies we suggest using the Homebrew package manager. After installing Homebrew the following commands will install all needed system dependencies for OpenMS:
The officially supported compiler is Microsoft Visual C++ which comes with Microsoft Visual Studio Build Tools. For a minimal installation we recommend you scroll to the bottom of the page and get the build tools only.
Visual Studio 2022 version 17.14 (MSVC toolset 14.44) or later is required. Note that this is higher than what C++23 alone would need: older toolsets cannot compile the Apache Arrow dependency, because of a bug in the standard library's <chrono> formatter for zoned_time durations coarser than seconds (LWG-4124, fixed by microsoft/STL#5155).
We also recommend that you install Git for Windows and Chocolatey. You can then using the following Bash commands from the Git Bash terminal to install the required system dependencies:
Begin by obtaining a copy of the OpenMS source code:
Configure, build and (optionally) test using a preset name for your platform. For example, on Linux x64:
The resulting build directory is build/linux-x64-release (each preset gets its own directory, so debug/release/relwithdebinfo builds don't clash). Substitute the preset name for your platform and desired build type; run cmake --list-presets to see all available presets, including the *-ci presets used by the CI pipeline, which additionally enable most optional features via VCPKG_MANIFEST_FEATURES (see below).
On Windows the same three commands work unchanged with a windows-x64-* preset – with Ninja as the default generator. If you would rather work in the Visual Studio IDE, add the generator on the configure line. In order to switch between Debug and Release builds in the Visual Studio IDE, you need to choose the 'debug' preset, since vcpkg's port files always build release, and debug only optionally on top. Therefore, a debug preset gives you both release+debug libraries. The 'release' preset only supports release builds (attempting a debug build in Visual Studio will fail).
Thus, for a multi-config build (Debug+Release) open the Developer Command Prompt, in the OpenMS source directory:
That writes build/windows-x64-debug/OpenMS_host.sln, which you can open in Visual Studio. OpenMS requires Visual Studio 17.14 or newer, so adjust the generator name if you are on a later release (cmake --help lists the generators your CMake knows about). The first configure of a given preset can take a while, since it builds all vcpkg dependencies for that triplet from source; subsequent configures reuse the already-built packages from build/<preset>/vcpkg_installed/.
To build OpenMS and run the tests with the Visual Studio (multi-configuration) generator, invoke this (the debug preset supports both Release and Debug there). Note that the default Ninja presets are single-configuration: a debug preset then builds only Debug, even though vcpkg still installs both release and debug libraries.
If you need a configuration that isn't covered by a preset, you can still configure manually, mirroring what the presets do under the hood:
The source tarball of a release does not contain the vcpkg submodule, but it does contain vcpkg.json, vcpkg-configuration.json and vcpkg-overlays/. Enable vcpkg and point CMake to the toolchain of a vcpkg checkout of your own (vcpkg needs network access to fetch the registry baseline named in vcpkg-configuration.json):
or build against system packages as described in Building without vcpkg (system packages).
The presets use vcpkg (OPENMS_USE_VCPKG=ON). Without a preset, OPENMS_USE_VCPKG is OFF and OpenMS takes its dependencies from the system (apt, Homebrew, conda/Bioconda) and from the prefixes in CMAKE_PREFIX_PATH:
The installed libraries must meet the minimum versions of OpenMS; the presets build the dependency set that CI tests. dockerfiles/Dockerfile is an example of a build on Ubuntu packages. If you set -DOPENMS_USE_VCPKG=ON without a preset, pass the vcpkg toolchain as shown above, otherwise the configure stops with an error that names the alternatives.
Every preset builds with Ninja, which is set once in the hidden base preset that all the others inherit. A cmake --preset ... therefore always produces a Ninja build tree — on Windows that means you get no Visual Studio solution file. Ninja has to be on your PATH: on Windows it ships with Visual Studio and is already on the path inside a Developer Command Prompt, and on Linux/macOS it comes from your package manager.
To build with a different generator, pass -G on the command line; it overrides the generator baked into the preset. For example, cmake --preset windows-x64-debug -G "Visual Studio 17 2022" gives you a solution file instead. Run cmake --help for the list of generators supported on your platform.
CMake refuses to change the generator of an existing build tree (*"Does not match the generator used previously"*), so this only works on a build directory that does not exist yet. To switch one that is already configured, add --fresh or delete build/<preset>/ first.
CMAKE_BUILD_TYPE and pick the configuration at build time instead. Because the build presets do not pin one, cmake --build --preset windows-x64-release would build Debug, not Release. Name the configuration explicitly when using such a generator, e.g. cmake --build --preset windows-x64-release --config Release.You can set more CMake variables adding -DVARIABLE=VALUE options when calling CMake.
The most important CMake variables are:
| OPENMS_USE_VCPKG=On/Off | Take the third-party libraries from vcpkg (On) or from system packages and CMAKE_PREFIX_PATH (Off). With On, CMake needs the vcpkg toolchain: the presets and the initialized vcpkg submodule provide it, or pass -DCMAKE_TOOLCHAIN_FILE=<vcpkg root>/scripts/buildsystems/vcpkg.cmake. See Building without vcpkg (system packages). (Default: Off; the presets set On) |
|---|---|
| CMAKE_PREFIX_PATH | Additional search path for libraries. [MacOSX only] If you want to use libraries installed via Homebrew or MacPorts you might need to provide the corresponding paths
|
| 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. |
| OPENMS_VERIFY_INTERFACE_HEADER_SETS=On/Off | Enable public-header compile checks. Build all_verify_interface_header_sets explicitly; see Verifying public headers. (Default: Off) |
| 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) |
| BUILD_TOPP_TOOLS=On/Off | Build the TOPP command-line applications (src/topp). Set to "Off" to build only the core OpenMS library, e.g. for a standalone SDK consumed by an external application. ENABLE_TOPP_TESTING and ENABLE_PIPELINE_TESTING default to following this flag, and ENABLE_CWL_GENERATION requires it to be "On". (Default: On) |
| INSTALL_OPENMS_EXAMPLES=On/Off | Install the OpenMS example data alongside the library/tools. Set to "Off" to skip installing example data, e.g. for a minimal standalone SDK install. (Default: On) |
| WITH_OPENTIMS=On/Off | Enables support for reading Bruker TimsTOF .d directories directly (without prior conversion to mzML) via the opentims library. When enabled, OpenMS will attempt to locate a system installation of opentims; if none is found, it is fetched and built automatically from source via CMake FetchContent. Adds .d (and .d.zip) input to CometAdapter, FeatureFinderIdentification, FeatureFinderLFQ, FeatureFinderMetaboIdent, FileConverter, IonMobilityBinning, MetaboliteSpectralMatcher, NucleicAcidSearchEngine, OpenSwathPeakMapExtractor, OpenSwathWorkflow, PeakPickerIM, ProSE, ProteomicsLFQ, SageAdapter, SimpleSearchEngine and TransitionListEvidenceFilter. (Default: On) |
| ENABLE_OPENTIMS_TESTS=On/Off | Download Bruker TimsTOF test data sets (DDA and DIA) and enable the corresponding integration tests. Requires WITH_OPENTIMS=On. The test data are fetched automatically via CMake FetchContent when this option is turned on. (Default: Off) |
| 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 (such as Comet and 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) |
| USE_EXTERNAL_SQLITECPP=Off/On | Use external SQLiteCpp library from system instead of vendored version. Recommended for Linux distributions to avoid file conflicts. (Default: Off, On for Ubuntu in CI) |
| USE_EXTERNAL_JSON=Off/On | Use external nlohmann-json library from system instead of vendored version. Required on Ubuntu due to Apache Arrow bundling. (Default: Off, On for Ubuntu in CI) |
| USE_EXTERNAL_SIMDE=Off/On | Use external SIMDe library from system instead of vendored version. Recommended for Linux distributions. (Default: Off, On for Ubuntu in CI) |
| LP_SOLVER=AUTO/COIN/GLPK/HIGHS | Select the linear programming solver backend. AUTO (default) tries COIN-OR first, then GLPK, then fetches HiGHS automatically via FetchContent if neither is installed. Set to COIN, GLPK, or HIGHS to require a specific solver. |
| WITH_THERMO_RAW=On/Off | Enable native reading of Thermo Fisher RAW files via the openms-thermo-bridge C++/.NET library (fetched automatically via CMake FetchContent from GitHub). Requires a .NET runtime to be present at run time so that the managed bridge DLLs can be loaded. Install the .NET 8 runtime from https://dotnet.microsoft.com/download, or install the dotnet-runtime-8.0 package from your distribution's package manager. On Windows and macOS the required nethost library is bundled with the .NET SDK/runtime installer. On Linux you may need to install the additional libnethost-dev (Debian/Ubuntu) or dotnet-runtime-8.0 package explicitly. At run time the bridge's nethost/hostfxr locates the installed runtime automatically when .NET sits in a standard location. If you installed .NET to a non-default directory (for example via the dotnet-install.sh script or an xcopy install of the runtime), set the DOTNET_ROOT environment variable to that directory — the folder that contains the dotnet host and the shared/ sub-directory (e.g. export DOTNET_ROOT=/usr/share/dotnet) — so the runtime can be found. The managed half of the bridge (ThermoWrapperManaged.dll, its runtimeconfig.json and the Thermo CommonCore assemblies) is installed both next to the bridge library and into share/OpenMS/openms_thermo_bridge/managed; OpenMS looks in the OPENMS_THERMO_MANAGED_DIR environment variable first, then in the share directory, then next to the bridge library. To build without a NuGet/GitHub round trip for those assemblies, pass the bridge's own -DOPENMS_THERMO_BRIDGE_PREBUILT_MANAGED_DIR=/path/to/extracted-zip (the zip is published with every openms-thermo-bridge release) or -DOPENMS_THERMO_BRIDGE_DOWNLOAD_PREBUILT_MANAGED=ON; the native bridge then only needs the nethost headers from a .NET SDK / host pack. (Default: On) |
| ENABLE_THERMO_RAW_TESTS=On/Off | Download a small Thermo RAW test file and enable integration tests for the Thermo RAW reader. Requires WITH_THERMO_RAW=On and a working internet connection during CMake configuration. (Default: Off) |
| WITH_WNETALIGN=On/Off | Enable the Wasserstein network alignment feature (FeatureLinkerWNet TOPP tool). When enabled, the three header-only libraries pylmcf, wnet, and wnetalign are fetched automatically via FetchContent. (Default: Off) |
| WITH_ONNX=On/Off | Enables ONNX Runtime support for machine-learning based inference modules, currently used by the PeptDeep predictors. This option requires an external ONNX Runtime C/C++ installation that can be found by CMake. Usually this can be done by adding the root directory of an ONNX Runtime release package to
Alternatively, set |
| OPENMS_PEPTDEEP_MODEL_URL | [with WITH_ONNX] Base URL from which the PeptDeep ONNX model files are downloaded during configuration, e.g. a mirror for a build without access to archive.openms.de. (Default: http://archive.openms.de/openms/models) |
| 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. For development, install prefixes are not supported. In this case OpenMS must be built in place! |
cmake at least once.
Optional OpenMS features that pull in additional dependencies (HDF5, ONNX Runtime, the Wasserstein network alignment libraries, etc.) need two things to be turned on together: the corresponding CMake option (e.g. -DWITH_HDF5=ON, -DWITH_ONNX=ON) and the matching vcpkg manifest feature via -DVCPKG_MANIFEST_FEATURES="<feature1>;<feature2>;...", so that vcpkg actually installs the extra dependency. The *-ci presets show an example enabling several of these together:
See Building OpenMS on GNU/Linux or other operating system build docs for the full list of WITH_*/USE_EXTERNAL_* build flags and what each optional feature does.
The set of dependencies and their versions or features are declared in the manifest file vcpkg.json at the root of the repository, and an overlay settings are declared in vcpkg-configuration.json. For a general introduction to vcpkg and manifest mode, see the vcpkg documentation.
Most of the libraries OpenMS depends are available, unmodified from the public vcpkg directory. A few, however needs a patch, file changes or do not exist in the registry at all (for example the header-only pylmcf/wnet/wnetalign libraries used for Wasserstein network alignment feature or the openms-thermo-bridge library used for native Thermo RAW file support). For these cases OpenMS ships its own overlay ports in the vcpkg-overlays/ directory:
vcpkg-overlays/ports contain one subdirectory per port. A port here can either replace a port of the same name from the public registry(e.g., to apply a patch or edit the existing port files) or provide an entirely a new port that is not available upstream at all (e.g., opentime, isospec, pylmcf, etc.).vcpkg-overlays/triplets contains custom triplets used to build these dependencies with non-default settings.These locations are wired up via the overlay-ports and overlay-triplets keys in vcpkg-configuration.json, so vcpkg automatically picks them up whenever it resolves a port name. If you need to add or edit the corresponding subdirectory under vcpkg-overlays/ports; see the vcpkg overlay-ports and the packaging details for details on writing a overlay-port.
1.9.8