[[TOC]]

== Checking out FACT++ ==

First you need to get FACT++ 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 FACT++.

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

== 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
}}}

To install FACT++, it is rcommended to have a working ROOT environment. For the installation of ROOT, plese refer to [[InstallingROOT]].
Before you run *cmake*, please make sure that your root environment has been properly initialized. If you have `root-config` in your path (or `root -b` starts up properly) this is usually not necessary. In any case, if it is required, you should find `cmake` complaining about missing root. If you have to initialize the root environment or switch to a different root version call *thisroot.sh*, for example:
{{{
[X] . /opt/root-6.14.04/bin/thisroot.sh
}}}

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. Note that not all versions of {{{clang}}} are compatible with all version of the boost-libraries on Ubuntu. You might have to try different versions. (However, it is worth it, because {{{clang}}} is much faster).

If you only want to compile the basic tools (rootifysql, root2sql, fits2sql, fitsdump and zfits) you can add {{{-DTOOLS_ONLY=1}}} when calling {{{cmake}}}. This simplifies compilation because less packages are required (for example the whole Qt stuff is not needed).

If you only want to compile the *viewer* you can add {{{-DVIEWER_ONLY=1}}} when calling {{{cmake}}}. This simplifies compilation because less packages are required, but all the Qt stuff is required.

The two options {{{-DTOOLS_ONLY=1}}} and {{{-DVIEWER_ONLY=1}}} can be combined.

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 a path to the header files and XXX_LIBRARY which is the library filename (including path). You can then do, for exmaple

{{{
[4] cmake -DMYSQL_INCLUDE_DIR=~/mysql/include -DMYSQL_LIBRARY=~/mysql/libmysqlclient.so ..
}}}

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 FACT++ ==

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.

== Packaging FACT++ ==

Once successfully compiled, you can package the tool-set and build a tar-archive and a Debian package by the following instructions. This is usually *not* recommended. It is mainly meant for system wide installations not for userspace installations. 

{{{
[6] make package
}}}

The Debian package can then be installed system wide with 

{{{
[7] dpkg -i fact++-YYWWDDHH.deb
}}} 

where '''YYWWDDHH''' is the version number compiled from the time when {{{cmake}}} was called.

== FACT++ and ROOT v6 ==

In root versions >=6.18, the {{{qt}}} integration has been discarded. Therefore, the graphical interfaces {{{fact}}} is turned off if compiled with a root version >=6.18.

== Old Information ==

Some older information can be found here https://fact-project.org/FACT++/. It describes the old build system, but apart from that should be more or less accurate.

== Compilation on our systems ==

=== ISDC ===

Make sure that the root-version you wanna use is properly initialized by calling
{{{
/swdev_nfs/root_v5.34.38/bin/thisroot.sh
}}}

The start cmake before calling make:

{{{
/swdev_nfs/cmake-3.5.0-Linux-x86_64/bin/cmake \
-DTOOLS_ONLY=1 \
-DBOOST_ROOT=/swdev_nfs/boost_1_47_0/ \
-DMYSQL_LIBRARY=/swdev_nfs/mysql-5.7.23-linux-glibc2.12-x86_64/lib/libmysqlclient.so \
-DMYSQL_INCLUDE_DIR=/swdev_nfs/mysql-5.7.23-linux-glibc2.12-x86_64/include/ \
-DMYSQLPP_LIBRARY=/swdev_nfs/mysql++-3.2.4/libmysqlpp.so \
-DMYSQLPP_INCLUDE_DIR=/swdev_nfs/mysql++-3.2.4/lib/ \
-DNOVA_INCLUDE_DIR=/swdev_nfs/libnova-0.15.0/include/libnova/ \
-DNOVA_LIBRARY=/swdev_nfs/libnova-0.15.0/lib/libnova.so  \
/path/to/CMakeList.txt
}}}

It is all a newer version, a newer required version, or compiled with mysqlclient 5.7.23, or all of that. Make sure that the root-version cmake finds is also compiled with the same mysqlclient-library, e.g. by
{{{
/swdev_nfs/cmake-3.5.0-Linux-x86_64/bin/cmake \
-DMYSQL_LIBRARY=/swdev_nfs/mysql-5.7.23-linux-glibc2.12-x86_64/lib/libmysqlclient.so \
-DMYSQL_INCLUDE_DIR=/swdev_nfs/mysql-5.7.23-linux-glibc2.12-x86_64/include \
/swdev_nfs/root_v5.34.38-source/
}}}

== Known to work ==

