Building OpenMS on Mac OS X

Introduction

This document 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 binary installer (see here), instead of building OpenMS from sources. Be aware though that we do not provide binary installers for every MacOS version. For more information read the install instructions for the TOPP binaries.

This document especially considers the installation of several libraries that 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.

Package Managers

We suggest to use Homebrew to install most of the requirements for OpenMS to ease the process of upgrading those dependencies.

Required applications

In order to compile OpenMS, several applications need to be installed:

• We only support building OpenMS via the standard Appleclang compiler (GCC can be tried at your own risk) and compilation is tested only on the two or three most recent macOS versions. Minimal installation is achieved by downloading Apple's "Command Line Tools", however we suggest installing a full Xcode (the current version can be obtained from the Mac App Store; required is version 4.2 or greater). More details can be found on the Apple Developer Site.

  Note

  Since macOS El Capitan 10.11, the "Command Line Tools" can easily be installed via:

  xcode-select --install

• CMake (>= 3.24) is required to configure and build the OpenMS as well as some of its dependencies.
• Qt5, its SVG module and the header files are required.

  Note

  We recommend installing Qt using Homebrew with:

  brew install qt5

• Building pyOpenMS, the Python bindings for OpenMS, requires Python, Cython and a few Python packages. See here for more detailed pyOpenMS build instructions.
• If you need to compile CoinMP yourself, you will also need gfortran as a Fortran compiler.

If your OpenMS version is a development version obtained via Git, the following applications are needed in order to create the OpenMS documentation:

• Doxygen (recommended: >= 1.8.13, required: > 1.7.1, some might be buggy in between) is used to generate the OpenMS documentation.

---

Installing the contrib package

In order to facilitate the installation of the libraries required for OpenMS, we provide a "contrib-package" containing the libraries Boost, Eigen, libSVM, libHDF5, glpk, zlib, bzip2, CoinMP and Xerces-C.

The contrib package is contained in the OpenMS release package and is available inside the contrib directory in the OpenMS directory.

If you are using the developer version of OpenMS via

cd ~
mkdir openms-development
cd openms-development
git clone https://github.com/OpenMS/OpenMS

you have to checkout the empty folder by calling the following command:

cd OpenMS
git submodule update --init contrib

CMake is used to check your system and build the contrib libraries.

Note

To avoid problems while building the libraries contained in the contrib package, the path to your contrib directory should not contain any spaces.

1. Open a Terminal (/Applications/Utilities/Terminal.app)
2. Create a build directory for the OpenMS contrib e.g.,

   mkdir ~/openms-development/contrib_build

3. Enter the created directory and call cmake to build the contrib

   cd <path_to_contrib_build>
   cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang <path_to_OpenMS_contrib>

   Example:

   \code
   cd ~/openms-development/contrib_build
   cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang ~/openms-development/OpenMS/contrib
   \endcode
   

If everything worked, the following sub-directories were created under the contrib build directory:

• lib/ containing the libraries needed by OpenMS.
• include/ containing the header files needed for OpenMS.

Using system libraries

As an alternative to the contrib libraries shipped with OpenMS you can also use libraries installed via your package manager (Homebrew or MacPorts).

For Homebrew the following sequence of commands installs most of the libraries required by OpenMS.

brew install libsvm xerces-c boost glpk eigen hdf5

Note

Until the CoinMP complete package is migrated to the coin-or-tools tap, we suggest to use our contrib version. You will then additionally need gfortran as a Fortran compiler to build.

The compression libraries bzip and zlib should come with your macOS/XCode/commandline tools.

If using Boost from brew, since v1.75, its CMake config file links all dependent libraries to icu4c when using boost::regex as static library. Therefore, we suggest to use dynamic libraries in the OpenMS build stage.

For MacPorts the following sequence of commands installs some of the libraries required by OpenMS.

sudo port install libsvm xercesc3 boost glpk eigen3 hdf5

The rest needs to be installed via the contrib.

# assuming you cloned OpenMS to ~/openms-development/OpenMS
cd ~/openms-development/OpenMS
git submodule update --init contrib
mkdir ../contrib-build
cd ../contrib-build
cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -DBUILD_TYPE=COINOR ~/openms-development/OpenMS/contrib

---

Note

Some thirdparty software used via adapter tools in OpenMS might also require an installed Java Runtime (brew cask install java).

Building OpenMS

Assuming you have successfully cloned OpenMS and installed the required libraries, you can now build OpenMS. Therefore execute the following steps:

1. Open a Terminal (/Applications/Utilities/Terminal.app)

2. Create a build directory for OpenMS, e.g.,

   mkdir ~/openms-development/openms_build

3. Call cmake to create the build system there

   cd <path_to_OpenMS_build>
   cmake -DOPENMS_CONTRIB_LIBS=<path_to_contrib_build> -DCMAKE_PREFIX_PATH="$(brew --prefix);$(brew --prefix qt5)" <path_to_OpenMS>

   Note

   If you obtained Boost from Homebrew, please add -DBOOST_USE_STATIC=OFF to the above command!

   If you still have Qt4 installed make sure to brew uninstall or at least brew unlink it, so it is not picked up. The same holds for libraries that you built and passed with the contrib. You can set additional CMake variables using the -DVARIABLE=VALUE option. A full list of the CMake variables is shown when you execute

   ccmake ~/openms-development/openms_build

   Note

   General cmake variables can be found in the CMake help. Not all of them can be overwritten.

   You need to execute cmake at least once before ccmake can be used.

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>

After CMake was executed, you can list the make targets by calling:

make targets

In order to build the OpenMS library, the TOPP tools, tests and this documentation execute the following command:

make

The TOPP tools should now be ready to use. The executables are located in the bin folder of the build directory. Add this folder to your PATH variable for easy access.

Note

When you intend to use thirdparty search engines like XTandem, their binaries also need to be in the PATH. Build them or download them inside the OpenMS source folder with

git submodule update --init THIRDPARTY

and adapt the following for every thirdparty tool you want to use (shown for XTandem):

export PATH=${PATH_TO_CLONED_OPENMS}/THIRDPARTY/${YOUR_OS}/${YOUR_ARCH}/XTandem:${PATH}

If you want to enable the corresponding tests in CMake, this has to happen before you configure and build the project.

---

Testing your OpenMS/TOPP installation

After you have installed OpenMS and TOPP, you should test your installation by executing the following command:

make test

or

ctest

Using ctest you can also execute only a subset of tests by using the -R [SUBSTRING] option and run tests in parallel using the -j parameter. For example,

ctest -R TOPP_ -j 4

will run all TOPP test using 4 jobs.

For more information, consult ctest man page.