How to build a release

Last update: 22 Nov 2019 [History] [Edit]

Introduction

In addition to the usual centrally produced releases and nightlies it is of course possible to build the release yourself. And for certain developments, this is probably the best way to go — you build the entire Athena code stack yourself, make your changes, compile and run your tests. Of course this requires a powerful machine (don’t try this on lxplus!) and even so will take several hours the first time (subsequent rebuilds should usually be much faster). It will also require a significant amount of space - how much exactly will depend on what you do, but for e.g. a full rebuild of Gaudi, atlasexternals and Athena, you should probably allow about 100 GB.

To start with, please make sure you have read the guide about the releases and the nightlies, so you understand a bit how it all fits together.

Be aware that we depend on the LCG releases, so we’re assuming that you have cvmfs installed. If not, it’s still possible to install from e.g. RPMs but this is not yet covered in these instructions.

For ATLAS people, you can also check the instructions on the reconstruction software twiki.

Build externals and Athena together

Setup and build

For the nightlies, the central build machines do the following:

asetup none,gcc8,cmakesetup
./athena/Projects/Athena/build_externals.sh -c
./athena/Projects/Athena/build.sh -acmi

i.e. they use asetup to get a compiler, then call a script to checkout and build the externals, and finally another script to checkout, build and install Athena.

You can have a look at the general build scripts under Build/AtlasBuildScripts, and the Project specific scripts are found in the Project directory. For example, the Athena scripts are under Projects/Athena. The main scripts that matter here are build_externals.sh (which checks out and builds the atlasexternals branch which corresponds to the Athena release, as defined in Projects/Athena/externals.txt), and build.sh which checks out and builds athena.

So, to build externals and Athena you can go to a fresh directory and do the following:

setupATLAS
lsetup git python
git clone https://:@gitlab.cern.ch:8443/atlas/athena.git
asetup none,gcc8,cmakesetup
./athena/Projects/Athena/build_externals.sh -c >& external.log &
./athena/Projects/Athena/build.sh >& build.log &

Alert For older gcc62-based releases, you should instead do: asetup none,gcc62,cmakesetup --gccversion=6.2.0binutils

Alert In some cases, you may need to provide a specific cmake version: asetup none,gcc83,cmakesetup --cmakeversion=3.14.7

You can choose which parts of the build you want to do (cmake, build, install) by adding the parameters -c, -m, and -i to build.sh. By default all parts are done.

The parameter ‘-c’ to build_externals.sh tells it not to bother making RPMs. So remove it if you really want to be able to do a rpm-based installation later - for most local use-cases it isn’t necessary.

Adding ‘-N’ to build.sh instructs it to use ninja instead of make - this won’t make a difference if you’re only building once, but if you plan to rebuild many times in the build directory then it’s far faster. For this to work you need to make sure a recent version of ninja is in your path, e.g. by doing:

export PATH=/cvmfs/sft.cern.ch/lcg/contrib/ninja/1.7.2.gcc0ea.kitware.dyndep-1/x86_64-slc6/:$PATH

And of course you can use ‘-h’ on both scripts to find all available options.

Normally you won’t want to compile exactly what was already in a nightly, but rather a version with modifications, so have a look at building externals, building athena and building Gaudi below.

Final configuration

In order to actually use Athena, you might need EOS. If so, this is how you set that up:

export EOS_MGM_URL=root://eosatlas.cern.ch
/usr/bin/eos -b fuse mount eos

Depending on your EOS installation, after kinit and mounting EOS, you may need to also do

eosfusebind -g

Running Athena

In order to use the above, in a fresh terminal you would do:

setupATLAS
asetup Athena,22.0.1 --releasepath=YOURBUILDAREA --siteroot=/cvmfs/atlas-nightlies.cern.ch/repo/sw/master

Some people have reported run-time problems accessing some needed files. If you encounter this, the following resolves the issues that have been reported so far:

export DATAPATH=$DATAPATH:/cvmfs/atlas-nightlies.cern.ch/repo/sw/master/atlas/offline/ReleaseData/v20/

Running unit tests

To run the unit tests:

setupATLAS
asetup AthenaExternals --releasepath=YOURBUILDAREA --cernsiteroot=/cvmfs/atlas-nightlies.cern.ch/repo/sw/master
cd YOURBUILDAREA
source $CMTCONFIG/setup.sh
make test

