lcg.bits

lcg.bits is the shared recipe pool for the LCG software stack: about 1,100 bits recipes for the HEP externals, Python/ML stack and Monte Carlo generators that lcgcmake builds (ROOT, Geant4, Python, CMake, pythia8, sherpa, …), plus the compiler toolchains (GCC-Toolchain, Clang-Toolchain). It holds recipes only: no defaults-*.sh profiles, no meta-packages and no CVMFS layout. Those live in stacks.bits, the shared stack base, which requires: lcg.bits and selects which branch of this repository a build uses.

Every LCG-based community builds on this pool through stacks.bits:

key4hep.bits ┐
ship.bits    │
lhcb.bits    ├── requires ──▶ stacks.bits ── requires ──▶ lcg.bits
atlas.bits   │
testbed.bits ┘

lcg.bits is registered in bits-providers as an always_load repository provider, so bits clones it automatically (into sw/REPOS/lcg.bits/…) whenever a build needs it. You normally never check it out yourself unless you are editing recipes.

Getting started

Users normally do not clone lcg.bits directly. You do not build from this directory: it has no defaults-release.sh, so a build here would get none of the stack's compiler, C++ standard or build-type settings. Build from stacks.bits (or from your community's repository) and bits fetches the right lcg.bits branch for you. Install bits and prepare the machine as described in Installation & Prerequisites in the bits user guide (the platforms the LCG CI builds, whose binaries are reused, are listed in the stacks.bits README), then:

bits init stacks.bits && cd stacks.bits     # or: git clone -b LCG_110 https://github.com/bitsorg/stacks.bits
bits use build --docker --architecture x86_64-el9 --defaults gcc14::opt --set release=LCG_110
bits build --dry-run ROOT                   # what would be reused and what built
bits build ROOT                             # one package and its dependencies
bits enter ROOT/latest                      # shell with ROOT loaded; `exit` to leave

--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 externals builds all externals and bits build generators the MC generators. bits q lists what was built (add -a <arch> to bits q/bits enter if several architectures are installed in the work directory). Check the machine with bits doctor. To build elsewhere, export BITS_WORK_DIR=/path/to/sw.

Any package: name in this repository can be built directly. Package names are the package: field of the recipe (ROOT, Geant4, GCC-Toolchain, pythia8), not necessarily the file name. The stacks.bits README explains the --defaults axes (compiler, build type, CUDA, release line) and the CVMFS layout.

Notes for LCG users

Branches and releases

Branch	Role
main	Trunk. Used when no release is chosen (release = main).
LCG_110	The LCG 110 release recipes.
LCG_110b	LCG 110 with security upgrades of some packages.
devel	Older development branch; not used by the default builds.

The stacks.bits dev3/dev4 nightly profiles need no branch of their own: they build the release branch's recipes with a few packages pinned to development heads or fixed tags.

The branch is chosen by the release variable that stacks.bits declares in defaults-release.sh:

variables:
  release: main
overrides:
  lcg.bits:
    tag: "%(release)s"     # the lcg.bits branch to clone

Pass the release on the command line, --set release=LCG_110. That is the convention every stacks-based community follows, so packages hash identically across groups and are reused from the binary store instead of rebuilt. The same value also names the {release} level of the CVMFS path (/cvmfs/bits.cern.ch/lcg/releases/LCG_110/…); main drops that level. A new release is a new branch here named after it (LCG_<NNN>). Without --set, bits takes the release from a release: in the chosen profiles, else from the branch of the stacks.bits checkout (LCG_110-patches gives LCG_110), else main; the branch must exist here.

Editing recipes

• Recipes are YAML headers plus a Bash body; most use the helpers from bits-recipe-tools (its recipe is in this repository; project: bits-recipe-tools). See Writing Recipes with bits-recipe-tools.
• Patches applied by recipes are in patches/; the macOS Homebrew system layer is in macos/Brewfile.
• Release-specific version pins belong in a defaults profile (stacks.bits defaults-dev3.sh/defaults-dev4.sh, or a community overlay), not in a copy of the recipe. See Override a package version without editing the recipe.
• To test a change, push it to a branch and build from stacks.bits with --set release=<branch>; bits clones that branch of lcg.bits.
• scripts/lcg2bits.py is the converter that generated the initial recipes from lcgcmake's heptools-*.cmake and CMakeLists.txt files.

Licence and compliance data

This repository is the source of the licence information for everything built from it. Each recipe header carries:

Field	Meaning
license:	SPDX expression of the package's licence (present in every recipe).
redistributable:	Which forms may leave the build host: all (default), binaries, sources, none. Packages marked none are built and usable locally but never uploaded to the store or published to CVMFS.
acknowledgment:	Attribution text that must accompany the binaries.

These fields do not enter package hashes, so correcting them never triggers a rebuild. At publish time bits turns them into a per-release NOTICE, LICENSE-SOURCE-OFFER.txt and CycloneDX/SPDX SBOMs. To audit:

bits compliance --recipes path/to/lcg.bits --no-store-check   # this pool's metadata only
cd stacks.bits                                                 # an LCG_110 checkout
bits compliance --defaults gcc14::opt externals generators     # the closure of a stack

bits compliance takes no --set, so run the second form in an LCG_110 checkout of stacks.bits: the release then comes from the branch.

See Licence compliance and redistribution policy and bits compliance.

CI and publishing

Builds, platforms and the defaults chain are configured in bits-console, which builds, publishes and certifies the LCG stack. Nightly builds and builds on each push to a branch of this repository are set up there as schedules (see steps 4 and 5 of Phase 4 of the bits workflow guide); a build on a push goes to the binary store only, and is neither certified nor published.

More information

• Communities built on this pool: key4hep.bits, ship.bits, lhcb.bits, atlas.bits, testbed.bits; bits-providers: the provider registry
• stacks.bits README: the defaults, axes, release selection and CVMFS layout used with this pool
• bits User Guide, Cookbook, Reference, in particular Repository Provider Feature and Defaults Profiles
• bits-console: CI builds and CVMFS publishing

License

GNU General Public License v3.0; see LICENSE. The packages built from these recipes keep their own licences, recorded in each recipe's license: field.