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

The previous lessons in this chapter have focused on **functional correctness**. Our test suite, powered by GoogleTest and managed by CTest, answers the question: "Does my code do what it's supposed to do?"


But we generally want our build systems to automatically detect other problems too.  For example:

- Are there any obvious memory errors and undefined behaviors?
- Does the code run efficiently?
- Is the coding style clean, consistent, and maintainable?

This chapter expands our utility belt with tools that help us implement such checks. We'll survey three categories of automated analysis and learn how to integrate them into our CMake projects:

1. **Dynamic Analysis** with AddressSanitizer to find memory bugs at runtime.
2. **Performance Analysis** with Google Benchmark to measure our code's speed.
3. **Static Analysis** with Clang-Tidy to enforce good practices and find bugs before we even compile.

## Finding Memory Errors with AddressSanitizer (ASan)


**Dynamic analysis** is the process of checking code for errors while it is running. The most powerful tools in this category are the **sanitizers**, which are special modes built into modern compilers like Clang and GCC.


The most famous of these is the **AddressSanitizer (ASan)**. It instruments our code with extra checks to detect a wide range of memory errors the moment they happen, such as:

- Buffer overflows (reading or writing past the end of an array).
- Use-after-free (using a pointer to memory that has already been deallocated).
- Use-after-return (using a pointer to a local variable after its function has returned).

These bugs are notoriously difficult to debug because they often cause crashes or unintended behaviors much later in the program's execution, far from the original error. ASan makes them trivial to find by stopping the program as soon as they happen, and providing a detailed stack trace.


## Integrating ASan with CMake


Enabling ASan involves simply setting a compiler and linker flag: `-fsanitize=address` on GCC/Clang, or `/fsanitize=address` in MSVC.


To improve stack traces when an error is detected, we generally also want to provide the `-fno-omit-frame-pointer` and `-g` arguments for GCC/Clang, or `/Zi` on MSVC.


The best way to manage this is with a dedicated build type and preset.  Let's create a module file to handle this:


<CodeFile path="cmake/Sanitize.cmake" status="New">


```c++
cmake_minimum_required(VERSION 3.23)

set(SANITIZE_CONDITION "$<CONFIG:Sanitize>")

if (MSVC)
  set(
    SANITIZE_FLAGS 
    "$<${SANITIZE_CONDITION}:/fsanitize=address>"
  )
  add_compile_options("$<${SANITIZE_CONDITION}:/Zi>")
else()
  set(SANITIZE_FLAGS
    "$<${SANITIZE_CONDITION}:-fsanitize=address>"
    "$<${SANITIZE_CONDITION}:-fno-omit-frame-pointer>"
    "$<${SANITIZE_CONDITION}:-g>"
  )
endif()

add_compile_options(${SANITIZE_FLAGS})
add_link_options(${SANITIZE_FLAGS})
```


</CodeFile>


And we'll `include()` it in our root `CMakeLists.txt` file:


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


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

include(cmake/Coverage.cmake)
include(cmake/Sanitize.cmake)#<h>

add_subdirectory(app)
add_subdirectory(greeter)

enable_testing()
add_subdirectory(tests)
```


</CodeFile>


Finally, let's add the corresponding presets to `CMakePresets.json`.


<CodeFile path="CMakePresets.json" status="Updated">


```json
{
  "version": 3,
  "configurePresets": [
    // ... other presets
    {
      "name": "sanitize",
      "displayName": "Address Sanitizer (ASan)",
      "inherits": "default",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Sanitize"
      }
    }
  ],
  "buildPresets": [
    // ... other presets
    {
      "name": "sanitize",
      "configurePreset": "sanitize"
    }
  ],
  "testPresets": [
    // ... other presets
    {
      "name": "sanitize",
      "inherits": "default",
      "configurePreset": "sanitize"
    }
  ]
}
```


</CodeFile>


<Pw>


## Seeing ASan in Action


Now, let's introduce a classic memory bug to the start of our `greet()` function in `GreeterLib`. We'll create a buffer of `5` bytes, then try to read index `5` of that buffer - ie, the byte at the 6th position:


<CodeFile path="greeter/src/Greeter.cpp" status="Updated">


```c++
#include <greeter/Greeter.h>
#include <iostream>//<h>

// ...

