atlas.bits

Recipes and defaults for building ATLAS Athena with bits. The repository is a thin layer. It builds AthenaExternals (atlasexternals) and Athena by running ATLAS's own Projects/Athena/build_externals.sh and build.sh without changes. The only difference from a standard ATLAS build is where the LCG base comes from: it is built by bits from the lcg.bits recipe pool instead of being taken from /cvmfs/sft.cern.ch/lcg/releases. defaults-atlas.sh requires stacks.bits, which provides the shared release base and the compiler and build-type profiles, and stacks.bits in turn requires lcg.bits. bits fetches both automatically through the bits-providers registry.

lcg.bits (LCG_110)  -->  lcg-view  -->  atlasexternals  -->  Athena
  recipe pool           LCG manifest    build_externals.sh    build.sh

Prerequisites

• bits, and one of two setups (see Installation & Prerequisites in the bits user guide; bits doctor checks the machine):
  • docker or rootless podman, to build in the platform's builder image with --docker (recommended, and the only way to reuse what the ATLAS CI built);
  • or the system packages listed in Building natively, to build with this machine's compilers and libraries.
• A platform the ATLAS CI builds, so that its binaries are reused: x86_64-el9 (ATLAS targets x86_64-el9-gcc15-opt), x86_64-el8, x86_64-el10 and aarch64-el9; Ubuntu is not a supported Athena platform. What is published on CVMFS today is x86_64-el9 (gcc15 opt and dbg, gcc14 opt). Pass the platform as --architecture; on one of them, bits architecture prints it. See Finding a platform with pre-built binaries.
• Network access during the build. atlasexternals and Athena set sandbox_network: "off" because build_externals.sh clones atlasexternals and downloads the Gaudi, ACTS, GeoModel and VecMem sources.
• Read access to https://gitlab.cern.ch/atlas/athena, which both recipes check out.

Using the published Athena

Athena is published on CVMFS under /cvmfs/bits.cern.ch/atlas, now 25.0.71 for x86_64-el9-gcc15-opt, x86_64-el9-gcc15-dbg and x86_64-el9-gcc14-opt, with its AthenaExternals and the LCG base it was built with (LCG 110, LCG_110_ATLAS_5). To run it, nothing has to be built; setupATLAS.sh from a checkout of this repository sets up the LCG base, AthenaExternals and Athena from CVMFS:

git clone https://github.com/bitsorg/atlas.bits && cd atlas.bits
bits q -a x86_64-el9-gcc15-opt Athena               # the published versions
BITS_ARCH=x86_64-el9-gcc15-opt BITS_ATHENA=25.0.71 source setupATLAS.sh
athena.py AthExHelloWorld/HelloWorldConfig.py       # the example this Athena builds

Run it in a plain shell (bash or zsh). It prints the LCG_RELEASE_BASE it uses and each setup.sh it sources, then, when /cvmfs/atlas.cern.ch is mounted, runs the stock ATLASLocalRootBase setup (asetup and lsetup are then available, but not needed for this Athena); without it, it says so and goes on. Without BITS_ATHENA it takes the latest Athena built in sw/ beside it, else the newest published; BITS_ARCH picks the platform (default x86_64-el9-gcc15-opt).

In the checkout, bits enter -a x86_64-el9-gcc15-opt Athena/25.0.71-2 instead opens a sub-shell from the release view /cvmfs/bits.cern.ch/atlas/views/LCG_110/<platform>: the LCG base, AthenaExternals and Athena on the paths, but not Athena's own run-time settings (JOBOPTSEARCHPATH, DATAPATH, ...). For athena.py, use setupATLAS.sh.

Getting started

bits init atlas.bits && cd atlas.bits     # or: git clone https://github.com/bitsorg/atlas.bits
bits use --architecture x86_64-el9 --defaults atlas::gcc15::opt
bits use build --docker --set release=LCG_110 \
                        --set athena_release=release/25.0.75
bits build --dry-run Athena
bits build Athena                         # LCG base, AthenaExternals and Athena
bits enter Athena/latest                  # the paths; to run athena.py, setupATLAS.sh (below)

The bits use profile stores the settings in this checkout: the platform and the defaults for every command, so bits q and bits enter find this build among others in the work directory, the rest for bits build; options given on the command line still win. The build architecture is x86_64-el9-gcc15-opt. --docker builds in the platform's builder image; on a machine of the same platform bits enter then works here. Without it, bits builds with this machine's compilers and system packages, and reuses nothing the CI built. bits build atlasexternals builds only the LCG base and AthenaExternals. Check the machine with bits doctor. To build elsewhere, export BITS_WORK_DIR=/path/to/sw. The profile format is described in the bits user guide.

To use an ATLAS-style setup instead of bits enter, source setupATLAS.sh from this repository. It takes Athena, then the atlasexternals and lcg-view that Athena was built with, from the work directory (BITS_SW, default sw/ beside the script) or, when not built there, from CVMFS under the cvmfs.yaml prefix (BITS_CVMFS_PREFIX overrides it; empty turns CVMFS off). It points LCG_RELEASE_BASE at lcg-view and sources the setup.sh of atlasexternals and Athena, then the stock ALRB setup. BITS_ATHENA=25.0.75 picks an Athena version (default: the latest built, else the newest published), and stops when the version given is not found; BITS_ARCH defaults to x86_64-el9-gcc15-opt. An LCG_RELEASE_BASE set before is kept, and said so.

