 |
OpenMS
|
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
Pre-Requisites (Software)
7-Zip (see http://www.7-zip.org/) 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. Qt comes in two flavors: commercial or non-commercial - choose whatever is applicable to you: read more on the Qt website. For several recent Qt6 versions, there are binary development versions available for the most recent compilers.
Installation of Qt6 via the Qt6 installer (requires an admin account):
Go to https://www.qt.io/download and find the download for the Qt binaries installer, download it and run the Qt binary installer. You will need to create a free user account with Qt, and log into that account during installation. The installer will ask for an installation directory, choose, e.g. c:\dev\qt6. From the components choose a matching version, e.g. Qt 6.7.1 and pick the MSVC binaries (e.g. MSVC 2019 64-bit), the Sources (for Qt headers) and Qt Debug Information files (optional).
If your Visual Studio version is more recent than the VS offered by the Qt installer, choose the closest available – they should be compatible. Resulting files appear under c:\dev\qt6\$VERSION (if you chose c:\dev\qt6 as installation directory).
Alternatively (no admin account required), compile Qt from sources. We cannot cover all the details here. See https://wiki.qt.io/Building_Qt_6_from_Git for details.
Finally, add the Qt bin directory (i.e the location of Qt6Core.dll, e.g. C:\dev\qt6\6.7.1\msvc2019_64\bin)to your Windows PATH Environment variable. If you forget this, starting any OpenMS executable will result in an error such as The program can't start because Qt6Networkd.dll is missing from your computer.
In addition, to run any of OpenMS' GUI apps (such as TOPPView), you need set the QT_PLUGIN_PATH environment variable to the plugins subdir of your Qt installation. E.g. set QT_PLUGIN_PATH to c:\dev\qt6_2\6.7.3\msvc2019_64\plugins.
For most of the steps below you need a command prompt which is aware of where components of Visual Studio (compiler, linker etc) are installed. Do not use a plain 'cmd' Command prompt. Certain steps will fail or find the wrong components (mostly when running CMake).
Open a VisualStudio Developer Command prompt for x64 (64-bit) since OpenMS only builds as 64-bit! (by default you may get a 32-bit environment)
"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" "C:\Program Files\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" tools/load_vcvarsall.sh if you are building in bash on Windows.OpenMS depends on several other libraries. On a Windows system, these are usually not present. 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
Download:
For development and cutting edge functionalities we recommend using the Git version of OpenMS from GitHub.
We will now clone OpenMS and checkout with the contrib submodule (and other submodules e.g. for search engines along with it).
The contrib sources are located in the contrib subfolder of the OpenMS source repository.
To obtain the latest (potentially unstable) version of OpenMS (and its contrib) use:
If you want to use a release version of OpenMS, use the corresponding Release-tagged version on GitHub (https://github.com/OpenMS/OpenMS/tags), e.g.
Installation:
After you got the source code for the contrib package follow these steps:
mkdir contrib_build Call CMake to build the contrib
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. 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:
<path_to_contrib_build>/lib directory to your PATH Environment Variable (this is so Windows can find the DLL's when running our executables). 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:
c:\programs\gs\gs8.60\bin) to the Windows PATH Environment dot. 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!
This part assumes section Contrib installation and QT installation have been completed! I.e. we assume you have the OpenMS source code and will now build the OpenMS library, TOPP tools, class tests etc.
To create the build system:
mkdir OpenMS_build Call CMake to create the build system
The CMAKE_PREFIX_PATH should hold the path to your Qt6 build/binary directory where Qt6Config.cmake resides (see example below). Note that it is NOT the main Qt6 directory, but the subfolder which is named after the toolchain it was build with (e.g. CMAKE_PREFIX_PATH=C:\dev\qt6_2\6.7.3\msvc2019_64\lib\cmake\Qt6).
The choice of <generator> depends on your system. Type cmake –help to see a list of available generators.
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:
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
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 |
| 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. For development, install prefixes are not supported. In this case OpenMS must be built in place! |
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).
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 binaries (dll's and executables) 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.
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.
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/.
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.
Example:
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, callThis 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.
Git: clone, then type and search for OpenMS/OpenMS. Select a folder. Wait for clone to finish. Open clone. Trust authors. source tools/loadvcvarsall.sh && load_msenv && git submodule update –init contrib && mkdir contrib-build && cd contrib-build && cmake -DBUILD_TYPE=ALL ../contrib > CMake: Select Kit, select preferably "Visual Studio Build Tools Release 2022 - amd64" > CMake: Configure 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.
Build all targets (incl. 'doc' and 'doc_tutorials') in Release mode (copy the Qt6 plugin to the [OpenMS_build]/bin/Release and [OpenMS_build]/doc/doxygen/parameters/Release/ directories first)
1.9.1