An introduction to the build pipeline, and how we can orchestrate it manually

Before working with CMake, it's useful to understand the tools it orchestrates. This lesson guides you through setting up a C++ toolchain.

Building C++ Programs

Walking through the steps of the C++ compilation process, from source code to machine code.

The Compilation Pipeline

The linker's role in the build process, how it resolves symbols to combine object files, and how to troubleshoot common errors.

Object Files and the Linking Process

The difference between static and dynamic libraries, how to create them, and the trade-offs between them.

Static and Shared Libraries

The C++ Build Process

Recommended approaches for managing large projects and the libraries that they depend on

Learn how to structure your C++ projects for scalability and maintainability, from basic directory layouts to managing multiple modules.

Organizing a C++ Project

Learn to manage third-party libraries in C++, covering include/library paths, static vs. shared libraries, versioning, and platform differences.

Managing Libraries and Dependencies

An introduction to traditional build tools like Makefiles and IDE projects, highlighting the maintenance, scalability, and cross-platform challenges that result

Automated Build Systems and Their Limitations

Project Structure and Dependency Management

Setting up CMake and creating your first project

An introduction to CMake, the cross-platform, open-source meta-build system that solves the core challenges of C++ project management.

Why CMake?

A step-by-step guide to installing CMake. We'll explore command-line, GUI, and IDE workflows, and how to configure your compiler.

Setting Up a CMake Environment

Creating the bare minimum `CMakeLists.txt` file and build up to a project with an executable and a library, learning the fundamental commands along the way.

Writing a CMakeLists File

Learn the two-stage process of building a CMake project. This lesson covers configuring, generating, building, running, and troubleshooting common errors.

Building and Running CMake Projects

Learn how to organize large C++ projects in CMake using subdirectories and the `add_subdirectory()` command to create modular, maintainable builds.

CMake Project Structure and Subdirectories

Introducing CMake

Exploring CMake's programming features, caching mechanisms, and interactions with the file system

A primer on the fundamental building blocks of the CMake language: variables, string interpolation, and logging messages.

CMake Variables and Logging

Discover the CMake Cache, the mechanism for storing persistent user-configurable options, and learn how to create and manage cached variables.

The CMake Cache

Exploring CMake's command syntax and its list data type, including how to create, manipulate, and use lists in your projects.

CMake Commands, Arguments, and Lists

Transform your static build descriptions into dynamic scripts with CMake's control flow commands, if() and foreach().

CMake Conditionals and Loops

Exploring CMake's `file()` command, covering how to read, write, copy, and glob files, and how to manipulate paths.

Working with the File System

Learn to create reusable logic with CMake functions and macros, and how to organize them into modules for clean, scalable build systems.

Modularizing CMake Code

CMake Language and Fundamentals

Learn more about targets, and how their properties and links are the foundation of modern CMake

Learn to work with target properties - understanding their purpose, setting and updating them, and retrieving them when your build requires it

Target Properties

Learn about target types, and how the `PUBLIC`, `PRIVATE`, and `INTERFACE` keywords control how properties are shared.

Relationships Between Targets

Discover how CMake's `target_link_libraries()` command builds a dependency graph, and how it uses this graph to automatically manage transitive dependencies and link order.

Indirect Relationships and the Dependency Graph

Learn to use abstract target types like `INTERFACE`, `ALIAS`, and `IMPORTED` to model complex project needs, organize build properties, and integrate pre-compiled binaries.

Using `INTERFACE`, `ALIAS`, and `IMPORTED` Libraries

Adding support for user-configurable library types and an initial introduction to target installation.

Using Shared Libraries

Targets and Dependencies

Learn how to manage multiple build configurations within the same project, and how to create scripts that adapt to the environment

Learn how CMake manages different build configurations like Debug and Release, the difference between generator types, and how to apply settings conditionally using modern techniques.

Build Configurations (Debug, Release, etc.)

