1<!doctype html> 2<html lang="en-US"> 3 <head> 4 <meta charset="utf-8" /> 5 <meta name="viewport" content="width=device-width,initial-scale=1" /> 6 <meta name="generator" content="VuePress 2.0.0-rc.26" /> 7 <style> 8 :root { 9 --vp-c-bg: #fff; 10 } 11 12 [data-theme='dark'] { 13 --vp-c-bg: #1b1b1f; 14 } 15 16 html, 17 body { 18 background-color: var(--vp-c-bg); 19 } 20 </style> 21
21<script> 22 const useChoice = localStorage.getItem('vuepress-color-scheme') 23 const systemStatus = 24 'matchMedia' in window 25 ? window.matchMedia('(prefers-color-scheme: dark)').matches 26 : false 27 28 if (useChoice === 'light') { 29 document.documentElement.dataset.theme = 'light' 30 } else if (useChoice === 'dark' || systemStatus) { 31 document.documentElement.dataset.theme = 'dark' 32 } 33 </script>
33 34 <meta property="og:title" content="Documentation - TriBITS"><meta property="og:description" content="Core documentation for the TriBITS build, integration, and test framework."><meta property="og:image" content="/img/hero/docs-1600x900.jpg"><link rel="canonical" href="https://tribits.org/docs/"><link rel="icon" href="/favicon.ico"><link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png"><link rel="apple-touch-icon" href="/img/apple-touch-icon.png"><meta name="theme-color" content="#2c3e50"><meta property="og:type" content="website"><meta property="og:site_name" content="TriBITS"><meta name="twitter:card" content="summary_large_image"><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin=""><link href="https://fonts.googleapis.com/css2?family=Bitter:wght@400;500;600;700&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
34<script async="" defer="" data-website-id="43bd40a9-fd60-40d8-8fd9-40fdf176e553" data-api="/t/api/send" src="/t/umami"></script>
34<title>Documentation - TriBITS | TriBITS</title><meta name="description" content="Core documentation for the TriBITS build, integration, and test framework. Covers architecture, package model, dependency resolution, and project structure."> 35 <link rel="preload" href="/assets/style-COksVXw0.css" as="style"><link rel="stylesheet" href="/assets/style-COksVXw0.css"> 36 <link rel="modulepreload" href="/assets/app-WlgLpxym.js"><link rel="modulepreload" href="/assets/index.html-DAJegSVZ.js"><link rel="modulepreload" href="/assets/docs-1600x900-DilAoxEh.js"> 37 <link rel="prefetch" href="/assets/404.html-Oa4Loq6_.js" as="script"><link rel="prefetch" href="/assets/index.html-DAxIWS0d.js" as="script"><link rel="prefetch" href="/assets/index.html-DnkEC6b3.js" as="script"><link rel="prefetch" href="/assets/index.html-Dt5YlIgf.js" as="script"><link rel="prefetch" href="/assets/index.html-BO7sxh3N.js" as="script"><link rel="prefetch" href="/assets/TribitsBuildReference.html-OtVNNkj5.js" as="script"><link rel="prefetch" href="/assets/TribitsBuildReference.html-OtVNNkj5.js" as="script"><link rel="prefetch" href="/assets/TribitsDevelopersGuide.html-BKV-uHEh.js" as="script"><link rel="prefetch" href="/assets/TribitsDevelopersGuide.html-BKV-uHEh.js" as="script"><link rel="prefetch" href="/assets/TribitsMaintainersGuide.html-vWy3e1KY.js" as="script"><link rel="prefetch" href="/assets/TribitsMaintainersGuide.html-vWy3e1KY.js" as="script"><link rel="prefetch" href="/assets/index.html-f9wh96kg.js" as="script"><link rel="prefetch" href="/assets/index.html-40XtmL03.js" as="script"><link rel="prefetch" href="/assets/index.html-B8dcCDTG.js" as="script"><link rel="prefetch" href="/assets/index.html-C26M3zLG.js" as="script"><link rel="prefetch" href="/assets/index.html-BJhcJHAN.js" as="script"><link rel="prefetch" href="/assets/index.html-CBtG06wB.js" as="script"><link rel="prefetch" href="/assets/index.html-TyA6289n.js" as="script"><link rel="prefetch" href="/assets/index.html-BYzQkjnj.js" as="script"> 38 </head> 39 <body> 40 <div id="app"><!--[--><div class="vp-theme-container external-link-icon" vp-container><!--[--><header class="vp-navbar" vp-navbar><div class="vp-toggle-sidebar-button" title="toggle sidebar" aria-expanded="false" role="button" tabindex="0"><div class="icon" aria-hidden="true"><span></span><span></span><span></span></div></div><span><a class="route-link" href="/"><img class="vp-site-logo" src="/img/tribits-logo.svg" alt="TriBITS"><span class="vp-site-name vp-hide-mobile" aria-hidden="true">TriBITS</span></a></span><div class="vp-navbar-items-wrapper" style=""><!--[--><!--]--><nav class="vp-navbar-items vp-hide-mobile" aria-label="site navigation"><!--[--><div class="vp-navbar-item"><a class="route-link route-link-active auto-link" href="/docs/" aria-label="Docs"><!--[--><!--[--><!--]--><!--]-->Docs<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/guides/" aria-label="Guides"><!--[--><!--[--><!--]--><!--]-->Guides<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/reference/" aria-label="Reference"><!--[--><!--[--><!--]--><!--]-->Reference<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/pipelines/" aria-label="Pipelines"><!--[--><!--[--><!--]--><!--]-->Pipelines<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/downloads/" aria-label="Downloads"><!--[--><!--[--><!--]--><!--]-->Downloads<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/about/" aria-label="About"><!--[--><!--[--><!--]--><!--]-->About<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/changelog/" aria-label="Changelog"><!--[--><!--[--><!--]--><!--]-->Changelog<!--[--><!--[--><!--]--><!--]--></a></div><!--]--></nav><!--[--><!--]--><button type="button" class="vp-toggle-color-mode-button" title="toggle color mode"><svg class="light-icon" viewbox="0 0 32 32" style=""><path d="M16 12.005a4 4 0 1 1-4 4a4.005 4.005 0 0 1 4-4m0-2a6 6 0 1 0 6 6a6 6 0 0 0-6-6z" fill="currentColor"></path><path d="M5.394 6.813l1.414-1.415l3.506 3.506L8.9 10.318z" fill="currentColor"></path><path d="M2 15.005h5v2H2z" fill="currentColor"></path><path d="M5.394 25.197L8.9 21.691l1.414 1.415l-3.506 3.505z" fill="currentColor"></path><path d="M15 25.005h2v5h-2z" fill="currentColor"></path><path d="M21.687 23.106l1.414-1.415l3.506 3.506l-1.414 1.414z" fill="currentColor"></path><path d="M25 15.005h5v2h-5z" fill="currentColor"></path><path d="M21.687 8.904l3.506-3.506l1.414 1.415l-3.506 3.505z" fill="currentColor"></path><path d="M15 2.005h2v5h-2z" fill="currentColor"></path></svg><svg class="dark-icon" viewbox="0 0 32 32" style="display:none;"><path d="M13.502 5.414a15.075 15.075 0 0 0 11.594 18.194a11.113 11.113 0 0 1-7.975 3.39c-.138 0-.278.005-.418 0a11.094 11.094 0 0 1-3.2-21.584M14.98 3a1.002 1.002 0 0 0-.175.016a13.096 13.096 0 0 0 1.825 25.981c.164.006.328 0 .49 0a13.072 13.072 0 0 0 10.703-5.555a1.01 1.01 0 0 0-.783-1.565A13.08 13.08 0 0 1 15.89 4.38A1.015 1.015 0 0 0 14.98 3z" fill="currentColor"></path></svg></button><form class="search-box" role="search"><input type="search" placeholder="Search" autocomplete="off" spellcheck="false" value><!----></form></div></header><!--]--><div class="vp-sidebar-mask"></div><!--[--><aside class="vp-sidebar" vp-sidebar><nav class="vp-navbar-items" aria-label="site navigation"><!--[--><div class="vp-navbar-item"><a class="route-link route-link-active auto-link" href="/docs/" aria-label="Docs"><!--[--><!--[--><!--]--><!--]-->Docs<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/guides/" aria-label="Guides"><!--[--><!--[--><!--]--><!--]-->Guides<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/reference/" aria-label="Reference"><!--[--><!--[--><!--]--><!--]-->Reference<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/pipelines/" aria-label="Pipelines"><!--[--><!--[--><!--]--><!--]-->Pipelines<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/downloads/" aria-label="Downloads"><!--[--><!--[--><!--]--><!--]-->Downloads<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/about/" aria-label="About"><!--[--><!--[--><!--]--><!--]-->About<!--[--><!--[--><!--]--><!--]--></a></div><div class="vp-navbar-item"><a class="route-link auto-link" href="/changelog/" aria-label="Changelog"><!--[--><!--[--><!--]--><!--]-->Changelog<!--[--><!--[--><!--]--><!--]--></a></div><!--]--></nav><!--[--><!--]--><ul class="vp-sidebar-items"><!--[--><li><p tabindex="0" class="vp-sidebar-item vp-sidebar-heading active">Documentation <!----></p><ul class="vp-sidebar-children" style=""><!--[--><li><a class="route-link route-link-active auto-link vp-sidebar-item active" href="/docs/" aria-label="Documentation - TriBITS"><!--[--><!--[--><!--]--><!--]-->Documentation - TriBITS<!--[--><!--[--><!--]--><!--]--></a><!----></li><li><a class="route-link auto-link vp-sidebar-item" href="/docs/ci/" aria-label="Continuous Integration with TriBITS"><!--[--><!--[--><!--]--><!--]-->Continuous Integration with TriBITS<!--[--><!--[--><!--]--><!--]--></a><!----></li>
40<!--]--></ul></li><!--]--></ul><!--[--><!--]--></aside><!--]--><!--[--><main class="vp-page"><!--[--><!--]--><div vp-content><!--[--><!--]--><div id="content"><div class="hero-section"><h1 id="tribits-documentation" tabindex="-1"><a class="header-anchor" href="#tribits-documentation"><span>TriBITS Documentation</span></a></h1><p class="hero-tagline">Everything you need to understand the architecture, package model, and daily workflows of a TriBITS-managed project.</p><img class="hero-image" src="/img/hero/docs-1600x900.jpg" alt="TriBITS documentation overview showing build system architecture layers" width="1600" height="900"></div><h2 id="where-to-start" tabindex="-1"><a class="header-anchor" href="#where-to-start"><span>Where to Start</span></a></h2><p>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.</p><p>For hands-on walkthroughs, check the <a class="route-link" href="/guides/">Guides</a> section. For exact variable names and macro signatures, head to the <a class="route-link" href="/reference/">Reference</a>.</p><h2 id="architecture-overview" tabindex="-1"><a class="header-anchor" href="#architecture-overview"><span>Architecture Overview</span></a></h2><p>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.</p><p>The framework operates at three levels:</p><h3 id="project-level" tabindex="-1"><a class="header-anchor" href="#project-level"><span>Project Level</span></a></h3><p>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 <code>CMakeLists.txt</code> that looks deceptively simple because the heavy lifting happens inside the framework.</p><h3 id="repository-level" tabindex="-1"><a class="header-anchor" href="#repository-level"><span>Repository Level</span></a></h3><p>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.</p><p>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.</p><h3 id="package-level" tabindex="-1"><a class="header-anchor" href="#package-level"><span>Package Level</span></a></h3><p>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.</p><p>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.</p><h2 id="the-dependency-graph" tabindex="-1"><a class="header-anchor" href="#the-dependency-graph"><span>The Dependency Graph</span></a></h2><p>When you configure a TriBITS project, the framework reads every package declaration and builds a directed acyclic graph (DAG) of dependencies. This graph determines:</p><ul><li><strong>Build order.</strong> Packages are configured and built in topological order so that dependencies are always built before the things that need them.</li><li><strong>Enable/disable propagation.</strong> If you enable a package, its required dependencies are automatically enabled too. Optional dependencies can be toggled independently.</li><li><strong>Test selection.</strong> 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.</li></ul><p>The dependency graph is not just a build-time concept. It shapes how y
40ou 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.</p><div class="hint-container tip"><p class="hint-container-title">Why This Matters</p><p>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.</p></div><h2 id="configuration-model" tabindex="-1"><a class="header-anchor" href="#configuration-model"><span>Configuration Model</span></a></h2><p>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.</p><p>The standard pattern is:</p><div class="language-cmake line-numbers-mode" data-highlighter="prismjs" data-ext="cmake"><pre><code class="language-cmake"><span class="line"><span class="token comment"># Enable specific packages</span></span> 41<span class="line">-D Trilinos_ENABLE_Tpetra=<span class="token boolean">ON</span></span> 42<span class="line">-D Trilinos_ENABLE_Belos=<span class="token boolean">ON</span></span> 43<span class="line"></span> 44<span class="line"><span class="token comment"># TriBITS resolves dependencies automatically</span></span> 45<span class="line"><span class="token comment"># so enabling Belos also enables its required deps</span></span> 46<span class="line"></span> 47<span class="line"><span class="token comment"># Set build type</span></span> 48<span class="line">-D <span class="token variable">CMAKE_BUILD_TYPE</span>=Release</span> 49<span class="line"></span> 50<span class="line"><span class="token comment"># Enable tests for enabled packages</span></span> 51<span class="line">-D Trilinos_ENABLE_TESTS=<span class="token boolean">ON</span></span> 52<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>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.</p><h2 id="test-categories" tabindex="-1"><a class="header-anchor" href="#test-categories"><span>Test Categories</span></a></h2><p>TriBITS defines test categories that control when tests run:</p><ul><li><strong>BASIC</strong> tests run on every commit. They should be fast and catch the most common breakage.</li><li><strong>NIGHTLY</strong> tests run on a schedule. They can be slower and more thorough.</li><li><strong>HEAVY</strong> tests are expensive and run on demand or weekly. Think full-system integration tests that take hours.</li></ul><p>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.</p><h2 id="multi-repository-workflows" tabindex="-1"><a class="header-anchor" href="#multi-repository-workflows"><span>Multi-Repository Workflows</span></a></h2><p>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.</p><p>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.</p><p>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.</p><img src="/img/hero/docs-1600x900.jpg" alt="Multi-repository build workflow showing packages across three source repositories" width="1200" height="750"><h2 id="key-documentation-pages" tabindex="-1"><a class="header-anchor" href="#key-documentation-pages"><span>Key Documentation Pages</span></a></h2><p>These pages cover specific topics in depth:</p><ul><li><a class="route-link" href="/doc/TribitsDevelopersGuide.html">
52Developers Guide</a> covers the full development workflow: project layout, configuration, building, testing, and multi-repo setups.</li><li><a class="route-link" href="/doc/TribitsMaintainersGuide.html">Maintainers Guide</a> covers long-term maintenance: dependency hygiene, CI stability, versioning, and release practices.</li><li><a class="route-link" href="/doc/TribitsBuildReference.html">Build Reference</a> is the lookup table: variables, macros, patterns, and troubleshooting.</li></ul><h2 id="continuous-integration" tabindex="-1"><a class="header-anchor" href="#continuous-integration"><span>Continuous Integration</span></a></h2><p>TriBITS-based projects benefit from a standardized approach to CI because the framework defines how packages are configured and tested. See the <a class="route-link" href="/docs/ci/">CI documentation</a> for patterns and practical advice on setting up pipelines.</p><h2 id="next-steps" tabindex="-1"><a class="header-anchor" href="#next-steps"><span>Next Steps</span></a></h2><p>If you are just getting started, the <a class="route-link" href="/doc/TribitsDevelopersGuide.html">Developers Guide</a> 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 <a class="route-link" href="/guides/">Guides</a> section has task-specific walkthroughs for common scenarios.</p></div><!--[--><!--]--></div><footer class="vp-page-meta"><!----><div class="vp-meta-item git-info"><!----><!----></div></footer><nav class="vp-page-nav" aria-label="page navigation"><!----><a class="route-link auto-link next" href="/docs/ci/" aria-label="Continuous Integration with TriBITS"><!--[--><div class="hint">Next <span class="arrow right"></span></div><div class="link"><span class="external-link">Continuous Integration with TriBITS</span></div><!--]--></a></nav><!--[--><!--]--></main><!--]--></div><!--[--><!----><!--]--><!--]--></div> 53
53<script type="module" src="/assets/app-WlgLpxym.js" defer></script>
53 54
54<script type="module" src="https://static.cloudflareinsights.com/beacon.min.js/v4bc70e2c01a94c73b74392e4234840661791215815920" integrity="sha512-L0ha0OXavK/8okipN9F8BtP84dg9DUhPERbBXzwI6dgTA55d2+yweo3pn5CSFYs45/r8md2+xvUPtTdvTNRfjA==" data-cf-beacon='{"version":"2024.11.0","token":"d6d92e7a41e3491fb9cad4ed4521b9d3","r":1,"spa":2}' crossorigin="anonymous"></script>
54 55</body> 56</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.