/**

  @page install_mac Building %OpenMS on Mac OS X

  @section install_mac_read Introduction

  This document 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
  <b>download the binary installer</b> (see
  <a href="http://www.OpenMS.de" target="_blank">here</a>), 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).
  <br>
  If you encounter errors during configuring/compiling our software, have a
  look at our @ref known_dev_bugs section, maybe the error is
  already known. If not, please write to the mailing list (open-ms-general AT lists.sourceforge.net) or report the error
  on our <a href="https://github.com/OpenMS/OpenMS/issues">issue tracker</a>.

  @subsection hint_package_manager Package Managers

  We suggest to use <a href="https://brew.sh/" target="_new">Homebrew</a>
  to install most of the requirements for %OpenMS to ease the process of
  upgrading those dependencies.

  @subsection required_apps Required applications

  In order to compile %OpenMS, several applications need to be installed:
  <ul>
   <li>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 <a href="https://developer.apple.com/xcode/" target="_new" title="Xcode Downloads and Resources.">Apple Developer Site</a>.</li>
   @note Since macOS El Capitan 10.11, the "Command Line Tools" can easily be installed via:
   \code
     xcode-select --install
   \endcode
   <li>CMake (version 3.1 or higher) is required to configure and build the %OpenMS as well as some of its dependencies.</li>
   <li>Qt5, its SVG module and the header files are required.
   @note We recommend installing Qt using Homebrew with:
   \code
     brew install qt5
   \endcode
   <li>
    Building pyOpenMS, the Python bindings for %OpenMS, requires Python, Cython and a few Python packages. See
    \ref pyOpenMS "here" for more detailed pyOpenMS build instructions.
   </li>
   <li>If you need to compile CoinMP yourself, you will also need gfortran as a Fortran compiler.</li>
  </ul>

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

  <ul>
   <li><a href="http://www.doxygen.org/index.html">Doxygen</a> (recommended: >= 1.8.13, required: > 1.7.1, some might be buggy in between) is used to generate the %OpenMS documentation.</li>
   <li>pdflatex is required to generate the tutorial PDFs. The latest MacTeX release can be downloaded <a href="http://tug.org/mactex/">here</a></li>
  </ul>

 <hr>
 @section install_mac_contrib 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, WildMagic, libSVM, libHDF5, SeqAn, glpk, zlib, bzip2, CoinMP and Xerces-C.

  The contrib package is contained in the %OpenMS release package and is
  available inside the <tt>contrib</tt> directory in the %OpenMS directory.

  If you are using the developer version of %OpenMS via
    \code
      cd ~
      mkdir openms-development
      cd openms-development
      git clone https://github.com/OpenMS/OpenMS
    \endcode
  you have to checkout the empty folder by calling the following command:
    \code
      cd OpenMS
      git submodule update --init contrib
    \endcode

  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.

  <ol>
    <li>Open a Terminal (<tt>/Applications/Utilities/Terminal.app</tt>)</li>
    <li>Create a build directory for the %OpenMS contrib e.g.,
        \code
        mkdir ~/openms-development/contrib_build
        \endcode
    </li>
    <li>Enter the created directory and call <tt>cmake</tt> to build the contrib

        \code
        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>
        \endcode

    Example:

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

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

  <ul>
    <li><tt>lib/</tt> containing the libraries needed by %OpenMS.</li>
    <li><tt>include/</tt> containing the header files needed for %OpenMS.</li>
  </ul>

  @subsection using_system_libs 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.

    \code
      brew install libsvm xerces-c boost glpk eigen sqlite hdf5
    \endcode

  @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.
  @note The compression libraries bzip and zlib should come with your macOS/XCode/commandline tools.

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

    \code
      sudo port install libsvm xercesc3 boost glpk eigen3 sqlite hdf5
    \endcode

 The rest needs to be installed via the contrib.

    \code
      # 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=SEQAN ~/openms-development/OpenMS/contrib
      cmake -DBUILD_TYPE=COINOR .
      cmake -DBUILD_TYPE=WILDMAGIC .
    \endcode

  <hr>

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

  @section install_mac_openms Installing OpenMS

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

  <ol>
    <li>Open a Terminal (<tt>/Applications/Utilities/Terminal.app</tt>)</li>
    <li>Create a build directory for %OpenMS, e.g.,
        \code
        mkdir ~/openms-development/openms_build
        \endcode
    </li>

    <li>Call <tt>cmake</tt> to create the build system there

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

      @note 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 <code>-DVARIABLE=VALUE</code> option.
      A full list of the CMake variables is shown when you execute

        \code
        ccmake ~/openms-development/openms_build
        \endcode
      @note General cmake variables can be found in the CMake help. Not all of them can be overwritten.
      @note You need to execute <tt>cmake</tt> at least once before
            <tt>ccmake</tt> can be used.
    </li>
  </ol>


  \includedoc "../doxygen/install/common-cmake-parameters.doxygen"

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

    \code
    make targets
    \endcode

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

    \code
    make
    \endcode

  The TOPP tools should now be ready to use. The executables are located in the
  \c bin folder of the build directory. Add this folder to your
  <b><tt>PATH</tt></b> variable for easy access.
  @note When you intend to use thirdparty search- or inference engines like XTandem or Fido, their binaries also
  need to be in the <b><tt>PATH</tt></b>. Build them or download them inside the OpenMS source folder with
  \code
  git submodule update --init THIRDPARTY
  \endcode
  and adapt the following for every thirdparty tool you want to use (shown for XTandem):
  \code
  export PATH=${PATH_TO_CLONED_OPENMS}/THIRDPARTY/${YOUR_OS}/${YOUR_ARCH}/XTandem:${PATH}
  \endcode
  If you want to enable the corresponding tests in CMake, this has to happen before you configure and build the
  project.

 <hr>
 @section install_mac_testing_openms Testing your OpenMS/TOPP installation

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

    \code
    make test
    \endcode

  or

    \code
    ctest
    \endcode

  Using <tt>ctest</tt> 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,

    \code
    ctest -R TOPP_ -j 4
    \endcode

  will run all TOPP test using 4 jobs.

  For more information, consult ctest
  <a href="http://manpages.ubuntu.com/manpages/hardy/man1/ctest.1.html" target="_new">man page</a>.

*/
