Reference

The lookup table. Variables, macros, patterns, and options for working with TriBITS projects.

How to Use This Reference

This section is organized for lookup, not for reading start to finish. Use the headings and search to find what you need. Each entry includes the variable or macro name, what it does, and common usage patterns.

For explanations of why things work the way they do, see the Documentation section. For step-by-step task instructions, see the Guides.

Project-Level Configuration Variables

These variables control the overall behavior of a TriBITS build. Set them on the CMake command line or in a configuration file.

Package Enablement

Testing

Build Configuration

Multi-Repository

Core TriBITS Macros

These macros form the API that package developers use most often.

tribits_project()

Declares the top-level project. Called once in the root CMakeLists.txt.

tribits_project()

No arguments. The project name comes from the project() call that precedes it.

tribits_package()

Declares a package. Called at the top of each package's CMakeLists.txt.

tribits_package(PackageName)

This must be paired with tribits_package_postprocess() at the end of the file. Everything between these two calls defines the package contents.

tribits_package_postprocess()

Finalizes package registration. Must be the last TriBITS call in a package's CMakeLists.txt.

tribits_package_postprocess()

Forgetting this call is a common source of subtle bugs where tests or install rules do not behave correctly.

tribits_add_library()

Adds a library target to the current package.

tribits_add_library(mylib
  HEADERS
    mylib.hpp
    utils.hpp
  SOURCES
    mylib.cpp
    utils.cpp
  DEPLIBS
    some_other_lib
)

Key options:

• HEADERS - Header files to install.
• SOURCES - Source files to compile.
• DEPLIBS - Other libraries (within the same package) to link against.
• IMPORTEDLIBS - External libraries to link against.
• NOINSTALLHEADERS - Install library but not headers.

tribits_add_executable()

Adds an executable target.

tribits_add_executable(myapp
  SOURCES main.cpp
  DEPLIBS mylib
)

tribits_add_test()

Adds a test that runs an existing executable.

tribits_add_test(myapp
  NAME MyTest
  ARGS "--input=test_data.xml"
  NUM_MPI_PROCS 4
  CATEGORIES BASIC
)

Key options:

• NAME - Test name (defaults to executable name).
• ARGS - Arguments passed to the executable.
• NUM_MPI_PROCS - Number of MPI processes.
• CATEGORIES - BASIC, NIGHTLY, or HEAVY.
• PASS_REGULAR_EXPRESSION - Regex that must appear in stdout for the test to pass.
• FAIL_REGULAR_EXPRESSION - Regex that, if found in stdout, means the test failed.

tribits_add_executable_and_test()

Convenience macro that combines tribits_add_executable() and tribits_add_test() in one call:

tribits_add_executable_and_test(
  MyTest
  SOURCES my_test.cpp
  NUM_MPI_PROCS 1
  CATEGORIES BASIC
)

tribits_add_advanced_test()

For tests that need multiple steps, custom scripts, or complex pass/fail logic:

tribits_add_advanced_test(
  MyAdvancedTest
  TEST_0 EXEC myapp ARGS "--setup"
  TEST_1 EXEC myapp ARGS "--run"
  TEST_2 EXEC myapp ARGS "--verify"
  CATEGORIES NIGHTLY
)

Each TEST_N step runs sequentially. If any step fails, the test fails.

Dependency Declaration

Dependencies are declared in each package's cmake/Dependencies.cmake file.

tribits_package_define_dependencies()

tribits_package_define_dependencies(
  LIB_REQUIRED_PACKAGES PackageA PackageB
  LIB_OPTIONAL_PACKAGES PackageC
  TEST_REQUIRED_PACKAGES TestUtils
  TEST_OPTIONAL_PACKAGES HeavyTestFramework
  LIB_REQUIRED_TPLS Boost
  LIB_OPTIONAL_TPLS MPI
)

Dependency types:

• LIB_REQUIRED_PACKAGES - Internal packages required for the library to build.
• LIB_OPTIONAL_PACKAGES - Internal packages that enable additional features.
• TEST_REQUIRED_PACKAGES - Internal packages needed to build tests.
• TEST_OPTIONAL_PACKAGES - Internal packages for optional test features.
• LIB_REQUIRED_TPLS - External third-party libraries required.
• LIB_OPTIONAL_TPLS - External third-party libraries optional.

Third-Party Libraries (TPLs)

TPLs are external dependencies not managed by TriBITS. The framework provides a standard way to find and configure them:

# In FindTPLBoost.cmake
tribits_tpl_find_include_dirs_and_libraries(Boost
  REQUIRED_HEADERS boost/config.hpp
  REQUIRED_LIBS_NAMES boost_system boost_filesystem
)

The TPL_ENABLE_<name> variable controls whether a TPL is used.

Install Targets

TriBITS handles installation through standard CMake install mechanisms, triggered by the library and executable declarations:

cmake --install . --prefix /opt/myproject

Headers declared in tribits_add_library() are installed to include/. Libraries go to lib/. Executables go to bin/. Configuration files for downstream CMake consumers are generated automatically.

Common Configuration Patterns

Minimal Development Build

cmake -D CMAKE_BUILD_TYPE=Debug \
      -D <Project>_ENABLE_<MyPackage>=ON \
      -D <Project>_ENABLE_TESTS=ON \
      -B build

Full Release Build

cmake -D CMAKE_BUILD_TYPE=Release \
      -D BUILD_SHARED_LIBS=ON \
      -D <Project>_ENABLE_ALL_PACKAGES=ON \
      -D CMAKE_INSTALL_PREFIX=/opt/release \
      -B build

CI Incremental Build

cmake -D <Project>_ENABLE_<ChangedPackage>=ON \
      -D <Project>_ENABLE_ALL_FORWARD_DEP_PACKAGES=ON \
      -D <Project>_ENABLE_TESTS=ON \
      -D <Project>_TEST_CATEGORIES=BASIC \
      -B build

Troubleshooting Reference