[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
		    Do not forget to source setup.sh before running AliRoot cmake
    - 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
8d00e8c1	80	Do not forget to source setup.sh before running AliRoot cmake
4fb117a8	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
a60ec52a	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
4fb117a8	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
9973286e	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
4fb117a8	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!