Building the externals alone

If you want to test a new version of an external, it is often necessary to fork and compile your own version of atlasexternals.

Instructions on how to compile externals without scripts are kept up-to-date on the atlasexternals repository, but the following should work:

asetup none,gcc8,cmakesetup
mkdir build
cd build/
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCTEST_USE_LAUNCHERS=TRUE ../atlasexternals/Projects/AthenaExternals/
make install DESTDIR=/some/location

Once you are happy with your new version, you can use the standard build scripts but setting a couple of environment variables to specify your own fork and branch:

export AtlasExternals_URL = URLTOMYREPO
export AtlasExternals_REF = MYBRANCH
build_externals.sh -b MYBUILDAREA

Once you have the externals, you can either run build.sh as described above, or just use ninja to rebuild a few packages to test (see the git workflow tutorial for details on these ‘sparse builds’):

mkdir build/build/Athena/
cd build/build/Athena/
asetup none,gcc8,cmakesetup
source ../../../athena/Projects/Athena/build_env.sh
export PATH=/cvmfs/sft.cern.ch/lcg/contrib/ninja/1.7.2.gcc0ea.kitware.dyndep-1/x86_64-slc6/:$PATH
cmake -G Ninja -DCTEST_USE_LAUNCHERS=TRUE ../../../athena/Projects/Athena/ 2>&1 | tee cmake_config.log

Now you can build the packages you need with ninja Package_<package name> e.g. ninja Package_TrkTrack

Building Athena alone

If you want to build your local version of Athena, you can setup the externals you want to use and then build as before (using ninja, so don’t forget to add it to the PATH as explained above):

asetup master,AthenaExternals,latest
mkdir -p build/{install,src}
athena/Projects/Athena/build.sh -acmN 

We skipped the installation step here, since it’s not strictly necessary. If you do this, you can then setup your local compiled version by simply sourcing the setup script e.g.

asetup master,AthenaExternals,latest
source build/build/Athena/x86_64-centos7-gcc8-opt/setup.sh

You can also build it without using the scripts e.g.

asetup none,gcc8,cmakesetup
source ./install/AthenaExternals/22.0.1/InstallArea/x86_64-centos7-gcc8-opt/setup.sh
export GAUDI_ROOT=$PWD/install/GAUDI/22.0.1/InstallArea/x86_64-centos7-gcc8-opt
source ./athena/Build/AtlasBuildScripts/TDAQ_RELEASE_BASE.sh
cd build_athena/
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCTEST_USE_LAUNCHERS=TRUE ../athena/Projects/Athena/
make install DESTDIR=../install/Athena/22.0.1

(if you look at the scripts, you can see that this is more or less what they do anyway)

Building Gaudi

And of course it’s possible to build everything, including your own fork of Gaudi.

asetup master,AthenaExternals,latest
mkdir -p ${BUILDDIR}/{src,install}
athena/Build/AtlasBuildScripts/checkout_Gaudi.sh -t instrument_algtool_hack -e ssh://git@gitlab.cern.ch:7999/emoyse/Gaudi.git -s build/src/GAUDI 2>&1 | tee build/src/checkout.GAUDI.log
athena/Build/AtlasBuildScripts/build_Gaudi.sh \
    -s ${BUILDDIR}/src/GAUDI \
     -b ${BUILDDIR}/build/GAUDI \
     -i ${BUILDDIR}/install/GAUDI/22.0.1 \
 -e /cvmfs/atlas-nightlies.cern.ch/repo/sw/master/2018-10-22T2307/AthenaExternals/22.0.1/InstallArea/x86_64-centos7-gcc8-opt \
-p AthenaExternals -f x86_64-centos7-gcc8-opt -t "RelWithDebInfo"
./athena/Projects/Athena/build.sh -acm

And if you cloned Gaudi manually, you could compile it with e.g.

asetup none,gcc8,cmakesetup
source ./install/AthenaExternals/22.0.1/InstallArea/x86_64-centos7-gcc8-opt/setup.sh 
cd build_gaudi/
cmake -DGAUDI_ATLAS=TRUE -DGAUDI_ATLAS_BASE_PROJECT=AthenaExternals -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/InstallArea/x86_64-centos7-gcc8-opt -DCTEST_USE_LAUNCHERS=TRUE ../Gaudi/
make install DESTDIR=../install/GAUDI/22.0.1