* cmake 3.5.0 / 3.5.1 / 3.10.2
* Scientific Linux 6.10 with Boost 1.47.0 and gcc 4.4.7 
* Ubuntu 16.04 with Boost 1.58.0 and clang 3.8 / 4 .0 / 5.0 / 6.0 or gcc 5.4.0
* Ubuntu 18.04 with Boost 1.65.1 and clang 6.0 or gcc 7.3.0 / 7.4.0
* Peppermint 9 with Boost 1.65.1 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 (with Qt support compiled in)
* root binary packages might work if TOOLS_ONLY is enabled
* Qt4 4.8.7 / Qt5 5.9.5 (Qt5 compiles, but GUI does not work!)
* libqwt5-qt4 5.2.3 [with Qt4] 
* libqwt 6.1.3 [with Qt5]
* libz 1.2.3 / 1.2.8 / 1.2.11
* mysqlclient 5.7.23, 5.7.24, 5.7.27 (20.3.10) / 8.0.12 (21.0.12)
* mysql++ 3.2.2 / 3.2.4 (3v5)
* libssl 1.0.1e / 1.0.2g / 1.0.2n / 1.1.0g (openssl)
* libnova 0.12 / 0.15.0 / 0.16.0
* libv8 3.14.5 / libnode 10.19.00 (contains libv8 6.8.32)
* libreadline 7.0
* libncurses 5 (6.1)
* libcfitsio 5 (3.430)
* libccfits 0v5 (2.5)
* groff 1.22.3

Not all combinations might work though. (There are known problems with openssl 1.1.0 and Ubuntu 16.04: downgrade openssl to 1.0.*) It might already be enough to downgrade the development package (libssl-dev).

As a default, from cmake 3.6 onwards, the libmysqlclient (MySQL) to which the project is linked is automatically obtained from the libmysqlpp library (MySQL++).

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.

Adding the option `-DFORCE_QT5=1` to the cmake call allows to skip checking for Qt4 and force compilation with Qt5.

== Packages ==

This is a list of packages known to be required for a full installation on some Ubuntu (this list might not be correct for all systems not complete). Package names might differ. In some cases not all dependent packages (e.g. libbost-all-dev) might be required but only a subset.

It is not recommended to use snap for package installation!

* subversion
* cmake cmake-qt-gui cmake-curses-gui
* pkgconf (--recommended--)
* libz-dev [also zlib1g-dev] ("Could NOT find ZLIB")
* libncurses-dev ("Could NOT find Curses")
* libreadline-dev ("Could NOT find Readline")
* libgl-dev ("Could NOT find OpenGL")
* libv8-dev [also libnode-dev] ("Could NOT find V8")
* libccfits-dev ("Could NOT find Cfitsio")
* libssl-dev ("Could NOT find OpenSSL")
* libnova-dev ("Could NOT find Nova")
* libmysql++-dev ("Could NOT find MySQL++")
* libboost-all-dev ("Unable to find the requested Boost libraries")
* libsource-highlight-dev ("Could NOT find Highlight") <not required>

* libmysqlclient-dev

* qt4-qmake ("qmake: could not exec 'qmake': No such file or directory")
* qtbase5-dev ("...not providing FindQt5.cmake in CMAKE_MODULE_PATH...")
* libqt4-dev ("Qt is NOT installed correctly")
* libqwt-qt5-dev [with Qt5] or libqwt5-qt4-dev [with Qt4] ("Could NOT find Qwt")
* libqt4-opengl-dev ("Could NOT find Qt4 (missing: QT_QTOPENGL_INCLUDE_DIR QT_QTOPENGL_LIBRARY)")

* help2man groff
* curl
* bsd-mailx
* jsdoc-toolkit

== 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.

As a default, QT4 is searched. if Qt4 (or any of the required libraries: Core Gui OpenGL Sql Xml) is not found, cmake will try to find Qt5 and use Qt5 instead. Note that the project at the moment compiles with Qt5 but might not work! Qt5 can be forced with '''-DFORCE_QT5=1'''

== MySQL ==

Particularly systems that use MariaDB in favor of MySQL sometimes pretend to have mysql installed but compiling or linking will fail. In this case download the latest MySQL binaries from https://dev.mysql.com/downloads/mysql/ (You can use the minimal version).

After you extracted the archive, call cmake with the options
{{{
-DMYSQL_INCLUDE_DIRS=~/mysql-8.0.22-linux-glibc2.17-x86_64-minimal/include
-DMYSQL_LIBRARY_DIRS=~/mysql-8.0.22-linux-glibc2.17-x86_64-minimal/lib
}}}
where the provided path is the extacted directory.

Note that if MySQL++ is preinstalled, it might (verly likely) link to existing system libraries (e.g. MariaDB's mysqlclient library). This often leads to connection problems due to an unsupported SSL connection.

The solution is to get the MySQL++ release tarball (from https://tangentsoft.com/mysqlpp/home) and compile it yourself against your mysqclient library.

After extraction, change into their directory and execute something like
{{{
./configure --with-mysql-lib=~/mysql-8.0.22-linux-glibc2.17-x86_64-minimal/lib -with-mysql-include=~/mysql-8.0.22-linux-glibc2.17-x86_64-minimal/include
make
}}}

It can happen that make fails because mysql uses its own libssl which is not linked by the configure script. In this case do

{{{
LD_LIBRARY_PATH=~/mysql-8.0.22-linux-glibc2.17-x86_64-minimal/lib/private/:$LD_LIBRARY_PATH make
}}}

Now run your cmake (as before) with these additonal options (it is adviced to do that in an empty build directory):
{{{
-DMYSQLPP_INCLUDE_DIR=~/mysql++-3.2.5/lib
-DMYSQLPP_LIBRARY=~/mysql++-3.2.5/libmysqlpp.so
}}}