![]() |
OpenMS
2.8.0
|
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
Pre-Requisites (Software)
7-Zip
(see http://www.7-zip.org/) 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, sqlite3, CoinMP, WildMagic, libSVM, libHDF5, glpk, zlib, libbz2 and Xerces-C. This contrib package has several advantages over manual installation
Download:
If you plan to use the development version of OpenMS, clone OpenMS and checkout the optional contrib submodule with
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:
"C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
to get one! "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"
. (Same goes for VS2019) 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.
The <generator>
you use must be one of the Visual Studio Generators. This is because some contrib libs require Visual Studio to build. Use the -A x64
flag to build 64-bit libraries for the contrib (32-bit does not really make any sense for LC-MS data processing)! Type cmake -help
to see a list of available generators.
Example:
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. 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.10.0 and the MSVC component that fits your Visual Studio version and architecture (most likely only 64bit is supported anymore). You can deselect QTCreator under Tools. Accept the license, choose startmenu entries if wanted and install. Resulting files appear under "c:\dev\QT\$VERSION".
To build Qt from sources, download Qt5 from their git repository ad follow the steps below:
Follow this procedure if you want to compile Qt yourself:
-platform
param for the next configure command (e.g., -platform win32-msvc2012
) -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.9/
). Check more options and supported compilers here: http://doc.qt.io/qt-5/configure-options.html (especially for developers). Note that part of Qt requires Python to compile, so its a good idea to add the Python executable to your path <path-to-qt>
and sub-directories. <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|...).
</ol>
@section create_doc 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 (<tt>doc</tt> & <tt>doc_internal</tt> targets), TOPP tutorials (<tt>doc_tutorials</tt> target) and more,
you will need to install three programs:
<ol>
<li> 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)
<ul>
<li> Download the installer for Windows (http://www.doxygen.org)
<li> Execute the installer. It should automatically add doxygen.exe to the Windows PATH Environment (please recheck)
</ul>
<li> 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).
<ul>
<li> Download binaries for Windows (http://miktex.org/)
<li> During installation tick "install missing packages on the fly = yes"
<li> The installer SHOULD add the bin directory of MikTeX automatically to the Windows PATH Environment (please recheck)
</ul>
<li> GPL Ghostscript (e.g. 8.60, 9.19) for Windows
<ul>
<li> Download binaries for Windows (http://www.ghostscript.com/) and install
<li> Add the <i><path_to_GHOSTSCRIPT>/bin</i> directory (e.g. c:/programs/gs/gs8.60/bin) to the Windows PATH Environment
</ul>
<li>
Optional:<br>
You can create dependency graphs using a doxygen plug-in called <tt>dot</tt>.
<ul>
<li> Download binaries for windows from http://www.graphviz.org (we tested: graphviz-2.18.exe)
<li> The installer should have added dot.exe to the Windows PATH Environment (please recheck)
</ul>
</ol>
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 <tt>cmake .</tt> in your build tree. No need to recompile the library!
@section install_win_openms Installing OpenMS
For development and cutting edge functionalities we recommend using the Git version from GitHub
@code
git clone https://github.com/OpenMS/OpenMS
\endcode
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 @ref install_win_contrib above (and skip the clone step).
<br>
Now, we create the build system:
<ol>
<li>Open a Visual Studio Command Line (use x64 version if you want 64bit apps – and yes, you want that!)
<li>Create a build directory for %OpenMS, e.g. <tt>mkdir OpenMS_Win64</tt>
@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.
<li>Call CMake to create the build system
@code
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>"
\endcode
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 <tt><path_to_qt>\\mkspecs</tt>. Here you will need to choose the matching directory for your architecture and Visual Studio version.
@note Example CMAKE_PREFIX_PATH: <tt>C:\\dev\\qt-5.9\\mkspecs\\winrt-x64-msvc2017</tt>
The choice of <tt><generator></tt> depends on your system. Type <tt>cmake –help</tt> 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 <tt>MSBuild</tt> also on VS solution files!
Use the <tt>-A x64</tt> 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 <tt>-T host=x64</tt> flag instructs Visual Studio to use a 64bit compiler and linker toolchain to avoid linker errors (<tt>LNK1210: exceeded internal ILK size limit; link with /INCREMNTAL:NO</tt>) during development (if the flag is omitted the 32bit toolchain is used to generate 64bit binaries).
Example:
@code
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
\endcode
</ol>
\includedoc "../doxygen/install/common-cmake-parameters.doxygen"
Now there should be a <tt>OpenMS_host.sln</tt> 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.<br>
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 @subpage external_code) 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.
@section install_win_topp 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.
<br>
<br>
After you have built %OpenMS, you can build the TOPP tools
by building the "TOPP" project in the IDE.
<br>
@section install_win_testing_openms 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 <tt>ctest</tt>.
Single tests can be run with <tt>ctest -R <testnameregex></tt>, e.g. <tt>ctest -R Base64_test</tt>.
For more syntax on CTest look at the online documentation at http://cmake.org/.
@section install_win_cmdline_openms 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 <tt>MSBuild.exe</tt>, e.g.
@code
MSBuild.exe <solution.sln> /maxcpucount /target:<target> /p:Configuration=<Config>
\endcode
Example:
@code
MSBuild.exe OpenMS_host.sln
\endcode
@note Since the call can be a bit lengthy, there is a batch file in
<tt>OpenMS/tools/build.bat</tt> and in the root of your build tree (copied
there by cmake for convenience), 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. For example
to build only the %OpenMS library in release mode, call
@code
build OpenMS r
\endcode
@section install_win_create_installer Creating an installer
<ol>
<li> Download <a href="https://sourceforge.net/projects/nsis/" target="_blank">NSIS</a> (we tested nsis-3.06.1 successfully) and extract it somewhere
<li> Install the <a href="https://nsis.sourceforge.io/Special_Builds" target="_blank">large-string-build NSIS installer</a> 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.
<li> Install the <a href="https://github.com/SuperPat45/UltraModernUI" target="_blank">UltraModernUI-plugin</a> on top (just extract into the same directory as NSIS).
We tested <a href="https://github.com/SuperPat45/UltraModernUI/releases/tag/2.0b6" target="_blank">version 2.0b6</a> successfully.
<li> Add the NSIS folder (which contains 'makensis.exe') to your PATH, so CMake can find it.
<li> Checkout the <a href="https://github.com/OpenMS/THIRDPARTY" target="_blank">THIRDPARTY GitHub Repository</a> and flatten the structure for the target platform, e.g. copy all subdirectories in <tt>./all/</tt> to <tt>./Windows/64bit/</tt>.
<li> Configure %OpenMS as usual with additional flags <tt>SEARCH_ENGINES_DIRECTORY</tt> (for the flattened THIRDPARTY directory) and <tt>PACKAGE_TYPE="nsis"</tt>,
e.g.
@code
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)