User Tutorial

This tutorial provides instructions for:

• Adding BLT to a CMake project

• Building, linking, and installing libraries and executables

• Setting up unit tests with GTest

• Setting up host-config files to handle multiple platform configurations

• Using external project dependencies

• Exporting your project’s CMake targets for outside projects to use

• Creating documentation with Sphinx and Doxygen

The two example CMake projects used are included in BLT’s source tree at:

• <blt-dir>/cmake/docs/tutorial/bare_bones

• <blt-dir>/cmake/docs/tutorial/calc_pi

Here are direct links to the projects in BLT’s GitHub repo:

• https://github.com/LLNL/blt/tree/develop/docs/tutorial/bare_bones

• https://github.com/LLNL/blt/tree/develop/docs/tutorial/calc_pi

bare_bones provides a minimum template for starting a new project and calc_pi provides several examples that calculate the value of by approximating the integral using numerical integration. The code is adapted from ANL’s using MPI examples.

Most of the tutorial focuses on the BLT features used to create the complete calc_pi project.

The tutorial requires a C++ compiler and CMake, we recommend using CMake 3.8.0 or newer. Parts of the tutorial also require MPI, CUDA, Sphinx, and Doxygen.

We provide instructions to build and run these projects on several LLNL HPC platforms and ORNL’s Summit platform. See Host-configs.

Tutorial Contents

• Getting Started
  • Include BLT in your Git Repository
  • Include BLT in your CMake Project
  • Running CMake
  • Example: Bare Bones BLT Project
  • Example files
• Creating Targets
  • Example 1: Stand-alone Executable
  • Example 2: Executable with a Library
• Adding Tests
  • Configuring Tests within BLT
  • GoogleTest (C/C++ Tests)
  • FRUIT (Fortran Tests)
  • Adding a BLT unit test
  • Running Tests and Examples
  • Converting CTest XML to JUnit
• Host-configs
  • Building and Testing on Pascal
  • Building and Testing on Ray
  • Building and Testing on Summit
  • Example Host-configs
• Importing Targets
  • Common HPC Dependencies
    • MPI
    • CUDA
    • OpenMP
    • HIP
  • Third Party Libraries
    • No CMake Support
    • CMake’s Find Modules
    • First Class Project Support
• Creating Documentation
  • Calc Pi Sphinx Example
  • Calc Pi Doxygen Example
  • Building the Calc Pi Example Documentation
• Advanced Topics
  • Portable Compiler Flags
  • Exporting Targets
  • Object Libraries
• CMake Recommendations
  • Disable In-source Builds
  • Avoid using Globs to Identify Source Files
  • Use Arguments instead of Options in CMake Macros and Functions
  • Prefer Explicit Paths to Locate Third-party Dependencies
  • Error at Configure Time for Third-party Dependency Problems
  • Add Headers as Source Files to Targets
  • Always Support make install