.. _compiling:

.. py:currentmodule:: mod
.. cpp:namespace:: mod

Compiling from Source
=====================

.. _quick-start:

Quick Start
-----------

These are simplified instructions for Ubuntu, Fedora, Arch, and macOS.
If a step doesn't work or fit your case, please consult the sections below.

First, get MØD and install the easy dependencies:

.. code-block:: bash

	git clone --recursive https://github.com/jakobandersen/mod.git
	cd mod
	./bootstrap.sh
	pip3 install -r requirements.txt  # may need --user to install in home folder instead of system folders
	# Ubuntu:
	sudo apt install $(bindep -b | tr '\n' ' ')
	# Fedora:
	sudo dnf install $(bindep -b | tr '\n' ' ')
	# Arch:
	sudo pacman -Suy $(bindep -b | tr '\n' ' ')
	# macOS:
	brew tap Homebrew/bundle  # may not be needed
	brew bundle

Then:

1. (Ubuntu and Fedora < 33)
   Install Boost from source, see :ref:`install_boost_python`.
   Remember the installation path.
2. (Optional) Install CPLEX. Remember the installation path.
3. (Ubuntu) Install Graphviz from source:

   .. code-block:: bash

   	sudo apt install librsvg2-dev libpango1.0-dev
   	wget http://graphviz.gitlab.io/pub/graphviz/stable/SOURCES/graphviz.tar.gz
   	tar -xf graphviz.tar.gz --one-top-level=graphviz --strip-components=1
   	cd graphviz
   	./configure
   	make
   	sudo make install

Finally, compile and install MØD:

.. code-block:: bash

	mkdir build
	cd build
	# Without CPLEX:
	cmake ../ -DCMAKE_PREFIX_PATH=path/to/boost
	# With CPLEX:
	cmake ../ -DCMAKE_PREFIX_PATH=path/to/boost -DCPLEX_DIR=path/to/cplex
	make
	sudo make install


From a Git Repository
---------------------

After a checkout of the desired version, do:

.. code-block:: bash

	git submodule update --init --recursive
	./bootstrap.sh

This is needed to first fetch certain dependencies and second
to generate build files, extract the API documentation,
and create the file ``VERSION`` based on the current commit.

See :ref:`source-build` on how to then build the package.


As Dependency of Another CMake Project
--------------------------------------

MØD supports use via ``add_subdirectory`` in CMake.
The target ``mod::libmod`` is exported,
which can be used with ``target_link_libraries`` to link against libMØD.
The version is in the variable ``mod_VERSION``.
Note that running ``./bootstrap.sh`` is still needed if the
source is a repository clone (e.g., a Git submodule).


.. _source-build:

From a Source Archive
---------------------

The package is build and installed from source as a CMake project.
Generally that means something like:

.. code-block:: bash

	mkdir build
	cd build
	cmake ../ <options>
	make -j <n>
	make install

A source archive can also be created with ``make dist``.

The following is a list of commonly used options for ``cmake``.
Additional options specific for MØD along with their default valule are also
listed.
See also :ref:`dependencies` for elaboration on some of them.

- ``-DCMAKE_INSTALL_PREFIX=<prefix>``, set a non-standard installation
  directory. Note also that the `GNUInstallDirs
  <https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html>`__
  module is used.
- ``-DCMAKE_BUILD_TYPE=<build type>``, set a non-standard build type.
  The default is `RelWithDebInfo
  <https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=build_type#variable:CMAKE_BUILD_TYPE>`__.
  An additional build type ``OptDebug`` is available which adds the compilation
  flags ``-g -O3``.
- ``-DCMAKE_PREFIX_PATH=<paths>``, set a ``;``-separated list of paths used for
  finding most dependencies. The paths should generally be the prefixes
  specified when the dependency was installed.
  See also https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html#variable:CMAKE_PREFIX_PATH.
- ``-DBUILD_DOC=on``, whether to build documentation or not.
  This is forced to ``off`` when used via ``add_subdirectory``.
- ``-DBUILD_POST_MOD=on``, whether to build the post-processor or not.
- ``-DBUILD_POST_MOD_FMT=on``, whether to build the Latex format files used by
  the post-processor or not.
  Format files may need to be updated when the Latex compiler is updated,
  so when making a binary distribution of MØD that does not include the Latex
  compiler, it is probably a good idea to set this to ``off``.
  If the format files are not installed they will be compiled dynamically
  by the post-processor when needed, i.e., making each post-processor run
  slightly slower.
  Alternatively, the format file can be (re)installed by the post-processor
  using the
  :option:`mod_post --install-format`/:option:`mod_post --install-format-sudo`
  options.