std::string Greeter::greet() const {
  char buffer[5];
  std::cout << buffer[5];//<w>
  
  // ...
}
```


</CodeFile>


ASan can only detect a memory issue if we actually cause that issue to occur when running our ASan-enabled build.  For this reason, we get the most benefit out ASan when we combine it with a test suite that covers as much of our code as possible.


The test suite executes as many functions and branches of our code as possible, whilst ASan is keeping watch to detect if any of those actions cause memory issues.


First though, let's run our tests against our standard build, without ASan enabled.  As long as our memory issue doesn't cause the program to crash, our test suite will likely pass:


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


```c++
//<ti>
cmake --build --preset default
```


```c++
//<ti>
ctest --preset default
```


```c++
//<o>
...
100% tests passed, 0 tests failed out of 4
...
```


Let's try again, but this time with ASan enabled.  


Note if you're using GCC in a MinGW environment, such as MSYS2 UCRT64, these steps may not work.  We explain why this is and how to address it at the end of this section.


On other environments, we can delete our existing build directory, and then configure, build, and test our project from scratch, but this time using our new `sanitize` preset:


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


```c++
//<ti>
cmake --build --preset sanitize
```


```c++
//<ti>
ctest --preset sanitize
```


This time, the test should fail with a detailed report from ASan.  This will be a huge dump of information containing everything we might need to debug a complex issue.


For our simple program, some of the key output is shown below, where it tells us the type of error that was detected (`stack-buffer-overflow`) and points us to exactly where it happened:


```c++
//<oe>
ERROR: AddressSanitizer: stack-buffer-overflow on address 0x008d920fe905

...

Address 0x008d920fe905 is located in stack of thread T0 at offset 101 in frame
    #0 0x7ff6a39dc73f in Greeter::greet()

  This frame has 2 object(s):
    [32, 56) 'day_str' (line 18)
    [96, 101) 'buffer' (line 25) <== Memory access at offset 101 overflows this variable

...

0% tests passed, 4 tests failed out of 4
```


<Aside>


### ASan on Windows (MSYS2 / MinGW)


At the time of writing, ASan is not supported by GCC in MinGW-w64 environments, including MSYS2 UCRT64.


If you want to follow along, you can use the MSYS64 CLANG64 environment instead of UCRT64.  Both are included with MSYS64 installations.


Each MSYS64 environment is isolated, so you will need to install the required tools on this new environment if you haven't already.


This can be done in the same way we did previously via `pacman`, ensuring we're installing the `clang` variations instead of `ucrt64`.  The following commands install the compiler toolchain, CMake, and the Ninja build system:


```c++
//<ti>
pacman -Syu
```


```c++
//<ti>
pacman -S mingw-w64-clang-x86_64-toolchain \
  mingw-w64-clang-x86_64-cmake \
  mingw-w64-clang-x86_64-ninja
```


The CLANG64 shell uses the Clang compiler rather than GCC.  But, as long as we've kept our build scripts portable, the project should be configurable, buildable, and testable in exactly the same way: 


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


```c++
//<ti>
cmake --build --preset sanitize
```


```c++
//<ti>
ctest --preset sanitize
```


</Aside>


## Configuring ASan Runtime Behavior


AddressSanitizer's default settings find many common memory errors, but some more advanced checks are disabled by default because they can have a performance impact or are specific to certain bug classes. You can enable these checks at runtime to get even more detailed analysis. This is done by setting the `ASAN_OPTIONS` environment variable before running an instrumented executable.


A classic and dangerous C++ bug is a **use-after-return**. This happens when a function returns a pointer to one of its local variables. Once the function returns, its stack frame is destroyed, and the memory that the variable occupied is now free to be reused. The returned pointer is now "dangling," and any attempt to use it results in undefined behavior.


The ASan check for this, `detect_stack_use_after_return`, is disabled by default in many configurations. Let's write a test to demonstrate this bug and see how we can configure ASan to detect it.


### Creating a "Use-After-Return" Bug in a Test


We'll add a new test case to `tests/greeter/test_greeter.cpp`. This test will contain its own helper function that intentionally creates this bug.


<CodeFile path="tests/greeter/test_greeter.cpp" status="Updated">


```c++
#include <gtest/gtest.h>
#include <greeter/Greeter.h>

// ... existing tests

const char* getDanglingPointer() {
  char local_buffer[] = "This is temporary";

  // DANGER: returning pointer to local variable
  return local_buffer; //<w>
}

