[u/mrichter/AliRoot.git] / INSTALL.txt

############################################################################
# * Copyright(c) 1998-2014, ALICE Experiment at CERN, All rights reserved. *
# *                                                                        *
# * Author: The ALICE Off-line Project.                                    *
# * Contributors are mentioned in the code where appropriate.              *
############################################################################

############################################################################
#AliRoot build and install documentation                                   #
############################################################################

AliRoot, ALICE Off-line framework for simulation, reconstruction and analysis,
can be build and installed using CMake build system [http://www.cmake.org].

CMake is a cross-platform, open-source build system. One of the most important
features of CMake is the capability to build a project outside the source tree.
This enables the posibility to build different configurations from the same
source tree.

In order to build and install AliRoot 3 folders need to be defined.
 1. Source tree - The folder which contains AliRoot sources / AliRoot Git clone
 2. Build folder - The folder used for the actual build. This folder will contain
 all intermediary files and generated build files
 3. Installation folder - The folder when AliRoot libraries and binaries will be installed.

Minimum version of CMake for AliRoot is 2.8.11, but we recommend to stay up to date with
the latest stable version.

Important Note: All these 3 folders have to be in different locations.
Important Note: Developers information below


############################################################################
#Recommended workflow - Build and install                                  #
############################################################################

For an easier AliRoot build and installation we recommend the following first time 
AliRoot workflow. This workflow can be adapted to suit users purpose.

1. Create a work directory
    $ mkdir $MY_WORK_DIR
    $ cd $MY_WORK_DIR

2. Clone AliRoot repository inside your work directory.
   If this is just a simple build and there is no need to change and submit code,
   please use Git public interface
    $ git clone http://git.cern.ch/pub/AliRoot AliRoot

   For development purpose please use the private interface, https or kerberos
    $ git clone https://git.cern.ch/reps/AliRoot AliRoot

3. Create the build folder. The worklow is creating a "build" folder but any name can be used.
    $ mkdir build

4. Create the install folder. The workflow is creating an "install" folder but any name can be used.
    $ mkdir install

We now have the complete configuration to start building AliRoot. 
Note that the build does not require any environment variables. The only exception is DATE environment needed 
for the generation of DAs (full documentation HERE -> link to daq documentation)

5. In order to configure and start the build we have to go inside the build folder
    $ cd build
    
    The full build is controlled by CMake configure variables, no environment variables are needed. 
    CMake variables are passed to the build system through -D configure paramenter. Example:
    $ cmake -DCONFIGURE_PARAM1=ON -DCONFIGURE_PARAM2=/usr/some/location
    
    The full list of AliRoot configuration parameters
    - CMAKE_INSTALL_PREFIX - mandatory standard CMake paramenter. It points to AliRoot installation directory.
    - ROOTSYS - mandatory Root installation directory.
    - ALIEN - AliEn2 root installation directory. This configuration parameter is mandatory if Root was build with 
              AliEn2 support
    - FASTJET - FastJet installation point
    - ZEROMQ - ZeroMQ custom installation point. Not needed if ZeroMQ is installed on the system.
    - DIMDIR - DIM installation directory
    - ODIR - Platform for DIM, usually "linux"
    - SHUTTLE - default value OFF. To enable Shuttle build it needs to be set to ON
    - DATE_CONFIG - full location for date-config
    - AMORE_CONFIG - full location for amore-config
    - DA - default value OFF. To enable the build of DAs set it to ON
    - daqDA - location of daqDA libraries
    - MDCRPM - enable alimdc rpm creation
    - DARPM - enable DA rpm creation 
    
    A base cmake configuration would contain the following configuration parameters:
    $ cmake 
            -DCMAKE_INSTALL_PREFIX=$MY_WORK_DIR/install
            -DROOTSYS=$MY_ROOT_INSTALLATION_DIR
            -DALIEN=$MY_ALIEN_INSTALLATION_DIR
            $MY_WORK_DIR/AliRoot (or ../AliRoot)
    
    If all configuration parameters point correctly to the different installations than the configure step will be
    successul and we can move to the next step, the actual build. Before building please check that all information
    reported by the configuration step is correct or what you are expecting to be.
    
    If we need to change any configuration paramenter, for example the Root installation point set by ROOTSYS it
    is mandatory to delete the $MY_WORK_DIR/build/CMakeCache.txt file and rerun the full "cmake" command
    
    CMake offers general configuration options that can be set using CMAKE_BUILD_TYPE.
    Possible values are empty, Debug, Release, RelWithDebInfo and MinSizeRel. This variable is only supported for
    make based generators. If this variable is supported, then CMake will also provide initial values for the variables
    with the name CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]. For example, if CMAKE_BUILD_TYPE is Debug,
    then CMAKE_C_FLAGS_DEBUG will be added to the CMAKE_C_FLAGS.
    
    CMAKE_BUILD_TYPE for AliRoot Grid packages is RelWithDebInfo.
    
