TriBITS

A CMake-based framework for building, integrating, and testing multi-repository scientific software projects. TriBITS handles the hard parts of dependency management, cross-package testing, and continuous integration so engineering teams can ship reliable software.

Quick Start Map

Find the section that matches what you need right now.

Most Used Topics

These are the areas where most teams spend their time when working with TriBITS. Each topic links deeper into the documentation.

Why TriBITS Exists

Large-scale scientific software tends to grow into constellations of interdependent packages. Each package has its own build requirements, its own tests, and its own release cadence. Left unmanaged, the coupling between these packages turns routine changes into multi-day integration exercises.

TriBITS sits on top of CMake and provides a structured layer for declaring packages, expressing dependencies between them, gating integration on test results, and doing all of this across multiple source repositories at once. It was designed for projects where "just build everything from scratch" stopped being practical years ago.

The framework does not try to replace CMake. It extends it. If you already know CMake, the learning curve is mostly about understanding the TriBITS package model and how the dependency graph drives configuration, build ordering, and test selection.

What Problems It Solves

Dependency declaration at the package level. Instead of scattering find_package calls and hoping the right version is installed, TriBITS lets each package declare what it needs and what it provides. The framework resolves the full dependency graph before any code compiles.

Multi-repository builds. Real projects live across multiple Git repositories. TriBITS supports superbuilds where the framework pulls in multiple repos, configures them in the right order, and builds the whole stack as one coherent project.

Test-gated integration. You can define test categories (basic, nightly, heavy) and gate downstream builds on upstream test results. If package A's tests fail, packages that depend on A do not proceed. This catches breakage early instead of letting it cascade.

Consistent CI patterns. Because TriBITS standardizes how packages are configured and tested, CI pipelines become more uniform. You write the pipeline logic once and it adapts as packages are added or dependencies change.

What It Does Not Do

TriBITS is not a package manager in the npm or pip sense. It does not download pre-built binaries from a central registry. It is not a replacement for Spack, Conan, or vcpkg. It handles the build orchestration layer, not the distribution layer.

It also does not enforce a specific coding style, directory layout beyond the package level, or version numbering scheme. Those decisions remain with the project maintainers.

How Teams Typically Use TriBITS

A typical TriBITS project has a root CMake configuration that declares the project and lists available packages. Each package lives in its own directory (sometimes its own repository) and contains a small set of TriBITS-specific CMake files that declare the package name, its dependencies, its libraries, and its tests.

When a developer runs the configure step, TriBITS reads all the package declarations, resolves the dependency graph, enables the requested subset of packages, and generates the build system. The developer builds and tests as usual with make or ninja, but the ordering and configuration were handled by the framework.

For CI, the same structure means you can configure builds that only enable changed packages and their dependents, dramatically reducing build times for incremental work while still catching integration issues.

Recent Updates

• 2026-02-15Expanded the Build Reference with additional failure mode documentation and troubleshooting steps.
• 2026-01-28Added new pipeline patterns for matrix builds and conditional test stages.
• 2026-01-10Reorganized the Guides section with clearer categories for new and experienced users.
• 2025-12-19Updated Developers Guide sections on multi-repo workflow and superbuild configuration.
• 2025-11-30Clarified dependency declaration patterns in the Reference section and added inline examples.

See the full Changelog for all updates.

Getting Started

If you are encountering TriBITS for the first time, the recommended path through this documentation depends on your role:

For developers joining an existing TriBITS project: Start with the Developers Guide to understand the mental model, then use the Guides section for specific tasks like adding packages or configuring dependencies.

For build engineers setting up CI: Start with the Pipelines section for ready-made pipeline patterns, and refer to the Reference section for the specific variables and macros you will need to configure.

For maintainers responsible for long-term project health: The Maintainers Guide covers dependency hygiene, CI stability, versioning, and release practices. The Documentation section provides the architectural context.

For evaluators deciding whether TriBITS fits your project: Read the About page for the design philosophy, then review the Documentation section for the architecture overview. The Developers Guide has practical examples that show how the framework works in practice.

All documentation is searchable using the search box in the navigation bar. If you cannot find what you need, the Contact page has information on how to request new content or report documentation gaps.