- ``-DBUILD_PY_MOD=on``, whether to build the Python bindings or not.
- ``-DBUILD_PY_MOD_PIP=on``, whether to install the Python bindings via pip or
  not. The bindings are always installed in the ``<prefix>/lib`` folder, so
  a normal ``import`` in Python will probably not find the module.
  Having this setting on will enable a build of a fake Python package to be
  installed via ``pip`` in the default system folder. This fake package will
  redirect the import to the real location.
  This package can be uninstalled with ``pip uninstall mod-jakobandersen``.
- ``-DBUILD_TESTING=off``, whether to allow test building or not.
  This is forced to ``off`` when used via ``add_subdirectory``.
  When ``on`` the tests can be build with ``make tests`` and run with ``ctest``.
- ``-DBUILD_TESTING_SANITIZERS=on``, whether to compile libraries and tests
  with sanitizers or not. This is forced to ``off`` when ``BUILD_COVERAGE=on``.
- ``-DBUILD_EXAMPLES=off``, whether to build and allow running of examples as
  tests or not.
  This is forced to ``off`` when used via ``add_subdirectory``.
  This is forced to ``off`` when ``BUILD_TESTING`` is ``off``.
- ``-DBUILD_COVERAGE=off``, whether to compile code and run tests with GCov.
  When ``on`` the sanitizers on tests will be disabled.
  After building the tests, execute ``make coverage_collect`` without parallel
  jobs to run tests. Afterwards, execute ``make coverage_build`` to compile the
  code coverage report.
- ``-DENABLE_SYMBOL_HIDING=on``, whether symbols internal to the library are
  hidden or not. Disabling this option may degrade performance, and should only
  be done while developing extensions to the C++ library.
- ``-DENABLE_DEP_SYMBOL_HIDING=on``, whether symbols from library dependencies
  are hidden or not. Disabling this option may make it slower to load the
  library at runtime.
- ``-DENABLE_IPO=on``, whether to use link-time optimization or not.
  Disabling this option may degrade performance, but speed up linking time.
  As default the link-time optimizer will only use 1 thread.
  To use more threads, e.g., 7, use the following options for configuration
  ``-DCMAKE_MODULE_LINKER_FLAGS="-flto=7" -DCMAKE_SHARED_LINKER_FLAGS="-flto=7"``,
  when using GCC as the compiler.
- ``-DUSE_NESTED_GRAPH_CANON=on``, whether to use the dependency GraphCanon
  from the Git submodule or not.
- ``-DUSE_NESTED_NLOHMANN_JSON=on``, whether to use the dependency
  `nlohmann/json <https://github.com/nlohmann/json>`__ from the Git submodule
  or not.
- ``-DWITH_LOLA=on``, whether to enable/disable features depending on LoLA.
- ``-DWITH_OPENBABEL=on``, whether to enable/disable features depending on Open Babel.
- ``-DWITH_CPLEX=on``, whether to enable/disable features depending on CPLEX.
- ``-DWITH_CLP=on``, whether to enable/disable features depending on CLP.


.. _dependencies:

Dependencies
------------

Python dependencies are listed in ``requirements.txt`` (which includes
``requirements_nodoc.txt``).

Dependencies that can be satisfied via the system package manager are listed in
``bindep.txt``. Any missing package can be listed using the
`Bindep <https://docs.openstack.org/infra/bindep/readme.html>`__ program
(which can be installed via ``requirements.txt``).

The following is a detailed list of all dependencies and the CMake switches
related to them.

- This documentation requires (``-DBUILD_DOC=on``):

  - A supported version of `Sphinx <http://sphinx-doc.org>`__.
  - The Python package ``sphinx-autoapi`` (module name: ``autoapi``).