Learn the tools and patterns needed to write portable CMakeLists.txt files that work seamlessly across platforms and compilers

Cross-Platform Configurations

Learn to write architecture-aware CMake scripts for 32/64-bit systems and Apple's Universal Binaries (Intel/ARM).

Handling Different Architectures

Learn to build for different operating systems and architectures using CMake's cross-compilation support and toolchain files.

Cross-Compilation and Toolchain Files

Platforms and Build Configurations

Learn how to add external libraries to our build, and how to create our own packages for others to use

Learn to find and use pre-installed libraries with `find_package()`, understanding Module vs. Config mode and the power of imported targets

Finding Dependencies using `find_package()`

Learn how to make your libraries consumable by other projects using CMake by turning your build-tree into a distributable install-tree.

Creating a Consumable Package

Learn how to consume a CMake package you've installed, completing the producer-consumer cycle. We'll cover using `find_package()` and how to point CMake to your library's location

Using Installed Packages

Learn how to create self-contained, reproducible builds by fetching dependencies from source using `FetchContent()` and `ExternalProject_Add()`.

Fetching External Dependencies

Creating and Consuming Packages

Integrating the vcpkg and Conan package managers to handle external dependencies

Learn to manage C++ dependencies effortlessly with the vcpkg package manager and its seamless CMake integration using toolchain files and manifests.

Integrating CMake and vcpkg

Learn the day-to-day commands for managing dependencies with vcpkg and how to guarantee reproducible builds using baselines and version overrides

vcpkg Commands and Versioning

Combine vcpkg with CMake's cross-compilation capabilities. Learn to use triplets to target different architectures and chain-load toolchain files

Cross-Compiling with vcpkg

Discover Conan, the binary-first C++ package manager, and learn how to integrate it with CMake using profiles and lockfiles for fast, reproducible builds.

Using Conan with CMake

Learn to cross-compile C++ projects with Conan, using build and host profiles to manage dependencies for different platforms.

Cross-Compilation with Conan

Package Managers

Introducing presets, allowing us to simplify our workflow and share common configurations across our team

Learn the fundamentals of CMake Presets. This lesson introduces `CMakePresets.json` to simplify complex build commands.

CMake Presets

Learn to structure your CMake presets with inheritance and customize them for your local environment using `CMakeUserPresets.json`.

User Presets and Inheritance

Learn to make your CMake presets portable by using environment variables and conditional logic to adapt to different machine configurations.

Environment Variables and Conditional Presets

Learn how to extend the build process beyond simple compilation by integrating external tools and custom commands

Learn how to use generator expressions `$<...>` for build-time conditional logic.

Generator Expressions and Conditional Logic

Learn how to attach commands to specific points in a target's build lifecycle using `add_custom_command(TARGET)` for tasks like post-build file copying.

Integrating Tools with `add_custom_command()`

Learn to integrate code generators like Protobuf into your build process using `add_custom_command()`, creating automated file-level dependencies in CMake.

Generating Files with Protobuf and `add_custom_command()`

Custom Commands

An introduction to automating common workflow chores by creating custom targets

Learn to create standalone, non-code targets using add_custom_target() for utility tasks like code formatting and documentation generation.

Custom Targets and Build Utilities

Using the Clang-Format tool to automatically enforce a consistent coding style, and integrating it into our build using a custom CMake target

Using Clang-Format

An introduction to file sets and the `target_sources()` command, allowing us to manage our header files in a more controlled way

Using File Sets

A step-by-step guide to integrating Doxygen into your CMake build process for automated C++ documentation.

Generating Documentation with Doxygen

Custom Targets

Integrate automated tests into a CMake project using CTest, GoogleTest, and GoogleMock

Learn the fundamentals of automated testing in C++ with CTest. Create your first test suite, register tests with `add_test()`, and run them with the `ctest` command.

Automated Testing and CTest

Learn to refactor manual C++ tests into a professional test suite using the GoogleTest framework, managed by vcpkg and integrated with CTest.

