Do not include from subdirectories
[u/mrichter/AliRoot.git] / INSTALL.txt
1 ############################################################################
2 # * Copyright(c) 1998-2014, ALICE Experiment at CERN, All rights reserved. *
3 # *                                                                        *
4 # * Author: The ALICE Off-line Project.                                    *
5 # * Contributors are mentioned in the code where appropriate.              *
6 ############################################################################
7
8 ############################################################################
9 #AliRoot build and install documentation                                   #
10 ############################################################################
11
12 AliRoot, ALICE Off-line framework for simulation, reconstruction and analysis,
13 can be build and installed using CMake build system [http://www.cmake.org].
14
15 CMake is a cross-platform, open-source build system. One of the most important
16 features of CMake is the capability to build a project outside the source tree.
17 This enables the posibility to build different configurations from the same
18 source tree.
19
20 In order to build and install AliRoot 3 folders need to be defined.
21  1. Source tree - The folder which contains AliRoot sources / AliRoot Git clone
22  2. Build folder - The folder used for the actual build. This folder will contain
23  all intermediary files and generated build files
24  3. Installation folder - The folder when AliRoot libraries and binaries will be installed.
25
26 Minimum version of CMake for AliRoot is 2.8.11, but we recommend to stay up to date with
27 the latest stable version.
28
29 Important Note: All these 3 folders have to be in different locations.
30 Important Note: Developers information below
31
32
33 ############################################################################
34 #Recommended workflow - Build and install                                  #
35 ############################################################################
36
37 For an easier AliRoot build and installation we recommend the following first time 
38 AliRoot workflow. This workflow can be adapted to suit users purpose.
39
40 1. Create a work directory
41     $ mkdir $MY_WORK_DIR
42     $ cd $MY_WORK_DIR
43
44 2. Clone AliRoot repository inside your work directory.
45    If this is just a simple build and there is no need to change and submit code,
46    please use Git public interface
47     $ git clone http://git.cern.ch/pub/AliRoot AliRoot
48
49    For development purpose please use the private interface, https or kerberos
50     $ git clone https://git.cern.ch/reps/AliRoot AliRoot
51
52 3. Create the build folder. The worklow is creating a "build" folder but any name can be used.
53     $ mkdir build
54
55 4. Create the install folder. The workflow is creating an "install" folder but any name can be used.
56     $ mkdir install
57
58 We now have the complete configuration to start building AliRoot. 
59 Note that the build does not require any environment variables. The only exception is DATE environment needed 
60 for the generation of DAs (full documentation HERE -> link to daq documentation)
61
62 5. In order to configure and start the build we have to go inside the build folder
63     $ cd build
64     
65     The full build is controlled by CMake configure variables, no environment variables are needed. 
66     CMake variables are passed to the build system through -D configure paramenter. Example:
67     $ cmake -DCONFIGURE_PARAM1=ON -DCONFIGURE_PARAM2=/usr/some/location
68     
69     The full list of AliRoot configuration parameters
70     - CMAKE_INSTALL_PREFIX - mandatory standard CMake paramenter. It points to AliRoot installation directory.
71     - ROOTSYS - mandatory Root installation directory.
72     - ALIEN - AliEn2 root installation directory. This configuration parameter is mandatory if Root was build with 
73               AliEn2 support
74     - FASTJET - FastJet installation point
75     - ZEROMQ - ZeroMQ custom installation point. Not needed if ZeroMQ is installed on the system.
76     - DIMDIR - DIM installation directory
77     - ODIR - Platform for DIM, usually "linux"
78     - SHUTTLE - default value OFF. To enable Shuttle build it needs to be set to ON
79     - DATE_CONFIG - full location for date-config
80                     Do not forget to source setup.sh before running AliRoot cmake
81     - AMORE_CONFIG - full location for amore-config
82     - DA - default value OFF. To enable the build of DAs set it to ON
83     - daqDA - location of daqDA libraries
84     - MDCRPM - enable alimdc rpm creation
85     - DARPM - enable DA rpm creation 
86     
87     A base cmake configuration would contain the following configuration parameters:
88     $ cmake 
89             -DCMAKE_INSTALL_PREFIX=$MY_WORK_DIR/install
90             -DROOTSYS=$MY_ROOT_INSTALLATION_DIR
91             -DALIEN=$MY_ALIEN_INSTALLATION_DIR
92             $MY_WORK_DIR/AliRoot (or ../AliRoot)
93     
94     If all configuration parameters point correctly to the different installations than the configure step will be
95     successul and we can move to the next step, the actual build. Before building please check that all information
96     reported by the configuration step is correct or what you are expecting to be.
97     
98     If we need to change any configuration paramenter, for example the Root installation point set by ROOTSYS it
99     is mandatory to delete the $MY_WORK_DIR/build/CMakeCache.txt file and rerun the full "cmake" command
100     
101     CMake offers general configuration options that can be set using CMAKE_BUILD_TYPE.
102     Possible values are empty, Debug, Release, RelWithDebInfo and MinSizeRel. This variable is only supported for
103     make based generators. If this variable is supported, then CMake will also provide initial values for the variables
104     with the name CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]. For example, if CMAKE_BUILD_TYPE is Debug,
105     then CMAKE_C_FLAGS_DEBUG will be added to the CMAKE_C_FLAGS.
106     
107     CMAKE_BUILD_TYPE for AliRoot Grid packages is RelWithDebInfo.
108     
109 5. Build AliRoot
110     After the configuration is done the build can be started. Inside the build directory we type
111     $ make
112     If the configuration permits parallel build than we can run
113     $ make -jNR_OF_PROCESSORS
114     
115     For verbose output
116     $ export VERBOSE=1 # verbose mode enabled for futures make commands
117     $ make -j16
118     or
119     $ make -j16 VERBOSE=1 # verbose mode enabled only for this make command
120     
121     Running "make" inside the root of the build directory will trigger the build of the full AliRoot.
122     Building per folder is possible. Just switch to the folder in question and run "make". This will
123     trigger the build of the current folder plus all its dependencies.
124     
125     Example:
126     $ cd PWGJE/EMCALJetTasks
127     $ make -j16
128     
129 6. Install AliRoot
130     If the build finished successfuly than AliRoot can be properly installed inside "install" folder
131     Inside the build folder run:
132     $ make -jNR_OF_PROCESSORS install
133     
134     AliRoot installation follows "standard" installation directory structure.
135         - $MY_WORK_DIR/install/lib - libraries folder
136         - $MY_WORK_DIR/install/bin - binaries/executables folder
137         - $MY_WORK_DIR/install/include - header folder
138     
139     AliRoot specific folders are used for 
140         - $MY_WORK_DIR/install/da - DAs installation folder
141         - $MY_WORK_DIR/install/PWG** - different files related to PWG
142         
143
144 ############################################################################
145 #Recommended workflow - Running AliRoot                                    #
146 ############################################################################
147
148 Although the build and install procedure does not require any environment
149 variables, the actuall running of AliRoot needs to be aware of the different
150 locations of used libraries.
151
152 For properly running AliRoot we need to set at least 2 environment variables
153
154 1. PATH
155     Adding Root and AliRoot to PATH
156     $ export PATH=$MY_ROOT_INSTALLATION_DIR/bin:$MY_WORK_DIR/install/bin:$PATH
157     
158 2. LD_LIBRARY_PATH
159     Adding Root, AliRoot and AliEn to PATH. If FASTJET or ZEROMQ enabled than
160     we need to add them too.
161     $ export LD_LIBRARY_PATH=$MY_ALIEN_INSTALLATION_DIR/lib:$MY_ALIEN_INSTALLATION_DIR/api/lib:$LD_LIBRARY_PATH
162     $ export LD_LIBRARY_PATH=$MY_ROOT_INSTALLATION_DIR/lib:$LD_LIBRARY_PATH
163     $ export LD_LIBRARY_PATH=$MY_WORK_DIR/install/lib:$LD_LIBRARY_PATH
164     
165
166 ############################################################################
167 #Recommended workflow - Developers                                         #
168 ############################################################################
169 Dear developers,
170
171 AliRoot build and install system follows standard CMake procedures.
172 Please keep a clean, separate distinction between source tree, build and install
173 directories.
174
175 For any change related to the CMake files please follow the instructions inside the
176 CMakeLists.txt files. Targets are accessible through standard CMake functions.
177
178 Try to organize your work in separate folders.
179
180 Do not forget to install all the folders/files that are needed at run time, remeber, source
181 tree and install directory are different locations.
182
183 For any question do not hesitate to contact us:  aliroot-git-admins@cern.ch
184
185 Have a nice AliRoot development!