/**

  @page install_linux Building %OpenMS on GNU/Linux

  This document describes how to build %OpenMS on a GNU/Linux system from source.
  If you encounter errors during configuring/compiling our software,
  have a look at our @ref known_dev_bugs section and search in our <a href="https://github.com/OpenMS/OpenMS/issues">issue tracker</a>,
  maybe the error is already known.
  If not, please write to the <a href="https://lists.sourceforge.net/lists/listinfo/open-ms-general">mailing list</a>
  or report the error on our <a href="https://github.com/OpenMS/OpenMS/issues">issue tracker</a>.

  @note If you do not have root privileges on your system,
  make sure you read the section @ref build_linux_noroot.

  We are working on adding %OpenMS to the <a href=http://pkgs.org/search/openms>repositories</a> of the most popular distributions,
  but for many platforms the toolkit needs to be manually compiled on your system.
  The same applies if you want to use the most recent source files from our git repository.

  @section checkout_and_build Checkout OpenMS

  You can find the links to the release and development versions on the
  <a href="http://www.openms.de/downloads/">Downloads</a> page of the
  %OpenMS project.
  All source code, including the latest development version, is on github and can be obtained via git:

    \code
    # Assuming you are in ~/Development
    git clone https://github.com/OpenMS/OpenMS.git
    \endcode

  From here on, the instructions assume you have either an extracted tar.gz of a release and are inside its root, or checked out the development (git) version.

  Next, we will care for the dependencies upon which building %OpenMS from source relies.

  @section bin_dep Dependencies obtainable in binary form

  %OpenMS requires several other libraries to be present on your system.
  Most of these should be available in the repositories of your GNU/Linux distribution.

  For those libraries/versions often not found in the distro repositories, we provide sources and build scripts
  called "Contrib" build scripts.
  The Release tar.gz archive contains these libraries in the contrib/ folder,
  if you build the development (git) version, you'll find an empty submodule in that folder that you have to update first with
  \code
    git submodule update --init contrib
  \endcode

  <b>Despite that, in the following is a list of all required packages and libraries:</b>

  <ul>
    <li>
      Essential are \b gcc/g++ (>= 4.9) or similar ANSI C++ compiler with full C++11 support,
      \b CMake (>= 3.1; with >= 3.9 suggested), \b Qt5, \b patch, \b autoconf (> 2.60), \b automake (> 1.9), \b libtool (libtoolize/glibtoolize).
    </li>
    <li>
      For the complete feature set to be enabled, %OpenMS needs recent versions of
      \b Boost (>= 1.48), \b Eigen3 (>= 3.3.2), \b WildMagic5, \b libHDF5, \b libSVM (2.91 or higher but not 3.15),
      \b SeqAn (>= 1.4.0 but < 2.0 needed), \b glpk (>= 4.45) or \b CoinMP (>= 1.3.3), \b zlib, \b libbz2, and \b Xerces-C (>= 3.1.1).
      These should be built by our contrib build script in case they are not already installed via your package manager.
    </li>
    <li>
      Building the documentation from the development version requires doxygen (recommended: >= 1.8.13, required: > 1.5.4, some might be buggy in between) and pdflatex/texlive/texlive-full.
    </li>
    <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>
  </ul>

  For the most common distributions, we have compiled these commands which will install the required compatible libraries.
  There may be more libraries in your distributions packaging system, but beware of version incompatibilities.

  <table style="border-style:solid; border-collapse:collapse; border-color:#c0c0c0;" cellpadding="3px">
  <tr>
    <td><B>Fedora/RHEL/CentOS</B>
    <a href="http://koji.fedoraproject.org/koji/packages">packages</a>
  </td>
    <td><pre>
    # In newer distros change yum to dnf
    sudo yum groupinstall 'Development Tools'
    sudo yum install git tar
    # Especially on older CentOS versions <= 6 add the EPEL repo with additional updated packages
    sudo yum install epel-release
    # Update repo list for the thirdparty repository EPEL
    sudo yum repolist
    # Get REQUIRED installable contrib libraries
    sudo yum install cmake3 qt5-qtbase-gui qt5-qtbase-devel qt5-qtsvg-devel python-devel glpk-devel
    # Get OPTIONAL installable contrib libraries preferably from our Contrib package in the next step.
    #sudo yum boost-devel libsvm-devel libzip-devel zlib-devel xerces-c-devel bzip2-devel libhdf5-devel
    # NOTE that you might need to use cmake3 instead of cmake in the commands of the following steps.
    </pre>
    </td>
  </tr>
  <tr>
      <td><B>openSUSE >= 13.2<br/></B></td>
      <td><pre>
      # register obs://build.opensuse.org/devel:libraries:c_c++
      # tools
      sudo zypper install cmake gcc-c++ autoconf git patch automake libtool
      # REQUIRED dependencies
      sudo zypper install libqt5-qtbase-devel libqt5-qtsvg-devel python-devel glpk-devel
      # OPTIONAL dependencies, preferably installed with our Contrib package in the next step
      #sudo zypper install boost-devel libzip-devel zlib-devel \
      # libxerces-c-devel libbz2-devel libsvm-devel libhdf5-10
      </pre></td>
  </tr>
  <tr>
    <td><B>Ubuntu/Debian <br/>(16.04)</B></td>
    <td><pre>
    # include the ubuntu universe repository and update
    sudo add-apt-repository universe
    sudo apt update
    sudo apt-get install build-essential cmake autoconf patch libtool git automake
    sudo apt-get install qtbase5-dev libqt5svg5-dev libqt5opengl5-dev
    sudo apt-get install libboost-regex-dev libboost-iostreams-dev \
      libboost-date-time-dev libboost-math-dev libboost-random-dev libsvm-dev \
      libglpk-dev zlib1g-dev libxerces-c-dev seqan-dev libbz2-dev coinor-libcoinmp-dev libhdf5-dev
      # Use from contrib: EIGEN; SQLITE; WILDMAGIC (since libwildmagic-dev is buggy)
    </pre></td>
  </tr>
  <tr>
      <td><B>Ubuntu/Debian <br/>(>= 17.04)</B></td>
      <td><pre>
    # include the ubuntu universe repository and update
    sudo add-apt-repository universe
    sudo apt update
    sudo apt-get install build-essential cmake autoconf patch libtool git automake
    sudo apt-get install qtbase5-dev libqt5svg5-dev libqt5opengl5-dev
    sudo apt-get install libeigen3-dev libsqlite3-dev libwildmagic-dev libboost-random1.62-dev \
      libboost-regex1.62-dev libboost-iostreams1.62-dev libboost-date-time1.62-dev libboost-math1.62-dev \
      libxerces-c-dev libglpk-dev zlib1g-dev libsvm-dev libbz2-dev seqan-dev coinor-libcoinmp-dev libhdf5-dev
      # this should eliminate the need for building contrib libraries.
      </pre></td>
  </tr>
  <tr>
      <td><B>Ubuntu/Debian <br/>(= 19.10)</B></td>
      <td><pre>
    # include the ubuntu universe repository and update
    sudo add-apt-repository universe
    sudo apt update    
    sudo apt-get install build-essential cmake autoconf patch libtool git automake
    sudo apt-get install qtbase5-dev libqt5svg5-dev libqt5opengl5-dev
    sudo apt-get install libeigen3-dev libsqlite3-dev libwildmagic-dev libboost-random1.67-dev \
      libboost-regex1.67-dev libboost-iostreams1.67-dev libboost-date-time1.67-dev libboost-math1.67-dev \
      libxerces-c-dev libglpk-dev zlib1g-dev libsvm-dev libbz2-dev seqan-dev coinor-libcoinmp-dev libhdf5-dev
      # this should eliminate the need for building contrib libraries.
      </pre></td>
  </tr>  
  </table>

  @section build_linux_contrib Building remaining dependencies

  You can and should check which dependencies you still need by attempting to configure %OpenMS (see the next section),
  it will complain about anything unusual/missing.
  @warning Do not install libraries from our contrib package if it is installed on your system in a compatible version already. If you have an incompatible version, we suggest to update or deinstall and use the contrib version.
  @note In most cases, the only dependencies left unresolved (e.g. unavailable through your distributions packaging system) at this point are SeqAn, WildMagic and CoinOR.
  Contact us if you still have trouble with the dependencies \b after these
  instructions.

  The tar.gz of the Release contains the scripts for building all dependencies in the contrib/ folder.
  For the development (git) version, this so called submodule folder will be empty and has to be checked out separately.

  \code
  # Assuming you are in ~/Development/OpenMS
  git submodule update --init contrib
  cd ..
  mkdir contrib-build
  cd contrib-build
  \endcode

  For the contrib as well as for %OpenMS we suggest to use out-of-source builds.
  @note Generally all files generated while building %OpenMS have to go
  somewhere.
  In case of in-source-builds all files will be generated alongside the source code.
  While this is easy and a well known practice from the regular ./configure + make approach it also changes your build tree.
  It also prohibits building multiple configurations
  (e.g., Debug and Release or different compiler versions).
  As an alternative CMake offers the possibility to perform so called out-of-source builds.
  Here all build files, binaries, libraries, etc. are generated in a separate directory.

  From the <tt>./contrib-build/</tt> folder, execute the following command to show the
  available build types
     \code
        cmake -DBUILD_TYPE=LIST ../OpenMS/contrib
     \endcode
  and then build SeqAn (the other build scripts may or may not be needed to be
  executed depending on if your distribution does not provide a package for the dependency):
      \code
          cmake -DBUILD_TYPE=SEQAN ../OpenMS/contrib
          cmake -DBUILD_TYPE=WILDMAGIC ../OpenMS/contrib
          cmake -DBUILD_TYPE=EIGEN ../OpenMS/contrib       
      \endcode

  To avoid problems while building the libraries contained in the contrib package,
  the path to your contrib-build directory should not have any spaces in it. In case your distribution
  does not provide some of the packages (or in different versions than expected), it is sometimes easier
  to build all dependencies manually which can solve issues with incompatible versions:
      \code
          cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 ../OpenMS/contrib
      \endcode
  @section build_linux_noroot Building without root privileges

  If you are on a system without root access (e.g. a shared cluster), there are
  some additional considerations, especially regarding dependencies.
  Specifically, some older Red Hat systems have older libraries installed that
  may interfere with the newer versions that %OpenMS requires. The recommended
  installation procedure is to use the contrib package to compile <b>all</b>
  dependencies from source:

  \code
  cmake -DBUILD_TYPE=LIST ../OpenMS/contrib
  cmake -DBUILD_TYPE=ALL -DNUMBER_OF_JOBS=4 ../OpenMS/contrib
  \endcode

  Alternatively, you can build one package after the other by providing
  <tt>-DBUILD_TYPE=...</tt> with the appropriate argument. In addition, you
  may have to compile Qt yourself which you can get from <a
  href="http://download.qt.io/official_releases/qt">http://download.qt.io/official_releases/qt</a>
  (use version >5.5), if it is not provided on your server or the version on
  your environment is too old. Then you can use the traditional
  <tt>./configure --prefix=/path && make && make install</tt> sequence to compile
  and install Qt (note that you should set the <tt>--prefix=/path</tt> to a local directory assuming
  you don't have root privileges).


  @section install_linux_openms Configuring and building OpenMS/TOPP

  It is assumed that you have successfully built and installed all dependencies
  and are in the root folder of the %OpenMS tree (see above in @ref
  checkout_and_build for instructions how to obtain %OpenMS sources either from
  a release version or from the most recent development branch).

  The next step is to create a build directory beside the %OpenMS root
  directory e.g., <tt>OpenMS-build</tt> (see above note on out-of-source builds).

  \code
  # Assuming you are in ~/Development and OpenMS is also located in
  # ~/Development
  mkdir OpenMS-build
  cd OpenMS-build
  \endcode

  In the %OpenMS build directory we execute %CMake to <i>configure</i> %OpenMS. You
  should substitute <tt>/PATH/TO/contrib-build/</tt> with the above path to the built
  contrib. Make sure you use the <i>absolute</i> (and not relative) path for the
  contrib to avoid any potential issues.

  @note Since static versions of the boost library are on some systems (e.g. Ubuntu) compiled with different settings you have to set BOOST_USE_STATIC to OFF or compile it with our contrib.
  \code
  cmake -DOPENMS_CONTRIB_LIBS="/PATH/TO/contrib-build" -DBOOST_USE_STATIC=OFF ../OpenMS
  \endcode

  If CMake has problems finding system libraries, you might consider adding:
  \code
  -DCMAKE_PREFIX_PATH="/usr;/usr/local"
  \endcode
  to the CMake options.

  If CMake has problems finding Qt5 (Qt5SvgConfig.cmake is usually the first to fail), you might consider adding:
  \code
  -DQt5_DIR=/PATH/TO/qt/5.9.7/gcc_64/lib/cmake/Qt5
  \endcode
  to the CMake options, where <tt>/PATH/TO/qt/5.9.7/gcc_64</tt> depends on your system settings and Qt version.

  When configuring %OpenMS, consider setting <tt>WITH_GUI=Off</tt> and
  <tt>HAS_XSERVER=Off</tt>, especially as you may not have compiled Qt with
  OpenGL and you may not have an X server.

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

  A full list of the CMake variables is shown when you execute

  \code
  ccmake .
  \endcode

  This works only after having executed <tt>cmake</tt> once (see @ref install_linux_openms)

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

  \code
  make
  \endcode

  Advanced users can list the separate make targets by calling:
  \code
  make targets
  \endcode


  @subsection linux_openms_environment Getting your environment ready to use OpenMS

  The previous step takes the most time, in the meanwhile you can prepare your
  environment for easy %OpenMS usage:

  Make sure to add <tt>/PATH/TO/OpenMS/lib/</tt> (e.g.
  <i>/home/smith/OpenMS/lib/</i>) to the environment variable
  <b>LD_LIBRARY_PATH</b>.  The best way is to edit <tt>$HOME/.bashrc</tt> and add the
  following
  \code
  export LD_LIBRARY_PATH="/PATH/TO/OpenMS/lib:$LD_LIBRARY_PATH"
  \endcode

  The TOPP tools will be built in the <b>/PATH/TO/OpenMS/bin/</b> folder. Add
  this path to the environment variable <b>PATH</b> to use the commands
  anywhere on your system.

  This is necessary to use the TOPP tools from TOPPView.

  You can do this by appending the following also to your <tt>$HOME/.bashrc</tt>
  (Do not use the tilde character @em ~ to abbreviate your home folder)

  \code
  export PATH=$PATH:/PATH/TO/OpenMS/bin
  \endcode

  Apply both changes by executing

  \code
  source ~/.bashrc
  \endcode

    @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 check out prebuilt executables of the versions supported
    at the time of the release 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=~/Development/OpenMS/THIRDPARTY/${FOLDER_FOR_YOUR_OS_ARCH}/XTandem:${PATH}
    \endcode
    If you want to enable the corresponding tests in CMake, this has to happen <b>before</b> you configure and build the
    project.

  @section running_linux_openms Running OpenMS
  If the build from @ref install_linux_openms is ready, you can now run a
  GNU/Linux %OpenMS tool by e.g. executing

  \code
  FileInfo
  \endcode

  From here on you should be good to go! See below for advanced installation and configuration options.

  @note Once %OpenMS is built, some thirdparty software used via adapter tools in %OpenMS might also require an installed JavaVM.

  <br/>
  <br/>


 <hr>
 @section install_linux_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 ctest you can also execute only a subset of tests by using the -R [REGEX] option and
  run tests in parallel using the -j parameter. For more information, consult ctest
  <a href="http://manpages.ubuntu.com/manpages/hardy/man1/ctest.1.html" target="_new">man page</a>.

    \code
    ctest -R TOPP_ -j 4
    \endcode

  Will run all TOPP test using 4 jobs. Make sure that you have build all tests beforehand by executing

    \code
    make
    \endcode

*/
