70e47cea5f96d9ade910000664c894797fed44b7
[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 Important Note: All these 3 folders have to be in different locations.
27 Important Note: Developers information below
28
29
30 ############################################################################
31 #Recommended workflow - Build and install                                  #
32 ############################################################################
33
34 For an easier AliRoot build and installation we recommend the following first time 
35 AliRoot workflow. This workflow can be adapted to suit users purpose.
36
37 1. Create a work directory
38     $ mkdir $MY_WORK_DIR
39     $ cd $MY_WORK_DIR
40
41 2. Clone AliRoot repository inside your work directory.
42    If this is just a simple build and there is no need to change and submit code,
43    please use Git public interface
44     $ git clone http://git.cern.ch/pub/AliRoot AliRoot
45
46    For development purpose please use the private interface, https or kerberos
47     $ git clone https://git.cern.ch/reps/AliRoot AliRoot
48
49 3. Create the build folder. The worklow is creating a "build" folder but any name can be used.
50     $ mkdir build
51
52 4. Create the install folder. The workflow is creating an "install" folder but any name can be used.
53     $ mkdir install
54
55 We now have the complete configuration to start building AliRoot. 
56 Note that the build does not require any environment variables. The only exception is DATE environment needed 
57 for the generation of DAs (full documentation HERE -> link to daq documentation)
58
59 5. In order to configure and start the build we have to go inside the build folder
60     $ cd build
61     
62     The full build is controlled by CMake configure variables, no environment variables are needed. 
63     CMake variables are passed to the build system through -D configure paramenter. Example:
64     $ cmake -DCONFIGURE_PARAM1=ON -DCONFIGURE_PARAM2=/usr/some/location
65     
66     The full list of AliRoot configuration parameters
67     - CMAKE_INSTALL_PREFIX - mandatory standard CMake paramenter. It points to AliRoot installation directory.
68     - ROOTSYS - mandatory Root installation directory.
69     - ALIEN - AliEn2 installation directory. This configuration parameter is mandatory if Root was build with 
70               AliEn2 support
71     - FASTJET - FastJet installation point
72     - ZEROMQ - ZeroMQ custom installation point. Not needed if ZeroMQ is installed on the system.
73     - DIMDIR - DIM installation directory
74     - ODIR - Platform for DIM, usually "linux"
75     - SHUTTLE - default value OFF. To enable Shuttle build it needs to be set to ON
76     - DATE_CONFIG - full location for date-config
77     - AMORE_CONFIG - full location for amore-config
78     - DA - default value OFF. To enable the build of DAs set it to ON
79     - daqDA - location of daqDA libraries
80     - MDCRPM - enable alimdc rpm creation
81     - DARPM - enable DA rpm creation 
82     
83     A base cmake configuration would contain the following configuration parameters:
84     $ cmake 
85             -DCMAKE_INSTALL_PREFIX=$MY_WORK_DIR/install
86             -DROOTSYS=$MY_ROOT_INSTALLATION_DIR
87             -DALIEN=$MY_ALIEN_INSTALLATION_DIR
88             $MY_WORK_DIR/AliRoot (or ../AliRoot)
89     
90     If all configuration parameters point correctly to the different installations than the configure step will be
91     successul and we can move to the next step, the actual build. Before building please check that all information
92     reported by the configuration step is correct or what you are expecting to be.
93     
94     If we need to change any configuration paramenter, for example the Root installation point set by ROOTSYS it
95     is mandatory to delete the $MY_WORK_DIR/build/CMakeCache.txt file and rerun the full "cmake" command
96     
97 5. Build AliRoot
98     After the configuration is done the build can be started. Inside the build directory we type
99     $ make
100     If the configuration permits parallel build than we can run
101     $ make -jNR_OF_PROCESSORS
102     
103     For verbose output
104     $ export VERBOSE=1 # verbose mode enabled for futures make commands
105     $ make -j16
106     or
107     $ make -j16 VERBOSE=1 # verbose mode enabled only for this make command
108     
109 6. Install AliRoot
110     If the build finished successfuly than AliRoot can be properly installed inside "install" folder
111     Inside the build folder run:
112     $ make -jNR_OF_PROCESSORS install
113     
114     AliRoot installation follows "standard" installation directory structure.
115         - $MY_WORK_DIR/install/lib - libraries folder
116         - $MY_WORK_DIR/install/bin - binaries/executables folder
117         - $MY_WORK_DIR/install/include - header folder
118     
119     AliRoot specific folders are used for 
120         - $MY_WORK_DIR/install/da - DAs installation folder
121         - $MY_WORK_DIR/install/PWG** - different files related to PWG
122         
123
124 ############################################################################
125 #Recommended workflow - Running AliRoot                                    #
126 ############################################################################
127
128 Although the build and install procedure does not require any environment
129 variables, the actuall running of AliRoot needs to be aware of the different
130 locations of used libraries.
131
132 For properly running AliRoot we need to set at least 2 environment variables
133
134 1. PATH
135     Adding Root and AliRoot to PATH
136     $ export PATH=$MY_ROOT_INSTALLATION_DIR/bin:$MY_WORK_DIR/install/bin:$PATH
137     
138 2. LD_LIBRARY_PATH
139     Adding Root, AliRoot and AliEn to PATH. If FASTJET or ZEROMQ enabled than
140     we need to add them too.
141     $ export LD_LIBRARY_PATH=$MY_ALIEN_INSTALLATION_DIR/lib:$MY_ALIEN_INSTALLATION_DIR/api/lib:$LD_LIBRARY_PATH
142     $ export LD_LIBRARY_PATH=$MY_ROOT_INSTALLATION_DIR/lib:$LD_LIBRARY_PATH
143     $ export LD_LIBRARY_PATH=$MY_WORK_DIR/install/lib:$LD_LIBRARY_PATH
144     
145
146 ############################################################################
147 #Recommended workflow - Developers                                         #
148 ############################################################################
149 Dear developers,
150
151 AliRoot build and install system follows standard CMake procedures.
152 Please keep a clean, separate distinction between source tree, build and install
153 directories.
154
155 For any change related to the CMake files please follow the instructions inside the
156 CMakeLists.txt files. Targets are accessible through standard CMake functions.
157
158 Try to organize your work in separate folders.
159
160 Do not forget to install all the folders/files that are needed at run time, remeber, source
161 tree and install directory are different locations.
162
163 For any question do not hesitate to contact us:  aliroot-git-admins@cern.ch
164
165 Have a nice AliRoot development!