TriBITS Documentation

Everything you need to understand the architecture, package model, and daily workflows of a TriBITS-managed project.

TriBITS documentation overview showing build system architecture layers

Where to Start

The documentation is organized around how people actually use the framework. If you are new, start with the architecture overview below. If you are looking for something specific, the sidebar and search will get you there faster.

For hands-on walkthroughs, check the Guides section. For exact variable names and macro signatures, head to the Reference.

Architecture Overview

TriBITS is a layer on top of CMake. It does not replace CMake; it provides conventions, macros, and a dependency resolution engine that make large multi-package projects manageable. Understanding this layering is important because it means everything CMake can do is still available. TriBITS just adds structure.

The framework operates at three levels:

Project Level

A TriBITS project is the top-level entity. It defines the project name, the list of available repositories, and global configuration options. The project-level CMakeLists.txt is where you call the TriBITS macros that initialize everything. Most projects have a single root CMakeLists.txt that looks deceptively simple because the heavy lifting happens inside the framework.

Repository Level

A repository is a source tree (often a Git repo) that contains one or more packages. TriBITS projects can span multiple repositories. The framework knows how to pull them together, resolve cross-repo dependencies, and build everything in the right order.

This is one of the features that sets TriBITS apart from most build systems. If your project lives across five Git repos, TriBITS handles that natively. You do not need to write custom scripts to clone and stitch repos together.

Package Level

A package is the fundamental unit in TriBITS. Each package declares its name, its upstream dependencies, the libraries it builds, and the tests it provides. Packages can also have subpackages for finer-grained dependency control.

The package model is where most of the design decisions happen. Getting the boundaries right between packages, keeping the dependency graph clean, and writing tests that give meaningful signal are the things that determine whether a TriBITS project is pleasant or painful to work with.

The Dependency Graph

When you configure a TriBITS project, the framework reads every package declaration and builds a directed acyclic graph (DAG) of dependencies. This graph determines:

  • Build order. Packages are configured and built in topological order so that dependencies are always built before the things that need them.
  • Enable/disable propagation. If you enable a package, its required dependencies are automatically enabled too. Optional dependencies can be toggled independently.
  • Test selection. You can run tests for a specific package and its dependents, or for the whole project. The graph tells the framework which tests are relevant.

The dependency graph is not just a build-time concept. It shapes how you think about your project's architecture. A clean graph with few cycles (ideally zero) means the project is modular and testable. A tangled graph means changes cascade unpredictably.

Why This Matters

Most build system problems in large projects are really dependency problems. TriBITS makes the dependency graph explicit and tool-visible, so you can analyze it, visualize it, and enforce rules about what is allowed to depend on what.

Configuration Model

TriBITS configuration is driven by CMake cache variables. The framework defines a set of standard variables for enabling packages, setting build types, controlling test categories, and tuning compiler options. On top of that, each package can define its own configuration variables.

The standard pattern is:

# Enable specific packages
-D Trilinos_ENABLE_Tpetra=ON
-D Trilinos_ENABLE_Belos=ON

# TriBITS resolves dependencies automatically
# so enabling Belos also enables its required deps

# Set build type
-D CMAKE_BUILD_TYPE=Release

# Enable tests for enabled packages
-D Trilinos_ENABLE_TESTS=ON

There is a hierarchy to how variables are resolved. Project-level defaults can be overridden by repository-level settings, which can be overridden by package-level settings, which can be overridden by the developer on the command line. This layering is deliberate. It lets maintainers set sensible defaults while still giving developers full control.

Test Categories

TriBITS defines test categories that control when tests run:

  • BASIC tests run on every commit. They should be fast and catch the most common breakage.
  • NIGHTLY tests run on a schedule. They can be slower and more thorough.
  • HEAVY tests are expensive and run on demand or weekly. Think full-system integration tests that take hours.

This categorization is not just a convenience. It is fundamental to keeping CI pipelines fast while still catching problems. If every test ran on every commit, developers would either wait too long or start ignoring failures.

Multi-Repository Workflows

One of the more unusual features of TriBITS is native support for multi-repository projects. The project can declare a list of repositories, each with its own URL and branch. During the configure step, TriBITS can clone or update these repos and then treat all their packages as part of one unified build.

This works because the dependency graph spans repositories. Package A in Repo 1 can depend on Package B in Repo 2, and the framework handles the ordering and configuration seamlessly.

The practical benefit is that teams can develop packages in separate repos (with separate permissions, CI, and release cadences) while still testing the integrated result. The superbuild configuration pulls everything together.

Multi-repository build workflow showing packages across three source repositories

Key Documentation Pages

These pages cover specific topics in depth:

  • Developers Guide covers the full development workflow: project layout, configuration, building, testing, and multi-repo setups.
  • Maintainers Guide covers long-term maintenance: dependency hygiene, CI stability, versioning, and release practices.
  • Build Reference is the lookup table: variables, macros, patterns, and troubleshooting.

Continuous Integration

TriBITS-based projects benefit from a standardized approach to CI because the framework defines how packages are configured and tested. See the CI documentation for patterns and practical advice on setting up pipelines.

Next Steps

If you are just getting started, the Developers Guide is the right first read. It walks through the core concepts with enough detail to be useful without drowning you in edge cases. After that, the Guides section has task-specific walkthroughs for common scenarios.