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     - AMORE_CONFIG - full location for amore-config
  81     - DA - default value OFF. To enable the build of DAs set it to ON
  82     - daqDA - location of daqDA libraries
  83     - MDCRPM - enable alimdc rpm creation
  84     - DARPM - enable DA rpm creation
  85
  86     A base cmake configuration would contain the following configuration parameters:
  87     $ cmake
  88             -DCMAKE_INSTALL_PREFIX=$MY_WORK_DIR/install
  89             -DROOTSYS=$MY_ROOT_INSTALLATION_DIR
  90             -DALIEN=$MY_ALIEN_INSTALLATION_DIR
  91             $MY_WORK_DIR/AliRoot (or ../AliRoot)
  92
  93     If all configuration parameters point correctly to the different installations than the configure step will be
  94     successul and we can move to the next step, the actual build. Before building please check that all information
  95     reported by the configuration step is correct or what you are expecting to be.
  96
  97     If we need to change any configuration paramenter, for example the Root installation point set by ROOTSYS it
  98     is mandatory to delete the $MY_WORK_DIR/build/CMakeCache.txt file and rerun the full "cmake" command
  99
 100     CMake offers general configuration options that can be set using CMAKE_BUILD_TYPE.
 101     Possible values are empty, Debug, Release, RelWithDebInfo and MinSizeRel. This variable is only supported for
 102     make based generators. If this variable is supported, then CMake will also provide initial values for the variables
 103     with the name CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]. For example, if CMAKE_BUILD_TYPE is Debug,
 104     then CMAKE_C_FLAGS_DEBUG will be added to the CMAKE_C_FLAGS.
 105
 106     CMAKE_BUILD_TYPE for AliRoot Grid packages is RelWithDebInfo.
 107
 108 5. Build AliRoot
 109     After the configuration is done the build can be started. Inside the build directory we type
 110     $ make
 111     If the configuration permits parallel build than we can run
 112     $ make -jNR_OF_PROCESSORS
 113
 114     For verbose output
 115     $ export VERBOSE=1 # verbose mode enabled for futures make commands
 116     $ make -j16
 117     or
 118     $ make -j16 VERBOSE=1 # verbose mode enabled only for this make command
 119
 120     Running "make" inside the root of the build directory will trigger the build of the full AliRoot.
 121     Building per folder is possible. Just switch to the folder in question and run "make". This will
 122     trigger the build of the current folder plus all its dependencies.
 123
 124     Example:
 125     $ cd PWGJE/EMCALJetTasks
 126     $ make -j16
 127
 128 6. Install AliRoot
 129     If the build finished successfuly than AliRoot can be properly installed inside "install" folder
 130     Inside the build folder run:
 131     $ make -jNR_OF_PROCESSORS install
 132
 133     AliRoot installation follows "standard" installation directory structure.
 134         - $MY_WORK_DIR/install/lib - libraries folder
 135         - $MY_WORK_DIR/install/bin - binaries/executables folder
 136         - $MY_WORK_DIR/install/include - header folder
 137
 138     AliRoot specific folders are used for
 139         - $MY_WORK_DIR/install/da - DAs installation folder
 140         - $MY_WORK_DIR/install/PWG** - different files related to PWG
 141
 142
 143 ############################################################################
 144 #Recommended workflow - Running AliRoot                                    #
 145 ############################################################################
 146
 147 Although the build and install procedure does not require any environment
 148 variables, the actuall running of AliRoot needs to be aware of the different
 149 locations of used libraries.
 150
 151 For properly running AliRoot we need to set at least 2 environment variables
 152
 153 1. PATH
 154     Adding Root and AliRoot to PATH
 155     $ export PATH=$MY_ROOT_INSTALLATION_DIR/bin:$MY_WORK_DIR/install/bin:$PATH
 156
 157 2. LD_LIBRARY_PATH
 158     Adding Root, AliRoot and AliEn to PATH. If FASTJET or ZEROMQ enabled than
 159     we need to add them too.
 160     $ export LD_LIBRARY_PATH=$MY_ALIEN_INSTALLATION_DIR/lib:$MY_ALIEN_INSTALLATION_DIR/api/lib:$LD_LIBRARY_PATH
 161     $ export LD_LIBRARY_PATH=$MY_ROOT_INSTALLATION_DIR/lib:$LD_LIBRARY_PATH
 162     $ export LD_LIBRARY_PATH=$MY_WORK_DIR/install/lib:$LD_LIBRARY_PATH
 163
 164
 165 ############################################################################
 166 #Recommended workflow - Developers                                         #
 167 ############################################################################
 168 Dear developers,
 169
 170 AliRoot build and install system follows standard CMake procedures.
 171 Please keep a clean, separate distinction between source tree, build and install
 172 directories.
 173
 174 For any change related to the CMake files please follow the instructions inside the
 175 CMakeLists.txt files. Targets are accessible through standard CMake functions.
 176
 177 Try to organize your work in separate folders.
 178
 179 Do not forget to install all the folders/files that are needed at run time, remeber, source
 180 tree and install directory are different locations.
 181
 182 For any question do not hesitate to contact us:  aliroot-git-admins@cern.ch
 183
 184 Have a nice AliRoot development!