Bits is a build orchestration tool for complex software stacks. It fetches sources, resolves dependencies, and builds packages in a reproducible, parallel environment.
Full documentation is available in REFERENCE.md. This guide covers only the essentials.
git clone https://github.com/bitsorg/bits.git
cd bits
export PATH=$PWD:$PATH # add bits to your PATH
python -m venv .venv
source .venv/bin/activate
pip install -e . # install Python dependenciesRequirements: Python 3.8+, git, and Environment Modules (modulecmd).
On macOS: brew install modules
On Debian/Ubuntu: apt-get install environment-modules
On RHEL/CentOS: yum install environment-modules
# 1. Clone a recipe repository
git clone https://github.com/bitsorg/alice.bits.git
cd alice.bits
# 2. Check system requirements for ROOT
bits doctor ROOT
# 3. Build ROOT and all its dependencies
bits build ROOT
# 4. Enter the built environment
bits enter ROOT/latest
# 5. Run the software
root -b
# 6. Exit the environment
exit| Command | Description |
|---|---|
bits build <pkg> |
Build a package and its dependencies. |
bits enter <pkg>/latest |
Spawn a subshell with the package environment loaded. |
bits load <pkg> |
Print commands to load a module (must be eval'd). |
bits q [regex] |
List available modules. |
bits clean |
Remove stale build artifacts from a temporary build area. |
bits cleanup |
Evict old or infrequently used packages from a persistent workDir. |
bits doctor <pkg> [<pkg>...] |
Check that the system satisfies all recipe requirements before building. |
bits doctor --runner |
Validate the full build-runner environment (compiler, git, Docker, podman, CVMFS, disk, store). |
bits verify --from-manifest FILE |
Confirm a live deployment matches the build manifest (SHA-256 and provider commits). |
Create a bits.rc file (INI format) to set defaults:
[bits]
organisation = ALICE
remote_store = https://s3.cern.ch/swift/v1/alibuild-repo
prerequisites_url = https://alice-doc.github.io/alice-analysis-tutorial/building/
cvmfs_repos = /cvmfs/alice.cern.ch,/cvmfs/sft.cern.ch
[ALICE]
sw_dir = /path/to/sw # output directory
repo_dir = /path/to/recipes # recipe repository root
search_path = common,extra # additional recipe dirs (appended .bits)Bits looks for bits.rc in: --config FILE → ./bits.rc → ./.bitsrc → ~/.bitsrc.
Useful [bits] keys:
| Key | Description |
|---|---|
remote_store |
Default binary store URL (same syntax as --remote-store). |
write_store |
Default upload store URL. |
prerequisites_url |
URL shown when bits doctor cannot find the C++ compiler or git. |
cvmfs_repos |
Comma-separated CVMFS mount paths checked by bits doctor --runner. |
provider_policy |
name:prepend|append pairs controlling BITS_PATH insertion order. |
store_integrity |
true to enable SHA-256 verification of every recalled tarball. |
Create a file <package>.sh inside a *.bits directory with:
package: mylib
version: "1.0"
source: https://github.com/example/mylib.git
tag: v1.0
requires:
- zlib
---
./configure --prefix="$INSTALLROOT"
make -j${JOBS:-1}
make installbits clean # remove temporary build directories
bits clean --aggressive-cleanup # also remove source mirrors and tarballs
# Persistent workDir cache management (evict old / low-disk-space packages)
bits cleanup --max-age 14 # evict packages not used in the last 14 days
bits cleanup --min-free 100 # free space until at least 100 GiB available
bits cleanup -n # dry-run: show what would be removed# Build inside a Docker container for a specific Linux version
bits build --docker --architecture ubuntu2004_x86-64 ROOT
# Cross-compile for ARM64 on an x86-64 host (requires QEMU binfmt handlers)
bits build --docker --architecture slc9_aarch64 MyAnalysis
# Use a remote binary store (S3, HTTP, rsync) to share pre-built artifacts
bits build --remote-store s3://mybucket/builds ROOTThe --cvmfs-prefix flag (which embeds the final CVMFS deployment path at compile time so no relocation is needed at publish time) and bits publish --no-relocate are used by the bits-console-triggered CI pipeline on the build runners — they are not normally typed by end users. See WORKFLOWS.md Phase 5 for the user-facing workflow and REFERENCE.md §22 for the flag reference.
Docker support | Cross-compilation via QEMU | Remote stores
# Check runner environment before first use (compiler, git, Docker, podman, disk…)
bits doctor --runner --cvmfs-repos /cvmfs/alice.cern.ch
# Machine-readable runner report for CI / bits-console health panel
bits doctor --runner --json
# Verify that a live CVMFS deployment matches a recorded build manifest
bits verify --from-manifest alice-o2-20260411.json \
--cvmfs-root /cvmfs/alice.cern.chbits doctor reference | bits verify reference | Deployment verification §22c
git clone https://github.com/bitsorg/bits.git
cd bits
python -m venv .venv
source .venv/bin/activate
pip install -e .[test]
# Run tests
tox # full suite on Linux
tox -e darwin # reduced suite on macOS
pytest # fast unit tests onlybits uses a single toolchain from your laptop to experiment-wide CVMFS. Clone a package source next to your recipe checkout and bits detects it automatically, building your local version while resolving all other dependencies from the shared recipe repo. Once tested locally, the change follows an unbroken path: commit → recipe MR → CI build → bits publish → CVMFS. Group admins publish full experiment stacks; individual users can publish single packages to a separate namespace — both paths use the same commands and the same recipes.
See WORKFLOWS.md for the full phase-by-phase walkthrough and workflow diagram.
- Development-to-deployment workflow & diagram
- Environment management (
bits enter,load,unload) - Dependency graph visualisation
- Runner environment validation (
bits doctor --runner) - Deployment verification (
bits verify) - Repository provider feature (dynamic recipe repos)
- Defaults profiles
- Cross-compilation via QEMU
- Design principles & limitations
- CVMFS publishing pipeline & bits-console
Note: Bits is under active development. For the most up-to-date information, see the full REFERENCE.md.