installation.tex 8.42 KB
 Simon Spannagel committed Jun 25, 2018 1 2 3 \chapter{Installation} \label{ch:installation}  Simon Spannagel committed Nov 13, 2018 4 5 6 7 8 9 10 11 12 13 This section aims to provide details and instructions on how to build and install \corry. An overview of possible build configurations is given. After installing and loading the required dependencies, there are various options to customize the installation of \corry. This chapter contains details on the standard installation process and information about custom build configurations. \section{Supported Operating Systems} \label{sec:os} \corry is designed to run without issues on either a recent Linux distribution or Mac OS\,X. 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 Sierra (OS X 10.12, with AppleClang).  Simon Spannagel committed Jun 25, 2018 14 \section{CMVFS}  Simon Spannagel committed Nov 13, 2018 15 16 17 18 \label{sec:cvmfs} 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.  Simon Spannagel committed Jun 25, 2018 19   Simon Spannagel committed Nov 13, 2018 20 21 22 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. Versions both for SLC\,6 and CentOS\,7 are provided.  Simon Spannagel committed Jun 25, 2018 23 24  \section{Docker}  Simon Spannagel committed Nov 13, 2018 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 \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. 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}. Here, the current host system path is mounted to the \dir{/data} directory of the container. \begin{verbatim}$ docker run --interactive --tty \ --volume "$(pwd)":/data \ --name=corryvreckan \ gitlab-registry.cern.ch/corryvreckan/corryvreckan \ bash \end{verbatim} Alternatively it is also possible to directly start the simulation instead of an interactive shell, e.g. using the following command: \begin{verbatim}$ docker run --tty --rm \ --volume "$(pwd)":/data \ --name=corryvreckan \ gitlab-registry.cern.ch/corryvreckan/corryvreckan \ "corry -c my_analysis.conf" \end{verbatim} where an analysis described in the configuration \file{my_analysis.conf} is directly executed and the container terminated and deleted after completing the data processing. This closely resembles the behavior of running \corry natively on the host system. Of course, any additional command line arguments known to the \command{corry} executable described in Section~\ref{sec:executable} can be appended. For tagged versions, the tag name should be appended to the image name, e.g.\ \parameter{gitlab-registry.cern.ch/corryvreckan/corryvreckan:v1.0}, and a full list of available Docker containers is provided via the project's container registry~\cite{corry-container-registry}.  Simon Spannagel committed Jun 25, 2018 54 55 56  \section{Binaries}  Simon Spannagel committed Nov 13, 2018 57 58 59 60 61 Binary release tarballs are deployed to EOS to serve as downloads from the web to the directory \dir{/eos/project/c/corryvreckan/www/releases}. New tarballs are produced for every tag as well as for nightly builds of the \parameter{master} branch, which are deployed with the name \file{allpix-squared-latest--opt.tar.gz}. \section{Compilation from Source}  Simon Spannagel committed Nov 13, 2018 62 63 64 65 66 67 68 69 70  The following paragraphs describe how to compile the \corry framework and its individual analysis and reconstruction modules from the source code. \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}. 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.  Simon Spannagel committed Nov 13, 2018 71 \subsection{Downloading the source code}  Simon Spannagel committed Nov 13, 2018 72 73 74 75 76 77 78 79 80 81 82 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 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: \begin{verbatim}$ git clone https://gitlab.cern.ch/corryvreckan/corryvreckan $cd corryvreckan \end{verbatim}  Simon Spannagel committed Nov 13, 2018 83 \subsection{Configuration via CMake}  Simon Spannagel committed Nov 13, 2018 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 \label{sec:cmake_config} \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: \begin{verbatim}$ mkdir build $cd build$ cmake .. \end{verbatim} 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). 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~\cite{eudaq} 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}. 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: \begin{verbatim} $mkdir build$ cd build $cmake -DCMAKE_INSTALL_PREFIX=../install/ \ -DCMAKE_BUILD_TYPE=DEBUG \ -DBUILD_EventLoaderCLICpix2=OFF .. \end{verbatim}  Simon Spannagel committed Nov 13, 2018 120 \subsection{Compilation and installation}  121 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):  Simon Spannagel committed Nov 13, 2018 122 123 124 125 126 127 128 129 130 131 132 133 134 \begin{verbatim}$ make -j \end{verbatim} The compiled (non-installed) version of the executable can be found at \textit{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. To install the library to the selected installation location (defaulting to the source directory of the repository) requires the following command: \begin{verbatim} \$ make install \end{verbatim} The binary is now available as \textit{bin/corry} in the installation directory.