5. Build AliRoot
    After the configuration is done the build can be started. Inside the build directory we type
    $ make
    If the configuration permits parallel build than we can run
    $ make -jNR_OF_PROCESSORS
    
    For verbose output
    $ export VERBOSE=1 # verbose mode enabled for futures make commands
    $ make -j16
    or
    $ make -j16 VERBOSE=1 # verbose mode enabled only for this make command
    
    Running "make" inside the root of the build directory will trigger the build of the full AliRoot.
    Building per folder is possible. Just switch to the folder in question and run "make". This will
    trigger the build of the current folder plus all its dependencies.
    
    Example:
    $ cd PWGJE/EMCALJetTasks
    $ make -j16
    
6. Install AliRoot
    If the build finished successfuly than AliRoot can be properly installed inside "install" folder
    Inside the build folder run:
    $ make -jNR_OF_PROCESSORS install
    
    AliRoot installation follows "standard" installation directory structure.
        - $MY_WORK_DIR/install/lib - libraries folder
        - $MY_WORK_DIR/install/bin - binaries/executables folder
        - $MY_WORK_DIR/install/include - header folder
    
    AliRoot specific folders are used for 
        - $MY_WORK_DIR/install/da - DAs installation folder
        - $MY_WORK_DIR/install/PWG** - different files related to PWG
        

############################################################################
#Recommended workflow - Running AliRoot                                    #
############################################################################

Although the build and install procedure does not require any environment
variables, the actuall running of AliRoot needs to be aware of the different
locations of used libraries.

For properly running AliRoot we need to set at least 2 environment variables

1. PATH
    Adding Root and AliRoot to PATH
    $ export PATH=$MY_ROOT_INSTALLATION_DIR/bin:$MY_WORK_DIR/install/bin:$PATH
    
2. LD_LIBRARY_PATH
    Adding Root, AliRoot and AliEn to PATH. If FASTJET or ZEROMQ enabled than
    we need to add them too.
    $ export LD_LIBRARY_PATH=$MY_ALIEN_INSTALLATION_DIR/lib:$MY_ALIEN_INSTALLATION_DIR/api/lib:$LD_LIBRARY_PATH
    $ export LD_LIBRARY_PATH=$MY_ROOT_INSTALLATION_DIR/lib:$LD_LIBRARY_PATH
    $ export LD_LIBRARY_PATH=$MY_WORK_DIR/install/lib:$LD_LIBRARY_PATH
    

############################################################################
#Recommended workflow - Developers                                         #
############################################################################
Dear developers,

AliRoot build and install system follows standard CMake procedures.
Please keep a clean, separate distinction between source tree, build and install
directories.

For any change related to the CMake files please follow the instructions inside the
CMakeLists.txt files. Targets are accessible through standard CMake functions.

Try to organize your work in separate folders.

Do not forget to install all the folders/files that are needed at run time, remeber, source
tree and install directory are different locations.

For any question do not hesitate to contact us:  aliroot-git-admins@cern.ch

Have a nice AliRoot development!
Commit	Line	Data
4fb117a8	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
a60ec52a	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
4fb117a8	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.
4527d31d	72	- ALIEN - AliEn2 root installation directory. This configuration parameter is mandatory if Root was build with
4fb117a8	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
a60ec52a	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
4fb117a8	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
9973286e	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
4fb117a8	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!