Commit 6dd9cab8 authored by Simon Spannagel's avatar Simon Spannagel
Browse files

Update usermanual/chapters/installation.tex from CLICdp-Note-2019-006

parent dce324c1
......@@ -12,22 +12,22 @@ This chapter contains details on the standard installation process and informati
Furthermore, the continuous integration of the project ensures correct building and functioning of the software framework on CentOS\,7 (with GCC and LLVM), SLC\,6 (with GCC and LLVM) and Mac OS Mojave (OS X 10.14, with AppleClang).
\section{CMVFS}
\label{sec:cvmfs}
\label{sec:cvmfs_install}
The software is automatically deployed to CERN's VM file system (CVMFS)~\cite{cvmfs} for every new tag.
In addition, the \parameter{master} branch is built and deployed every night.
New versions are published to the folder \dir{/cvmfs/clicdp.cern.ch/software/corryvreckan/} where a new folder is created for every new tag, while updates via the \parameter{master} branch are always stored in the \dir{latest} folder.
The deployed version currently comprises all modules which are active by default and do not require additional dependencies.
A \file{setup.sh} is placed in the root folder of the respective release, which allows to set up all runtime dependencies necessary for executing this version.
The deployed version currently comprises of all modules that are active by default and do not require additional dependencies.
A \file{setup.sh} is placed in the root folder of the respective release, which allows all runtime dependencies necessary for executing this version to be set up.
Versions for both SLC\,6 and CentOS\,7 are provided.
\section{Docker}
\label{sec:docker}
Docker images are provided for the framework to allow anyone to run analyses without the need of installing \corry on their system.
The only required program is the Docker executable, all other dependencies are provided within the Docker images.
Docker images are provided for the framework allowing anyone to run analyses without needing to install \corry on their system.
The only required program is the Docker executable as all other dependencies are provided within the Docker images.
In order to exchange configuration files and output data between the host system and the Docker container, a folder from the host system should be mounted to the container's data path \dir{/data}, which also acts as the Docker \parameter{WORKDIR} location.
The following command creates a container from the latest Docker image in the project registry and start an interactive shell session with the \command{corry} executable already in the \texttt{\$PATH}.
The following command creates a container from the latest Docker image in the project registry and starts an interactive shell session with the \command{corry} executable already in the \texttt{\$PATH}.
Here, the current host system path is mounted to the \dir{/data} directory of the container.
\begin{verbatim}
......@@ -64,13 +64,13 @@ The following paragraphs describe how to compile the \corry framework and its in
\subsection{Prerequisites}
\label{sec:prerequisites}
The core framework is compiled separately from the individual modules and \corry has therefore only one required dependency: ROOT 6 (versions below 6 are not supported)~\cite{root}.
The core framework is compiled separately from the individual modules, therefore \corry has only one required dependency: ROOT 6 (versions below 6 are not supported)~\cite{root}.
Please refer to~\cite{rootinstallation} for instructions on how to install ROOT.
ROOT has several components of which the GenVector package is required to run \corry, a package included in the default build.
ROOT has several components and to run \corry the GenVector package is required, a package that is included in the default build.
\subsection{Downloading the source code}
The latest version of \corry can be downloaded from the CERN Gitlab repository~\cite{corry-repo}.
For production environments it is recommended to only download and use tagged software versions, as many of the available git branches are considered development versions and might exhibit unexpected behavior.
For production environments, it is recommended to only download and use tagged software versions as many of the available git branches are considered development versions and might exhibit unexpected behavior.
For developers, it is recommended to always use the latest available version from the git \texttt{master} branch.
The software repository can be cloned as follows:
......@@ -82,10 +82,10 @@ $ cd corryvreckan
\subsection{Configuration via CMake}
\label{sec:cmake_config}
\corry uses the CMake build system to configure, build and install the core framework as well as all modules.
\corry uses the CMake build system to configure, build, and install the core framework as well as all modules.
An out-of-source build is recommended: this means CMake should not be directly executed in the source folder.
Instead, a \textit{build} folder should be created, from which CMake should be run.
For a standard build without any additional flags this implies executing:
Instead, a \dir{build} folder should be created from which CMake should be run.
For a standard build without any additional flags this entails executing:
\begin{verbatim}
$ mkdir build
......@@ -97,32 +97,33 @@ CMake can be run with several extra arguments to change the type of installation
These options can be set with -D\textit{option}.
The following options are noteworthy:
\begin{itemize}
\item \parameter{CMAKE_INSTALL_PREFIX}: The directory to use as a prefix for installing the binaries, libraries and data.
Defaults to the source directory (where the folders \textit{bin/} and \textit{lib/} are added).
\item \parameter{CMAKE_BUILD_TYPE}: Type of build to install, defaults to \parameter{RelWithDebInfo} (compiles with optimizations and debug symbols).
\item \parameter{CMAKE_INSTALL_PREFIX}: The directory to use as a prefix for installing the binaries, libraries, and data.
Defaults to the source directory (where the folders \dir{bin/} and \dir{lib/} are added).
\item \parameter{CMAKE_BUILD_TYPE}: The type of build to install, which defaults to \parameter{RelWithDebInfo} (compiles with optimizations and debug symbols).
Other possible options are \texttt{Debug} (for compiling with no optimizations, but with debug symbols and extended tracing using the Clang Address Sanitizer library) and \texttt{Release} (for compiling with full optimizations and no debug symbols).
\item \textbf{\texttt{BUILD\_\textit{ModuleName}}}: If the specific module \parameter{ModuleName} should be installed or not.
Defaults to \texttt{ON} for most modules, however some modules with additional dependencies such as EUDAQ or EUDAQ2~\cite{eudaq,eudaq2} are disabled by default.
This set of parameters allows to configure the build for minimal requirements as detailed in Section~\ref{sec:prerequisites}.
\item \parameter{BUILD_ALL_MODULES}: Build all included modules, defaulting to \parameter{OFF}.
\item \parameter{BUILD_ALL_MODULES}: Build all included modules, defaulting to \texttt{OFF}.
This overwrites any selection using the parameters described above.
\end{itemize}
An example of a custom debug build, without the \parameter{EventLoaderCLICpix2} module and with installation to a custom directory is shown below:
An example of a custom debug build, including the \module{EventLoaderEUDAQ2} module and with installation to a custom directory, is shown below:
\begin{verbatim}
$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=../install/ \
-DCMAKE_BUILD_TYPE=DEBUG \
-DBUILD_EventLoaderCLICpix2=OFF ..
-DBUILD_EventLoaderEUDAQ2=OFF ..
\end{verbatim}
It should be noted that the \module{EventLoaderEUDAQ2} module requires additional dependencies and is therefore not built by default.
\subsection{Compilation and installation}
Compiling the framework is now a single command in the build folder created earlier (replacing \textit{\textless number\_of\_cores\textgreater} with the number of cores to use for compilation):
Compiling the framework is now a single command in the build folder created earlier, where \parameter{<number_of_cores>} is replaced with the number of cores to use for compilation:
\begin{verbatim}
$ make -j<number_of_cores>
\end{verbatim}
The compiled (non-installed) version of the executable can be found at \textit{src/exec/corry} in the \dir{build} folder.
The compiled (non-installed) version of the executable can be found at \file{src/exec/corry} in the \dir{build} folder.
Running \corry directly without installing can be useful for developers.
It is not recommended for normal users, because the correct library and model paths are only fully configured during installation.
......@@ -131,4 +132,4 @@ To install the library to the selected installation location (defaulting to the
$ make install
\end{verbatim}
The binary is now available as \textit{bin/corry} in the installation directory.
The binary is now available as \file{bin/corry} in the installation directory.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment