[[TOC]]

== Checking out Mars ==

First you need to get Mars from the svn-repository. The default command will checkout it into a sub-directory called "{{{directory}}}" at the current directory. It will be created if not existing. If the argument is omitted, the default directory is Mars.

{{{
[0] svn checkout https://www.fact-project.org/svn/trunk/Mars [directory]
[1] cd Mars
}}}

== Creating the build system ==

Now create a new sub-directory '''build''' (or with your preferred name) in your main source directory (here assuming the default name was used)

{{{
[2] mkdir build
[3] cd build
}}}

Before you run *cmake*, please make sure that your root environment has been properly initialized. With recent ROOT versions it is often enough if `root-config` is in your path. That is usually the case if you can execute root easily from your command line (or root-config itself) or if `export | grep ROOTSYS` gives a reasonable result. Otherwise, call `thisroot.sh` from your root installation. Assuming root is installed in /opt/root-6.14.04, this would be:
{{{
[X] . /opt/root-6.14.04/bin/thisroot.sh
}}}

Be aware of the dot in front of the path! Note that switching from a newer to an older version in this way might fail (CMAKE_PREFIX_PATH will still point to the previous version).

Now call {{{cmake}}} from there (the "{{{..}}}" is intentional!)

{{{
[4] cmake ..
}}}

As a default, the project is compiled with the build type ''Release'', thus all optimization is enabled and debug symbols are switched off. To enable debug symbols, you can use the build mode 'Debug' or '!RelWithDebInfo', e.g.

{{{
[4] cmake -DCMAKE_BUILD_TYPE=Debug ..
}}}

As a default, cmake will try to find the compiler suite 'clang/clang++', 'gcc/g++' and 'cc/c++' (in this order). If you want to define a compiler yourself, then you can call cmake like this
{{{
[4] cmake -DCMAKE_C_COMPILER=clang-4.0 -DCMAKE_CXX_COMPILER=clang++--4.0 ..
}}}

instead. If you are not sure which compiler to use, just use the default and see if it works. (In almost all cases using a different compiler is not worth it)

CMake will check for the availability of all important packages. For Mars, this is mainly *root* and *libnova*. Although, we have managed to compile Mars with pre-installed binary packages, it is advised that you install root from scratch (see http://root.cern.ch). Libnova (if there is no package available -- don't forget the dev-package!) can be found here http://libnova.sourceforge.net/index.html and should be easy to compile (`./configure && make`.

If a package is missing, you will see an error which looks like this

{{{#!default lineno=1
CMake Error at /usr/share/cmake-3.10/Modules/FindPackageHandleStandardArgs.cmake:137 (message):
  Could NOT find Nova (missing: NOVA_LIBRARY NOVA_INCLUDE_DIR)
Call Stack (most recent call first):
  /usr/share/cmake-3.10/Modules/FindPackageHandleStandardArgs.cmake:378 (_FPHSA_FAILURE_MESSAGE)
  cmake/FindNova.cmake:11 (FIND_PACKAGE_HANDLE_STANDARD_ARGS)
  CMakeLists.txt:131 (FIND_PACKAGE)
}}}

It is a bit tricky to find out which package is missing at the moment. The important line is line #2
{{{
Could NOT find Nova (missing: NOVA_LIBRARY NOVA_INCLUDE_DIR)
}}}
In this case, it is the development package of the nova library (libnova-dev).

If you find something missing during compilation which is not checked, please let me know. As a good practice please attach the complete output of {{{cmake}}} and of {{{make}}}. To clean up your build tree and start from scratch simple remove the directory ({{{rm -rf build}}}) and start over with step ![2]. 

''Hint'': To get an idea what cmake is doing or has done, you can call {{{cmake-gui .}}} in the build directory. Note that the {{{.}}} is required.

Usually, there is XXX_INCLUDE_DIR which is a path to the header files and XXX_LIBRARY which is the library filename (including path). 

To check what cmake actually found, you can call

{{{
[4] cmake-gui .
}}}


== Observatory ==

The default observatory is build in during compile time. This should avoid that by mistake and changed resource files, a wrong observatory location is selected. The default is La Palma (`ORM`). If you want to select a different location (ORM, HAWC, SPM, RWTH), you can do that when running cmake, for example, by

{{{
[4] cmake -DOBSERVATORY=HAWC ..
}}}

== Compiling Mars ==

Then call 

{{{
[5] make -jN
}}} 

where '''N''' is the numbers of threads you want to utilize (check the number of CPU cores you can keep busy). Or you can omit the {{{-jN}}} in case you want to run on a single CPU.

== Linking Problems ==

Mars itself only links with root libraries, standard C(++) libraries and libnova. If you have **any** linker problem, it is most likely related to the fact that you are linking environment during compilation of Mars (e.g. LD_LIBRARY_PATH) is not set identical to linking root. In most cases (I think) setting your root environment with **thisroot.sh** should help.

== Starting Mars ==

On success, by starting root in your build directory, you should see a message like
{{{
[0] root -l

Loading 'libmars.so'... done.

Welcome to the Mars Root environment.

root [0] 
}}}

Be aware that it might be slightly different for different versions (in particular of root).

You should now be able to use Mars.

How does that work? When you start root in your build directory, it reads `.rootrc` in your build directory. This file points to `rootlogon.C` in your build directory. This macro is executed when on root startup and loads the shared object `lib/libmars.so`. As all this uses absolute paths, you could even move `.rootrc` into your home directory and get the Mars environment no matter where you start root. As this works only with absolute paths, you might not change or rename the build directory without changing those files.

== Known to work ==

* cmake 3.5.0 / 3.5.1 / 3.10.2 / 3.15.3
* CentOS 6.8 and gcc 6.2.1 / 7.2.1
* Scientific Linux 6.10 and gcc 4.4.7
* Ubuntu 16.04 and clang 3.8 / 4 .0 / 5.0 / 6.0 or gcc 5.4.0
* Ubuntu 18.04 and clang 6.0 or gcc 7.3.0 / 7.4.0
* Peppermint 9 and clang 6.0 or gcc 7.3.0
* root 5.34/36, 5.34/38, 6.12/06, 6.14/04, 6.14/06, 6/18.04
* root binary packages might work
* libnova 0.12 / 0.15.0

Not all combinations might work though. And not all combinations might always be up-to-date in the repository as they can not always be tested. Please report if you find a problem with them so that it can be fixed.

If you have a too old version of cmake, you can download binary packages at https://cmake.org/download/. Usually, it is enough to call cmake with its full path to switch version. So just unpack the tar-ball and call the cmake binary in the package. Note that root already imposes requirements on cmake which can be found at InstallingROOT.

== Known Problems ==

There are many different build systems for root (e.g. root 5, root 6), different ways to install root (use build dir, run install, install your own package, install root binary builds). All these build systems interact differently with cmake. I believe that right now, it should work for most root installations, but I can not guarantee. If there is any hint that your installation files due to root issues, please contact me. Also make sure that the version of root-config that is found by cmake is consistent with your ROOTSYS and the root version you are actually going to use.