About TriBITS
A build framework shaped by the practical demands of large-scale scientific software engineering.
What TriBITS Is
TriBITS stands for Tribal Build, Integrate, and Test System. It is a CMake-based framework designed for managing the complexity that comes with large, multi-package, multi-repository software projects. The kinds of projects where "just use CMake" is true but insufficient. Where the build system needs to understand package boundaries, dependency graphs, and test categorization across dozens or hundreds of interconnected components.
The framework grew out of the needs of scientific computing projects. These projects tend to share a set of characteristics that make build management difficult: long-lived codebases with accumulated coupling, teams distributed across organizations, packages that evolved independently but need to integrate reliably, and testing requirements that range from quick sanity checks to week-long simulations.
TriBITS does not try to be a general-purpose build system. It is specifically designed for the pattern of "many packages with declared dependencies, built and tested together." If that matches your situation, the framework removes a significant amount of build infrastructure work. If it does not, standard CMake is probably a better fit.
Design Philosophy
Several principles guided the design of TriBITS and continue to guide its evolution.
Build What You Need, Not Everything
Large projects have many packages. Most developers work on a few at a time. TriBITS lets you enable just the packages you care about, and it figures out what else needs to be enabled to satisfy dependencies. This keeps configure and build times reasonable for daily development while still supporting full-project builds for integration testing.
Make Dependencies Explicit
Implicit dependencies are the source of most "works on my machine" problems. If package A uses headers from package B but does not declare that dependency, builds will succeed whenever B happens to be configured first and fail otherwise. TriBITS forces explicit declaration. The dependency graph is a first-class data structure that the framework analyzes, validates, and uses to drive the build.
Tests Are Part of the Build System
Testing is not an afterthought in TriBITS. Test declarations are part of the package CMake files. Test categories (BASIC, NIGHTLY, HEAVY) are baked into the framework. CI pipelines can query the dependency graph to determine which tests to run. This integration means testing scales with the project instead of becoming a separate, increasingly disconnected process.
Support Real-World Project Structure
Real projects are messy. They span multiple repositories. They have optional dependencies. They need to build on different platforms with different compilers. They have tests that take 5 seconds and tests that take 5 hours. TriBITS was designed with this reality in mind, not for the clean-room case where everything is in one repo and builds with one compiler.
What Problem Does It Solve
Consider a project with 100 packages across 5 repositories. Without TriBITS (or something like it), you would need to:
- Write custom CMake logic to discover and configure packages in the right order.
- Handle cross-repository dependencies manually.
- Build separate CI pipelines for each repo and somehow test the integration.
- Manage test selection and categorization outside the build system.
- Hope that developers remember to update dependency information when they change code.
TriBITS replaces all of that with a declarative model. Each package says what it is, what it needs, and what it provides. The framework handles the rest.
This does not eliminate complexity. Large software projects are inherently complex. But it moves the complexity from ad-hoc scripts and tribal knowledge into a structured framework where it can be analyzed, automated, and maintained.
Scope and Limitations
TriBITS handles build orchestration: configuring, building, testing, and installing packages in the right order with the right options. It does not handle:
- Package distribution. TriBITS is not a package manager. It does not download pre-built binaries or resolve external dependency versions. Tools like Spack, Conan, or vcpkg handle that layer.
- Deployment. Getting built software onto production systems is outside the framework's scope.
- Code quality enforcement. TriBITS does not enforce coding standards, style rules, or documentation requirements. Those are project-level decisions.
The framework is deliberately focused. It does one thing well rather than trying to be a complete software lifecycle tool.
The Documentation on This Site
This site serves as the primary documentation resource for TriBITS. It is organized into several sections:
- Documentation covers the architecture and core concepts.
- Guides provides step-by-step walkthroughs for common tasks.
- Reference is the lookup table for variables, macros, and configuration options.
- Pipelines shows CI/CD patterns that work with the framework.
- Downloads has offline resources and presentation materials.
The legacy documentation pages (Developers Guide, Maintainers Guide, Build Reference) contain detailed reference material that complements the newer documentation sections.
Contributing and Feedback
If you find errors in the documentation, unclear explanations, or missing topics, feedback is welcome. Use the Contact page to get in touch. Documentation improvements are tracked in the Changelog.
We encourage contributions from all experience levels. Whether it is a small typo fix, a new code example, or a suggestion for a missing topic, every contribution improves the documentation for the community. Review the Developers Guide to understand the framework's conventions before proposing changes.
History and Context
TriBITS grew out of the practical needs of scientific software teams working on projects with dozens of interdependent packages spread across multiple repositories. The framework was developed to address problems that standard CMake alone does not solve well at scale: automatic dependency resolution across packages, test category management, and multi-repository integration.
The name TriBITS stands for Tribal Build, Integrate, and Test System. The "tribal" in the name reflects the framework's origin in collaborative scientific computing environments where multiple teams contribute to a shared codebase. The framework encodes the build system knowledge that teams accumulate over years of working together, making that knowledge explicit and repeatable rather than locked in individual expertise.
Over time, the framework has been refined based on real-world usage in projects ranging from small research codes to large production applications with hundreds of packages. The design priorities have remained consistent: make dependency management explicit, support incremental builds at the package level, and integrate testing directly into the build workflow.