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