Continuous Integration with TriBITS

CI is where build systems prove their worth. A clean dependency model and standardized test categories mean your pipelines can be smarter than "build everything, test everything, hope for the best."

TriBITS gives CI pipelines structural information about the project. This page covers how to use that information effectively.

The Build-Test Loop

The fundamental CI pattern for a TriBITS project is straightforward:

1. Configure the project with the relevant packages enabled.
2. Build in dependency order.
3. Run tests for the enabled packages.
4. Report results.

What makes TriBITS CI different from a naive "run cmake and ctest" approach is that step 1 can be intelligent. Instead of enabling everything, you enable the packages that changed and their downstream dependents. The framework resolves the rest.

# Enable only the changed package and its dependents
cmake -D MyProject_ENABLE_ChangedPackage=ON \
      -D MyProject_ENABLE_ALL_FORWARD_DEP_PACKAGES=ON \
      -D MyProject_ENABLE_TESTS=ON \
      ..

This keeps CI times reasonable as the project grows. A change to a leaf package only builds and tests that package. A change to a core package builds and tests everything that depends on it.

Incremental vs Full Builds

Most CI runs should be incremental: only recompile what changed and what depends on it. Full builds should happen on a schedule (nightly or weekly) to catch environment drift and subtle interactions.

TriBITS supports both patterns through its package enable system:

• Incremental: enable changed packages plus forward dependencies.
• Full: enable all packages. Use the NIGHTLY or HEAVY test category to run extended tests.

The key is not to treat full builds as the normal case. If every PR triggers a full build of a 200-package project, developers will stop waiting for CI and start merging without it.

Test Categories in CI

Continuous integration pipelines should map to TriBITS test categories:

This mapping ensures that fast feedback comes from fast tests, and thorough validation happens when it matters most.

Handling Flaky Tests

Every large project has flaky tests. The question is not whether you will have them, but how you manage them. Ignoring flakes erodes trust in CI. Over-reacting to them wastes developer time.

Practical approaches:

• Track flake rates. If a test fails more than 2% of the time without code changes, it is flaky. Log it.
• Quarantine, do not delete. Move known flakes to a separate test category that runs but does not gate merges.
• Fix root causes. Most flakes come from timing assumptions, shared state, or resource contention. These are real bugs worth fixing.
• Retry with limits. Automatic retry (once) is reasonable for known intermittent issues. More than one retry is a sign you are papering over a problem.

TriBITS test categories help here. You can mark a known-flaky test as NIGHTLY to remove it from the PR gate while keeping it visible in scheduled runs.

Multi-Repository CI

When a project spans multiple repositories, CI gets more complicated. A change in one repo can break packages in another. TriBITS handles this through its superbuild model, but the CI pipeline needs to be aware of cross-repo dependencies.

The typical approach:

1. Detect which repo changed.
2. Configure a superbuild that includes all repos.
3. Enable the changed packages and their cross-repo dependents.
4. Build and test.

This requires that your CI system can check out multiple repos and run the superbuild configure. Most modern CI platforms support this through multi-repo checkout steps.

Build Caching

TriBITS projects are CMake projects, so standard CMake build caching applies. ccache or sccache can dramatically reduce compilation times, especially in CI where the same code is built repeatedly across branches.

The key consideration with TriBITS is that the configure step can be expensive for large projects because of the dependency resolution. Caching the CMake configuration (the build directory) between CI runs helps, but be careful about stale cache entries when the package list or dependency graph changes.

# Use ccache for compilation caching
export CCACHE_DIR=/ci-cache/ccache
cmake -D CMAKE_CXX_COMPILER_LAUNCHER=ccache ..

Reporting and Dashboards

TriBITS integrates with CDash (the CMake testing dashboard) for test result reporting. If your organization uses CDash, TriBITS can submit results directly:

ctest -D Experimental
# or for nightly builds
ctest -D Nightly

Even without CDash, the CTest XML output can be parsed by most CI platforms to show test results inline with the build.

Common CI Pitfalls

Building everything on every PR. This does not scale. Use incremental builds.

Ignoring test failures. If CI is red and nobody cares, CI is not providing value. Fix failures or quarantine them, but do not let the dashboard stay red.

Not testing the integration. Unit tests are necessary but not sufficient. Integration tests that exercise cross-package interfaces catch a different class of bugs. Use NIGHTLY tests for this.

Slow feedback loops. If CI takes 2 hours for a PR, developers will context-switch away and lose momentum. Target 15-30 minutes for PR builds by using incremental builds and BASIC tests.

Pipeline Examples

See the Pipelines section for concrete CI pipeline configurations and patterns that work with TriBITS projects across different CI platforms.