- libMØD:

  - A C++ compiler with reasonable C++17 support is needed.
  - `Boost <http://boost.org>`__ dev >= 1.73
    (use ``-DBOOST_ROOT=<path>`` for non-standard locations).
  - `GraphCanon <https://github.com/jakobandersen/graph_canon>`__ >= 0.5.
    This is fulfilled via a Git submodule (make sure to do
    ``git submodule update --init --recursive``),
    but if another source is needed, set ``-DUSE_NESTED_GRAPH_CANON=off``.
  - `nlohmann/json <https://github.com/nlohmann/json>`__ >= 3.7.3.
    This is fulfilled via a Git submodule (make sure to do
    ``git submodule update --init --recursive``),
    but if another source is needed, set ``-DUSE_NESTED_NLOHMANN_JSON=off``.
  - (optional) `LoLA <http://www.informatik.uni-rostock.de/tpp/lola/>`__,
    Low-level petri-net analyser (``-DWITH_LOLA=on``).
  - (optional) `Open Babel <http://openbabel.org>`__ dev, >= 2.3.2
    (``-DWITH_OPENBABEL=on``).
  - (optional) An ILP solver from the following list.
    At run-time, use the function
    :cpp:func:`getAvailableILPSolvers`/:py:func:`getAvailableILPSolvers`
    to see which have been enabled.

    - CPLEX dev (``-DWITH_CPLEX=on``, use ``-DCPLEX_DIR=<path>`` to specify the
      installation path).
      Depending on the CPLEX version it *may* require a license file to be
      accessible. See the documentation of CPLEX for this. Newer versions of
      CPLEX do not have this requirement.
    - CBC dev (``-DWITH_CBC=on``) from the COIN-OR package, along with
      a compatible LP solver:

      - CLP from the COIN-OR package, and included in CBC.

- PyMØD (``-DBUILD_PY_MOD=on``):

  - Python 3 dev
  - Boost.Python built with Python 3
  - (Optional) IPython 3

- PostMØD (``-DBUILD_POST_MOD=on``):

  - ``pdflatex`` available in the ``PATH`` or in ``CMAKE_PROGRAM_PATH``,
    with not too old packages (Tex Live 2012 or newer should work).
  - ``pdf2svg`` available in the ``PATH`` or in ``CMAKE_PROGRAM_PATH``.
  - ``dot`` and ``neato`` from Graphviz available in the ``PATH`` or in
    ``CMAKE_PROGRAM_PATH``.
    They must additionally be able to load SVG files and output as both SVG and
    PDF files (all via cairo).
    That is, in the output of ``dot -P`` the following edges must exist:

    - ``cairo_device_svg -> output_svg``
    - ``cairo_device_pdf -> output_pdf``
    - ``rsvg_loadimage_svg -> render_cairo``

  - If you install Graphviz from source, you can check if the status output in
    the end of ``configure`` includes the following two lines::

    	pangocairo:    Yes
    	rsvg:          Yes


.. _install_boost_python:

Boost and Boost.Python with Python 3
------------------------------------

A package with the sources of Boost can be downloaded from `http://boost.org`.


Basic Installation
""""""""""""""""""

Boost uses a custom build system which may be difficult to use.
A procedure for compiling and installing Boost with Python 3 for Boost.Python
is the following.

1. ``./bootstrap.sh --with-python=python3`` (optionally give
   ``--prefix=some/path`` to specify a non-standard installation path.
2. ``./b2`` (optionally give ``-j N`` (similar to GNU Make) to compile with
   multiple threads)
3. ``./b2 install`` (optionally give ``--prefix=some/path`` to specify a
   non-standard installation path (if not done earlier).

After ``bootstrap.sh`` has been run, the file ``project-config.jam``
has been created, which can be edited to customise installation path and a lot
of other things. All edits should be done before running ``b2``.


Non-standard Python Installation
""""""""""""""""""""""""""""""""

Passing ``--with-python=python3`` to ``bootstrap.sh`` should work.
This adds a line similar to "``using python : 3.3 ;``" to
``project-config.jam``.
After compilation (running ``b2``) the file ``stage/lib/libboost_python3.so``
should exist. If not, it did not detect Python 3 properly.

If Python is installed in a non-standard location, add the a line similar to
"``using python : 3.3 : python3 : /path/to/python/3/installtion/include ;``" to
``project-config.jam``, where the last path is the path to the
``include``-folder of the Python-installation.


Custom GCC Version
""""""""""""""""""

Before running ``b2`` create the file ``user-config.jam`` in the root of the
home dir (see `here
<http://www.boost.org/boost-build2/doc/html/bbv2/overview/configuration.html>`__
for the full documentation). Put a line similar to
"``using gcc : : /path/to/g++-4.8``" in the file.