Integrating GoogleTest with CMake

Learn to use a wide range of assertions, write data-driven parameterized tests, and isolate dependencies with Google Mock.

Assertions and Parameterized Tests

Learn how to isolate dependencies that our project uses, and then how to replace those dependencies at test time using Google Mock.

Dependency Injection and Mocking

Learn the standard pattern for testing application logic by refactoring it into a linkable library

Testing Executables

Move beyond individual tests to manage a full test suite. Learn to organize tests, run tests in parallel, filter by labels, and measure our code coverage

Managing a Test Suite

Automated Testing

Using static and dynamic analysis in CMake projects to automatically detect memory bugs, performance issues, and problematic code

Learn to find memory bugs at runtime by integrating AddressSanitizer (ASan) into a CMake project

Using AddressSanitizer (ASan)

Adding benchmarks to our build to measure the performance of our code, and track how it changes over time

Using Google Benchmark

Integrating Clang-Tidy to enforce good practices and find bugs before we even compile

Using Clang-Tidy

Automated Analysis

Automating the entire development lifecycle using Git for souce control, GitHub Actions for cloud builds, and CPack to create distributable packages and installers.

An introduction to Git, the version control system that underpins modern collaborative software development and automated build pipelines.

Source Control with Git

Learn how to automate your build and test process with Continuous Integration (CI) and a build server. This lesson provides a guide to creating a GitHub Actions workflow for a CMake project.

Build Servers and Continuous Integration

Learn to package your C++ projects using CMake's CPack. This lesson covers creating developer ZIP archives and professional Windows MSI installers with components.

Packaging with CPack

Learn to automate the packaging process by integrating CPack with a multi-platform GitHub Actions workflow

Packaging with GitHub Actions

Learn to automate the creation of a professional Windows installer by integrating CPack, the WiX Toolset, and a multi-platform GitHub Actions workflow.

Creating Installers with CPack and GitHub Actions

Learn to automate the release process using a GitHub Actions workflow that builds, packages, and publishes artifacts to a GitHub Release

Deployment with GitHub Releases

Continuous Integration and Packaging

If you have a basic grasp of C++ but find the build process intimidating, this course is for you. We assume you know the language, but not how to manage large projects.

Manage complex, cross-platform builds using industry-standard tools. Create scalable build systems that automate the entire development lifecycle.

This course is a comprehensive deep-dive into the entire C++ build ecosystem, centered around the power and flexibility of modern CMake. We leave no stone unturned.

Start with a foundational understanding of compilers, linkers, static vs. shared libraries, and object files.

The Full Build Pipeline

Learn every aspect of the CMake language, from variables and control flow to functions, modules, and generator expressions.

Complete CMake Language Mastery

Master the modern target-centric paradigm, including properties, usage requirements, and abstract targets.

Advanced Target Management

Explore every method for handling dependencies, from `find_package` and `FetchContent` to vcpkg and Conan, including versioning and cross-compilation.

In-Depth Dependency Management

Integrate a full suite of professional tools for testing (CTest, GoogleTest), analysis (ASan, Clang-Tidy), and packaging (CPack).

Total Workflow Automation

Build a fully automated deployment pipeline that takes your code from a Git push to a published GitHub Release with multi-platform installers.

End-to-End CI/CD and Deployment

What You'll Learn

Become a software engineer with C++.  Starting from the basics, we guide you step by step along the way

Intro to C++ Programming

If you're completely new to programming or want a thorough introduction, consider starting with our free introductory course:

New to Programming?

Managing C++ Projects Using CMake

In this chapter, we saw how `add_custom_target()` allows us to create standalone utility targets for developer-centric tasks like code formatting. This concept of creating named actions is a powerful way to automate your entire development workflow.


One of the most valuable automations you can add to a project is documentation generation. Good documentation is essential for maintainable software, but keeping it up-to-date manually is a chore. The best documentation is the kind that lives right next to the code it describes and can be generated with a single command.


