| The Gaudi Framework v30r0 (c919700c)

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

GaudiRelease/doc/doxygen/cmake_doc/README.md
Go to the documentation of this file.
1 How to build and use the Gaudi with CMake {#quick-guide-cmake}
2 =========================================
3
4 Requirements
5 ------------
6 The CMake configuration of Gaudi is based on the version 2.8.5 or later of
7 CMake. On lxplus (SLC6 and CentOS7) you need to call something like:
8
9 $ export PATH=/cvmfs/sft.cern.ch/lcg/contrib/CMake/3.7.0/Linux-x86_64/bin:$PATH
10
11 You also need to ensure that the compiler you want to use is configured and
12 available on the PATH, for example with something like:
13
14 $ . /cvmfs/sft.cern.ch/lcg/contrib/gcc/7.1.0/x86_64-centos7/setup.sh
15
16 In addition you will need at least python 2.7.
17
18 **NOTE**: If you use the LHCb environment (as of LbScripts v7r7), you do not
19 need to prepare the environment for the compiler.
20
21 Quick Start
22 -----------
23 To quickly get started, you can use the `Makefile`, which
24 will take care of the main details (except the value of `BINARY_TAG`, or
25 `CMTCONFIG` for backward compatibility):
26
27 $ make -j 8
28 $ make test
29
30 The main targets are:
31
32 * `configure`
33
34 just run CMake to generate the build directory (or reconfigure)
35
36 * `all` (default)
37
38 build everything (implies `configure`)
39
40 * `test`
41
42 run the tests (and generate HTML reports), note that it does not
43 imply the build and does not require installation
44
45 * `install`
46
47 populate the `InstallArea` directory, *required for runtime/deployment*
48
49 Some extra targets are provided for special cases:
50
51 * `unsafe-install`
52
53 allow partial installation after a failed build (for builds in a
54 continuous integration system)
55
56 * `post-install`
57
58 optional operations on the content of `InstallArea` (like compressing
59 the `python` directory)
60
61 * `apply-formatting`
62
63 apply automatic code formatting to C++ and python sources (using `clang-format` and
64 `autopep8` if available)
65
66
67
68 Build
69 -----
70 I suggest to use the off-source build, which means that the files required by
71 the build and the build products are created in a different directory than the
72 source one.
73 In this example I'll use `Gaudi-build`, created at the same level as the
74 directory containing the sources (`Gaudi`).
75
76 To prepare the build directory, you have to:
77
78 $ src=$PWD/Gaudi
79 $ mkdir Gaudi-build
80 $ cd Gaudi-build
81 $ export BINARY_TAG=$LCGPLAT
82 $ export CMAKE_PREFIX_PATH=/cvmfs/sft.cern.ch/lcg/releases
83 $ cmake -DCMAKE_TOOLCHAIN_FILE=$src/toolchain.cmake \
84 -G "Eclipse CDT4 - Unix Makefiles" $src
85
86 `$LCGPLAT` is set if you used the LCG gcc setup script above, otherwise set it manually.
87 This will create the required Unix makefiles and the Eclipse project
88 configuration to build Gaudi.
89
90 Other options are available on the command line when you prepare the build
91 directory the first time or afterwards via the CMake configuration tool
92 `ccmake`, for example `CMAKE_USE_DISTCC` or `CMAKE_USE_CCACHE`.
93
94 Now you can build the project with a simple (from `Gaudi-build`)::
95
96 $ make
97
98 or from Eclipse after you imported the project.
99
100 The tests can be run via the command `ctest` or with `make test`.
101
102 Note that the build via `Makefile` uses the build directory
103 `build.${BINARY_TAG}` under the source directory.
104
105
106 Install
107 -------
108 The build of the project obtained with CMake cannot be used directly by other
109 projects: it needs to be installed in the source directory (for backward
110 compatibility with CMT) with the command:
111
112 $ make install
113
114 It must be noted that the special file ``python.zip`` is not automatically
115 generated, so, if you want it, you have to call, after the installation:
116
117 $ make post-install
118
119
120 Run
121 ---
122 The runtime environment for the installed binaries is described by the XML file
123 `Gaudi.xenv` located in the directory `InstallArea/$BINARY_TAG`, in
124 the format understood by the Python script `xenv` available in the `cmake`
125 directory in the source tree (it is also installed).
126
127 The behavior of `xenv` is quite similar to that of the standard Unix
128 command `env` (see `man env`), with the addition of few functionalities
129 (append, prepend, XML).
130
131 For example, you can call `gaudirun.py` like this (with the variable `src`
132 defined above):
133
134 $ $src/cmake/xenv --xml $src/InstallArea/$BINARY_TAG/Gaudi.xenv \
135 gaudirun.py --help
136
137 or, to have a sub-shell with the right environment:
138
139 $ $src/cmake/xenv --xml $src/InstallArea/$BINARY_TAG/Gaudi.xenv bash
140
141 (note that you may need to add the `--norc` option to `bash`).
142
143
144 Run from the build directory
145 ----------------------------
146 For testing and debugging (as already mentioned) there is no need to install.
147
148 To run an application using the build directory, you can use the script
149 `xenv` with the XML file `Gaudi-build.xenv` located in the `conf` subdirectory
150 of the build directory, or the convenience script `run` (in the build directory),
151 for example like this:
152
153 $ cd Gaudi-build
154 $ ./run gaudirun.py --help
155 $ ./run bash
156
157 When using `Makefile` the above lines should be changed in
158
159 $ build.$BINARY_TAG/run gaudirun.py --help
160 $ build.$BINARY_TAG/run bash
161
162
163 Resources
164 -------------
165 * [CMake documentation](http://www.cmake.org/cmake/help/documentation.html)
166 * `FindTBB.cmake` was taken from <https://bitbucket.org/sergiu/tbb-cmake>