After a build, run the example the same way, from the checkout:

source setupATLAS.sh                                # the latest Athena built in sw/
athena.py AthExHelloWorld/HelloWorldConfig.py

With another work directory (BITS_WORK_DIR), set BITS_SW to it first, or setupATLAS.sh takes the Athena published on CVMFS.

Building more of Athena

athena.sh builds AthExHelloWorld and the packages athena.py loads to run it: the package filter in the recipe, + <path> lines ending with - .*, as in ATLAS's package_filters.txt. To build more, add + <path> lines for the packages (and the packages they need) before - .*; the build then takes longer and needs more of AthenaExternals, which atlasexternals already builds with ATLAS's own filter.

When a build stops

Message	Cause and fix
lcg-view: 'main' is not an LCG release	No --set release=LCG_110 (nor in bits use build).
this Athena wants LCG_<N><postfix>; lcg-view provides ...	The athena ref wants another LCG than lcg-view makes (LCG_110_ATLAS_5, for Athena 25.0.71 to 25.0.75). Another postfix needs lcg-view.sh and atlasexternals.sh changed.
Athena <version> needs gcc15 ...	Athena 25.0.74 and later: build with --defaults atlas::gcc15::opt.
A download or clone fails in atlasexternals or Athena	The build needs the network (Prerequisites); with --sandbox, the recipes already allow it.

Notes for ATLAS users

• Always pass the release on the command line (--set release=LCG_110, or record it with bits use as above). The value selects the lcg.bits and stacks.bits branches and the CVMFS {release} path segment. It also enters every package hash. A release chosen any other way hashes differently, so nothing built by the other groups is reused. lcg-view stops with an error on the default main, because the ATLAS manifest needs an LCG release number.
• The LCG view. lcg-view uses bits overlay lcg to write LCG_110_ATLAS_5/LCG_externals_<platform>.txt and LCG_generators_<platform>.txt over the bits-built closure of lcg-externals and lcg-generators. The package directories in these files point straight at the bits install prefixes. ATLAS's own find_package(LCG 110 EXACT) (AtlasLCG) reads them, so no ATLAS CMake is changed.
• The _ATLAS_5 flavour. defaults-atlas.sh applies the deltas of lcgcmake heptools-110_ATLAS_5.cmake on top of the neutral lcg.bits LCG_110 branch: generator and xrootd version pins, the ATLAS-patched epos4, hijing and madgraph5amc versions, and the CUDA stack. It also disables DD4hep and acts (AthenaExternals builds its own GeoModel and ACTS), R, rpy2, onnxruntime and tf2onnx. Other communities using the same branch are not affected.
• Known gaps. tauolacpp builds 1.1.9.atlas1, because no atlas2 patch exists yet. The jax_cuda12_* packages have no recipe in lcg.bits. The cuda and cudnn pins (13.3.1, 9.20.0.48) are newer than the lcg.bits recipes support today.
• What is built. athena_release (default main) is the athena ref of both Athena and atlasexternals: its externals.txt picks the atlasexternals version, built with that version's own package filter plus CrestApi. The ref must use the LCG that lcg-view provides (LCG_110_ATLAS_5: 25.0.71 and later), or the build stops. Athena 25.0.74 and later need gcc15 (athena.sh checks the compiler first); build an older ref with the compiler it was released with, e.g. --defaults atlas::gcc14::opt. Athena currently builds only the AthExHelloWorld example and what athena.py AthExHelloWorld/HelloWorldConfig.py needs to run (the filter in athena.sh).
• Developing Athena. bits init -c . Athena creates a writable athena checkout next to the recipes; later builds of Athena use it. See the bits cookbook on developing a single package.
• CVMFS layout. Builds publish under /cvmfs/bits.cern.ch/atlas with the shared stacks.bits layout; only the prefix differs. prefix must match cvmfs_prefix in the bits-console ATLAS community configuration. When lcg-view is published, its post-relocate.sh rewrites the manifest directories to the published package paths, so find_package(LCG) resolves against CVMFS. Publishing is done by the bits-console pipeline after a working local build.

Files

File	Purpose
defaults-atlas.sh	ATLAS overlay: stacks.bits base, release tracking, CVMFS layout, _ATLAS_5 deltas and disables
lcg-externals.sh, lcg-generators.sh	ATLAS's top-level LCG externals and generators (from the LCG_110_ATLAS_5 manifest)
lcg-view.sh	Writes the LCG_<N>_ATLAS_5 manifests over the bits-built LCG closure
atlasexternals.sh	AthenaExternals, built with ATLAS's build_externals.sh
athena.sh	Athena, built with ATLAS's build.sh
setupATLAS.sh	Optional setupATLAS replacement that uses the bits-built LCG view and projects

The compiler and build-type profiles (gcc13, gcc14, gcc15, opt, dbg, cuda, ...) are not part of this repository. They come from stacks.bits.

More information

• Producing an LCG release view; ATLAS sources: athena and atlasexternals
• stacks.bits and lcg.bits READMEs: profiles, releases, CVMFS layout and the recipe pool; bits-providers: the registry
• bits User Guide, Cookbook, Reference
• bits-console: CI builds and CVMFS publishing

License

Apache License 2.0, see LICENSE.