This lesson explores how to integrate **Doxygen** into a CMake project. We'll learn how to install Doxygen, how to write documentation comments, and how to create a `docs` target that fully automates the process.


## What is Doxygen?


Doxygen is a documentation generator. It's a tool that parses your source files and extracts specially formatted comments, along with information about your code's structure (classes, functions, namespaces, etc.), to produce a set of documentation.


The output is highly configurable and can be generated in multiple formats, most commonly HTML, but also LaTeX for high-quality PDFs and man pages for command-line tools.


The core philosophy of Doxygen is that documentation should live with the code. By embedding documentation directly in comments, you make it easier for developers to keep it synchronized with the code it describes. When a function changes, its documentation is right there to be updated.


## Installing Doxygen


Before we can use Doxygen, we need to install it. The process is simple and available for all major platforms from the [official site](https://www.doxygen.nl/download.html).


Doxygen is also available on most package managers:

- Homebrew: `brew install doxygen`.
- Debian/Ubuntu using `apt`: `sudo apt install doxygen`.
- Chocolatey: `choco install doxygen.install`.
- MSYS2 UCRT64 using `pacman`: `pacman -S mingw-w64-ucrt-x86_64-doxygen`

After installation, we can open a new terminal and verify `doxygen` is available by checking its version:


```c++
//<ti>
doxygen --version
```


You should see output indicating the version number, for example, `1.14.0`:


```c++
//<o>
1.14.0
```


### Finding Doxygen using CMake


As with our previous example using `clang-format`, we can ask CMake to find `doxygen` using the `find_program()` command.  To keep things organized, we'll set up Doxygen from a new `cmake/Docs.cmake` file and then `include()` it in our root `CMakeLists.txt` file:


<CodeViewer>


<CodeFile path="cmake/Docs.cmake" defaultOpen status="New">


```c++
#<cmake>
cmake_minimum_required(VERSION 3.23)

find_program(DOXYGEN_EXECUTABLE doxygen)
if (DOXYGEN_EXECUTABLE)
  message(STATUS "Found Doxygen at ${DOXYGEN_EXECUTABLE}")
endif()
```


</CodeFile>


<CodeFile path="CMakeLists.txt" status="Updated">


```c++
#<cmake>
cmake_minimum_required(VERSION 3.23)
project(Greeter)

add_subdirectory(app)
add_subdirectory(greeter)

include(cmake/Docs.cmake)#<h>
```


</CodeFile>


</CodeViewer>


We can test this by running the configure step from our build directory:


```c++
//<ti>
cmake ..
```


```c++
//<o>
...
-- Found Doxygen at D:/msys64/usr/bin/doxygen.exe
...
```


We can use this `DOXYGEN_EXECUTABLE` to interact with Doxygen on the command line in much the same way we used `CLANG_FORMAT_EXE` earlier in the chapter.


```c++
add_custom_target(doxygen_things
  COMMENT "Doing doxygen things..."
  COMMAND ${DOXYGEN_EXECUTABLE} --version
)
```


However, by default, CMake also includes a `FindDoxygen` helper that let's us load Doxygen through a `find_package()` command.  This approach provides us with some additional CMake-specific variables and functions that we'll use later:


<CodeFile path="cmake/Docs.cmake" status="Updated">


```c++
#<cmake>
cmake_minimum_required(VERSION 3.23)

find_package(Doxygen)
if(Doxygen_FOUND)
  message(STATUS "Found Doxygen Version "
    "${DOXYGEN_VERSION} at ${DOXYGEN_EXECUTABLE}")
endif()
```


</CodeFile>


```c++
//<ti>
cmake ..
```


```c++
//<o>
...
-- Found Doxygen Version 1.14.0 at D:/msys64/usr/bin/doxygen.exe
...
```


Note that `DOXYGEN_EXECUTABLE` is technically deprecated when using `find_package(Doxygen)` and may stop working in the future.  The `find_package()` variation instead provides modern CMake targets and functions that we can use to interact with Doxygen.  We're just using `DOXYGEN_EXECUTABLE` in this example to show the parallels between each approach.


## Installing Doxygen using Conan


If we don't want to install Doxygen through our system tools, we can instead use [Conan](https://conan.io/center/recipes/doxygen) if preferred.  However, Doxygen is **not** a runtime dependency of our project in the same way that libraries like `spdlog` and `tabulate` might be.


As such, it should **not** go in the `[requires]` section of our `conanfile.txt`.  Doxygen is a tool that we use as part of the building of our project - not something we ship - so it should instead be placed in a `[tool_requires]` section:


<CodeFile path="conanfile.txt">


```c++
[tool_requires]#<h>
doxygen/1.14.0#<h>

[generators]
CMakeDeps
CMakeToolchain
```


</CodeFile>


We can then run a `conan install` in the normal way.  From the project root:


```c++
//<ti>
conan install . --output-folder=build --build=missing
```


Conan will **not** automatically add the `doxygen` executable to our system path.  Unless we do that manually, we won't have access to some useful utilities that are available through the `doxygen` command-line interface.


However, as long as we provide the generated `conan_toolchain.cmake` file to CMake at the configure step, our `find_program()` and `find_package()` commands will work as normal within our build:


<CodeViewer>


<CodeFile path="CMakeLists.txt">


```c++
#<cmake>
cmake_minimum_required(VERSION 3.23)

project(Greeter)

add_subdirectory(greeter)
add_subdirectory(app)

find_program(DOXYGEN_EXECUTABLE doxygen)
if(DOXYGEN_EXECUTABLE)
  message(STATUS "Doxygen: ${DOXYGEN_EXECUTABLE}")
endif()

find_package(Doxygen)
if(DOXYGEN_FOUND)
  message(STATUS "Doxygen Version: "
    "${DOXYGEN_VERSION}")
endif()
```


</CodeFile>


<CodeFile path="CMakePresets.json" defaultOpen>


```json
{
  "version": 3,
  "configurePresets": [{
    "name": "conan",
    "binaryDir": "${sourceDir}/build",
    "cacheVariables": {
      "CMAKE_TOOLCHAIN_FILE":
        "${sourceDir}/build/conan_toolchain.cmake",
      "CMAKE_BUILD_TYPE": "Release"
    }
  }],
  "buildPresets": [{
    "name": "conan",
    "configurePreset": "conan"
  }]
}
```


</CodeFile>


</CodeViewer>


We can configure this from our project root to ensure everything is working:


```c++
//<ti>
cmake --preset conan
```


```c++
//<o>
...
-- Doxygen: /Users/greg/.conan2/p/b/doxyg4821aef89cf1f/p/bin/doxygen
-- Doxygen Version: 1.14.0
...
```


<Advanced>


### Using `conanbuild` Scripts


After a `conan install`, there will be a `conanbuild` script in our build directory that can give us direct command line access to `doxygen`, and any other tools that Conan installed.


The type of this file and how we use it depends on our system / Conan profile.  For example, in Unix-like environments, it might be a `.sh` file that we can `source`:


```c++
//<ti>
source build/conanbuild.sh
```


This allows us to access the tools that Conan installed for the remainder of the terminal session:


```c++
//<ti>
doxygen --version
```


```c++
//<o>
1.14.0
```


This is particularly useful when we're setting up build servers / continuous integration environments, which we cover later in the course.


</Advanced>


## Documenting Code with Doxygen Syntax


Doxygen recognizes several styles of comments, but the most common for C++ is the Javadoc style. A Doxygen comment block starts with `/**` and ends with `*/`, or uses `///` for single-line comments.


Let's document the public `Greeter.h` header in our `GreeterLib`. We do this by adding our specially formatted comments at the top of the file, and above the function declarations we want to document:


<CodeFile path="greeter/include/greeter/Greeter.h" status="Updated">


```c++
/**
 * @file Greeter.h
 * @brief Declares the public API for the Greeter library.
 *
 * This is the primary file that you should #include if
 * you want to use the library. 
 */
#pragma once
#include <string>

/**
 * @brief Provides a friendly greeting.
 *
 * This function generates a greeting string that can be
 * displayed to the user. It's the core feature of the
 * Greeter library.
 *
 * @return A std::string containing the greeting.
 *
 * @code
 * #include <iostream>
 * #include <greeter/Greeter.h>
 * int main() {
 *   std::cout << get_greeting(); // Prints the greeting
 * }
 * @endcode
 */
std::string get_greeting();
```


</CodeFile>


Let's break down the special Doxygen commands (which start with `@` or `\\`):

- `@file`: This is the simplest way we can signal to Doxygen that this file is part of the public API of our library, so should be included in the documentation it generates
- `@brief`: A short, one-line summary of the file or function's purpose. This is often used in lists and quick-reference sections.  Optionally, the paragraphs that follow provides a more detailed description.
- `@return`: Describes what the function returns.
- `@code` / `@endcode`: A block that will be formatted as a code sample in the final documentation.

This is just a tiny fraction of Doxygen's capabilities. You can document parameters with `@param`, create groups of related functions, add notes with `@note`, and much more.  The [official docs](https://www.doxygen.nl/manual/docblocks.html) list all the possibilities.


For now, this basic documentation of our `get_greeting()` function is enough to demonstrate the process of integrating Doxygen with CMake.


<Pw>


## Integrating with CMake


The `FindDoxygen` helper powering our `find_package(Doxygen)` command provides the convenient `doxygen_add_docs()` function, which wraps all the logic for creating a documentation target. At its simplest, you give it a name for the target and a list of files or directories to scan.


Let's add it to our `Docs.cmake` module. We'll create a target named `docs` and tell it to scan our `app` and `greeter` source directories.


<CodeFile path="cmake/Docs.cmake" status="Updated">


```c++
#<cmake>
cmake_minimum_required(VERSION 3.23)

find_package(Doxygen)
if(Doxygen_FOUND)
  message(STATUS "Found Doxygen Version "
    "${DOXYGEN_VERSION} at ${DOXYGEN_EXECUTABLE}")

  doxygen_add_docs(docs #<h>
    ${PROJECT_SOURCE_DIR}/greeter/include #<h>
    COMMENT "Generating docs with Doxygen..."#<h>
  ) #<h>
endif()
```


</CodeFile>


This single command does several things for us:

1. It creates a custom target named `docs`.
2. It configures Doxygen to scan files in the provided directories for documentation comments.  We're just scanning `/greeter` in this example, but we could add more.
3. If we don't provide a configuration file, it generates a default one on the fly.  We cover configuration files later in the lesson.

## Building and Viewing the Documentation


With our `Docs.cmake` module set up and included in our root `CMakeLists.txt` file, let's configure our project and build our docs.  From our build directory:


```c++
//<ti>
cmake ..
```


Now, we can build our new `docs` target.


```c++
//<ti>
cmake --build . --target docs
```


```c++
//<o>
[build] Generating API documentation with Doxygen...
... (Doxygen's output) ...
```


This will create a `html/` directory inside our `build/` folder. If we open the `index.html` file in a web browser, we'll see our generated documentation, ready to be explored:


<Img file="doxygen-greeter-output-1.png" alt="Screenshot of the Doxygen output" width="693" height="1331" blurHash="L23[-w?wE1Ri%1jYD%a}xuoxRjay" />


This lets anyone using our library browse through our documentation in a clean, organized way.  Our documentation is also a website, so we could easily upload the contents of this `/build/html` directory on the internet for anyone to browse.


## Configuring Doxygen using a `Doxyfile`


Doxygen's behavior is controlled by a configuration file, by default named `Doxyfile`. If `doxygen_add_docs()` can't find this file, it just uses a default configuration it manages internally.


A `Doxyfile` can set hundreds of settings that controls every aspect of the process, from what files Doxygen should scan to what colors should be used in the generated documentation.


You can generate a default `Doxyfile` by running `doxygen -g` in your terminal.


```c++
//<ti>
doxygen -g
```


```c++
//<o>
Configuration file 'Doxyfile' created.
```


This will create a large file that you can copy, paste, and edit as needed.  The file is heavily commented, explaining what each option does.


In CMake projects, we don't usually create the `Doxyfile` directly.  Instead, we ask CMake to generate it as part of the configuration step.


The first step is to create a **template** version of a `Doxyfile`.  We typically call this template `Doxyfile.in`, whick CMake will ingest and modify to create the final `Doxyfile`.  This allows us to control the configuration through CMake, meaning we can inject CMake variables from our build into the `Doxyfile`.


Let's create a `docs` directory in our project root and add our template file to it:


<CodeFile path="docs/Doxyfile.in" status="New">


```plain text
# High Level Settings
PROJECT_NAME     = "@PROJECT_NAME@"
PROJECT_VERSION  = "@PROJECT_VERSION@"
OUTPUT_DIRECTORY = "@CMAKE_CURRENT_BINARY_DIR@/docs"

# Which files should be documented?
INPUT     = "@PROJECT_SOURCE_DIR@/greeter/include" \
            "@PROJECT_SOURCE_DIR@/some-other-lib/include"
RECURSIVE = YES

# Styling
HTML_COLORSTYLE     = TOGGLE
HTML_COLORSTYLE_SAT = 80
SHOW_INCLUDE_FILES  = NO
```


</CodeFile>


In this example, we:

- Provide our project name and version, and where the docs should be generated.  We've moved the output to the `/docs` folder within our `/build` to keep things more organized.
- Provide a list of the folders that Doxygen should document.  The `some-other-lib` example doesn't exist in our case, but is included to show how we can document multiple directories.  The `RECURSIVE` setting asks Doxygen to also explore subdirectories of these inputs.
- Provide some styling adjustments.  The `HTML_COLORSTYLE` being set to `TOGGLE` causes the documentation to show a button to switch between light mode and dark mode.  `HTML_COLORSTYLE_SAT` changes the saturation in a range from 0 (grayscale) to 255 (maximum vibrancy).  `SHOW_INCLUDE_FILES` being set to `NO` hides the list of files that our headers depend on, such as `<string>`.

This is just an example configuration - Doxygen is hugely configurable.  Remember, we can see a full list of options and what they do from the file generated by `doxygen -g` or, alternatively, from the [official docs](https://www.doxygen.nl/manual/config.html).


The key part to note for the CMake integration are the `@VARIABLE@` placeholders. When we process this file with CMake, it will replace these placeholders with the values of the corresponding CMake variables.


## Using `configure_file()`


Let's process our `Doxyfile.in` template to generate a final, configured `Doxyfile`. We do this with the `configure_file()` command.  This is a generic, CMake-provided command for generating **any** type of configuration file from a template, not just doxyfiles.


We provide it with an input template (`Doxyfile.in` in this case) and an output file path. It reads the input, replaces all `@VAR@` and `${VAR}` placeholders with the corresponding CMake variable values, and writes the result to the output file.


```c++
#<cmake>
configure_file(
  "MyTemplateFile.in"
  "MyOutputFile.txt"
)
```


### The `@ONLY` Argument


The fact that `configure_file()` replaces placeholders using both the `@VAR@` and `${VAR}` syntax can be problematic.  Some external tools use `${VAR}` as their own syntax for interpolating variables, and this includes Doxygen's `Doxyfile` format.


Without intervention, CMake's `configure_file()` command would see something like `${DOXYGEN_VAR}` in our template, try to substitute it with a CMake variable called `DOXYGEN_VAR`, find nothing, and replace it with an empty string.  This would break our Doxygen configuration.


Fortunately, `configure_file()` allows us to pass the `@ONLY` argument.  This means it will **only** replace placeholders that use the `@VAR@` syntax, leaving `${VAR}` alone:


```c++
#<cmake>
configure_file(
  "Doxyfile.in"
  "Doxyfile"
  @ONLY#<h>
)
```


### Using `configure_file()` to Generate a `Doxyfile`


Let's use this to create our `Doxyfile`.  We'll stick to the practice of placing generated files in our build directory - `CMAKE_CURRENT_BINARY_DIR` - so our project is easier to keep clean.


We'll also provide this file to `doxygen_add_docs()` using the `CONFIG_FILE` argument, and we can delete our input argument:


<CodeFile path="cmake/Docs.cmake" status="Updated">


```c++
#<cmake>
cmake_minimum_required(VERSION 3.23)

find_package(Doxygen)
if(Doxygen_FOUND)
  message(STATUS "Found Doxygen Version "
    "${DOXYGEN_VERSION} at ${DOXYGEN_EXECUTABLE}")

  configure_file( #<h>
    "${PROJECT_SOURCE_DIR}/docs/Doxyfile.in" #<h>
    "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" #<h>
    @ONLY #<h>
  ) #<h>

  doxygen_add_docs(docs
    # This is now provided in the Doxyfile<d>
    ${PROJECT_SOURCE_DIR}/greeter/include#<d>
    
    CONFIG_FILE "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" #<h>
    COMMENT "Generating docs with Doxygen..."
  )
endif()
```


</CodeFile>


With these changes, we can now rebuild our documentation as before, and see our configuration reflected in the output:


```c++
//<ti>
cmake --build . --target docs
```


<Img file="doxygen-greeter-output-2.png" alt="Screenshot of customized Doxygen output" width="713" height="1093" blurHash="L1Ss8800D%_3_3Rks:t7Ipt6t6s:" />


## Summary


Automating documentation is a common hallmark of creating large projects. By integrating Doxygen with CMake, we can turn a tedious manual task into a simple, repeatable command.


**Doxygen Basics**: Doxygen generates documentation by parsing special comments (`/** ... */`) in your source code.


**CMake Integration**:

1. Use `find_package(Doxygen)` to locate the Doxygen executable.
2. Use `configure_file()` to generate a project-specific `Doxyfile` from your template.
3. Pass the file to the `CONFIG_FILE` argument of `doxygen_add_docs()`.

**Building Docs**: After integrating everything, we can generate up-to-date documentation for your project by running a single command: `cmake --build . --target docs`.


**Configuration as Code**: Doxygen can be configured using a `Doxyfile`.  We can use CMake to generate this by creating a `Doxyfile.in` template, and inject variables into the output with `@VAR@` placeholders.


<Preview>


### Automated Testing and Analysis


Our code is consistently formatted, and our documentation can be generated with a single command. But how do we know our code actually **works**? And more importantly, how do we ensure it **keeps working** as we add new features and refactor existing logic?


In the next chapter, we will answer that question by introducing **automated testing**. We'll start by introducing **CTest**, CMake's built-in testing framework. You'll learn how to write simple C++ tests, use the `enable_testing()` and `add_test()` commands to register them with CMake, and run your entire test suite from the command line with the `ctest` utility.


</Preview>


</Pw>

`find_package` and the CMake Package System

Official Doxygen Website

Special Comment Blocks

`FindDoxygen` Module Documentation

`configure_file()` Command Documentation

How to generate Doxygen documentation using CMake?

Learn how to generate professional C++ documentation automatically. This lesson covers installing and configuring Doxygen, documenting code with Javadoc-style comments, and creating a custom 'docs' target in CMake using find_package() and add_custom_target().

Automating C++ Documentation with CMake and Doxygen

Using `configure_file()` to Generate a `Doxyfile`

Generating Documentation with Doxygen

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Managing C++ Projects Using CMake