TEST(
  ASanRuntimeOptionTests,
  FailsToDetectUseAfterReturnByDefault
) {
  const char* dangling_ptr = getDanglingPointer();

  // The memory dangling_ptr points to is no longer valid.
  // Accessing it is undefined behavior.
  char first_char = dangling_ptr[0]; // <w>

  // This assertion might pass by chance if
  // the memory hasn't been overwritten.
  EXPECT_NE(first_char, '\0');
}
```


</CodeFile>


First, let's run this test with our `sanitize` preset and the default ASan options.


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


```c++
//<ti>
cmake --build --preset sanitize
```


```c++
//<ti>
ctest --preset sanitize
```


In most environments, this test will **pass**. The undefined behavior doesn't cause an immediate crash, and since the specific check is disabled, ASan remains silent.


```c++
//<o>
...
100% tests passed, 0 tests failed out of 5
...
```


### Enabling the Check in CMake


Now, let's enable the `detect_stack_use_after_return` check. We'll set the `ASAN_OPTIONS` environment variable.  We can do this in several ways.  One option is to set it system-wide or for our terminal session, using techniques we covered earlier.


We can also apply it when a CMake preset is being used via the `environment` key:


<CodeFile path="CMakePresets.json">


```c++
{
  "version": 3,
  "configurePresets": [/*...*/],
  "buildPresets": [/*...*/],
  "testPresets": [{
    "name": "sanitize",
    "inherits": "default",
    "configurePreset": "sanitize",
    "environment": {//<h>
      "ASAN_OPTIONS": "detect_stack_use_after_return=1"//<h>
    }//<h>
  }]
}
```


</CodeFile>


Alternatively, we can apply it to a set of tests found by a `gtest_discover_tests()` invocation:


<CodeFile path="tests/greeter/CMakeLists.txt" status="Updated">


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

add_executable(GreeterLibTests test_greeter.cpp)

target_link_libraries(GreeterLibTests PRIVATE
  GreeterLib
  GTest::gtest
  GTest::gmock
  GTest::gmock_main
)

gtest_discover_tests(GreeterLibTests PROPERTIES
  LABELS "library"
  ENVIRONMENT #<h>
    "ASAN_OPTIONS=detect_stack_use_after_return=1" #<h>
)
```


</CodeFile>


After setting this environment variable using any of these approaches, we can rebuild and run the tests again:


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


```c++
//<ti>
cmake --build --preset sanitize
```


```c++
//<ti>
ctest --preset sanitize
```


This time, the test should fail. ASan, with the check now enabled, intercepts the invalid memory access and provides a detailed report:


```c++
//<oe>
ERROR: AddressSanitizer: stack-use-after-return on address 0x020481232e20
...
Address 0x020481232e20 is located in ... getDanglingPointer()
...
80% tests passed, 1 tests failed out of 5
```


This is just one example of the many ways you can customize ASan's behavior. For a full list of options and detailed explanations of the errors ASan can find, the [official AddressSanitizer documentation](https://github.com/google/sanitizers/wiki/AddressSanitizer) is an excellent resource.


## Summary


In this lesson, we've seen how to integrate dynamic analysis into our build process to catch a whole class of memory bugs that are often missed by standard testing.

- **Dynamic Analysis**: Sanitizers like ASan find errors by instrumenting your code to perform checks as it runs.
- **AddressSanitizer (ASan)**: The most common sanitizer, it excels at finding memory errors like buffer overflows and use-after-free bugs.
- **CMake Integration**: We enabled ASan by adding the `-fsanitize=address` flag and created a dedicated `Sanitize` build type and preset to manage it.
- **Clear Error Reports**: When ASan detects an error, it immediately terminates the program and provides a detailed stack trace, making bugs easy to locate and fix.

<Preview>


### Benchmarking Performance


We've focused on making our code correct, but how do we make it fast? And how do we ensure it stays fast as the codebase evolves?


In the next lesson, we will move from correctness to performance. We'll introduce **Google Benchmark**, the standard library for C++ micro-benchmarking, and learn how to write and run benchmarks to measure the performance of our code.


</Preview>


</Pw>

AddressSanitizer (ASan)

Sanitize your C++ code - Kostya Serebryany

AddressSanitizer - Clang documentation

Instrumentation Options (for -fsanitize)

AddressSanitizer for Visual Studio

Sanitizers in Qt Creator

What's the proper way to enable AddressSanitizer in CMake that works in Xcode?

A practical guide to using AddressSanitizer (ASan) with CMake to find C++ memory errors like buffer overflows and use-after-free bugs. Learn to set up a dedicated ASan build type, create a CMake preset, and analyze the runtime error reports to improve your code's stability.

How to Use AddressSanitizer (ASan) with CMake for C++ Memory Debugging

Finding Memory Errors with AddressSanitizer (ASan)

Creating a "Use-After-Return" Bug in a Test

Using AddressSanitizer (ASan)

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Managing C++ Projects Using CMake