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

So far, our build process has been focused entirely on one thing: compiling C++ code. But a real-world development workflow involves much more. We often need to run external tools, copy files, or execute scripts as part of the build. Some common examples include:

- Copying a final executable to a specific deployment directory.
- Running a script to sign a binary after it has been built.
- Generating a checksum for a release artifact.

This lesson introduces the `add_custom_command()` command with its `TARGET` signature. This is CMake's mechanism for attaching arbitrary actions to specific moments in a target's build lifecycle, allowing you to integrate any external tool or script into your build process.


## Using the `TARGET` Signature of `add_custom_command()`


We've previously seen how the `OUTPUT` signature of `add_custom_command()` is used to generate source files. The `TARGET` signature serves a different purpose: it attaches a command to the lifecycle of an _existing_ target. It doesn't create new files that other targets depend on; it simply runs a command at a specified time.


The basic syntax is:


```c++
#<cmake>
add_custom_command(TARGET <name> <timing>
  COMMAND ...
  COMMENT "..."
)
```

- The `<name>` is the name of an existing target, like our `GreeterApp`.
- The `<timing>` keyword lets us specify exactly when our command should run within the build process of our target.  We'll walk through the available timings in the next section.
- The `COMMAND` keyword lets us specify the action we want to take
- The `COMMENT` keyword lets us output an optional message to our build log when the command is executed

### The Timing Hooks


There are three primary timings we can use:

- `PRE_BUILD`: The command runs **before** any other build rule for the target is executed. This is useful for setup tasks, like generating files that the compiler will need.  We walk through a practical example of this in the next lesson.
- `PRE_LINK`: The command runs **after** all source files for the target have been compiled into object files, but **before** the final link step that creates the executable or library. This is a more niche option, useful for tasks that need to process object files.
- `POST_BUILD`: This is the most common and useful timing. The command runs **after** the target has been successfully built. It's perfect for post-processing tasks like copying the final binary, running a code signing tool, or packaging assets.

Let's see these timings in action. Our command will use the basic `echo` program available on almost all platforms to log out a message.  We'll run `echo` on each phase of our `GreeterApp` build in `app/CMakeLists.txt`:


<CodeViewer>


<CodeFile path="CMakeLists.txt">


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

add_subdirectory(app)
```


</CodeFile>


<CodeFile path="app/CMakeLists.txt" defaultOpen>


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

add_executable(GreeterApp src/main.cpp)

# Add custom commands for each build phase
add_custom_command(TARGET GreeterApp PRE_BUILD #<h>
  COMMAND echo "PRE_BUILD: GreeterApp is about to be built" #<h>
) #<h>

add_custom_command(TARGET GreeterApp PRE_LINK #<h>
  COMMAND echo "PRE_LINK: Sources compiled, about to link" #<h>
) #<h>

add_custom_command(TARGET GreeterApp POST_BUILD #<h>
  COMMAND echo "POST_BUILD: GreeterApp has been built successfully" #<h>
) #<h>
```


</CodeFile>


<CodeFile path="app/src/main.cpp">


```c++
#include <iostream>

int main() {
  std::cout << "Hello World";
  return 0;
}
```


</CodeFile>


</CodeViewer>


Let's test our changes.  Note that these commands will only be executed if `GreeterApp` needs to be built.  If it already exists in our build directory and hasn't changed, it may not be recompiled, meaning our commands will not be executed.


To be sure our program gets built, we can run the build step from a clean build directory.


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


The build log should show the order of operations, with our `echo` output documenting each step:


```c++
//<o>
PRE_BUILD: GreeterApp is about to be built
PRE_LINK: Sources compiled, about to link
POST_BUILD: GreeterApp has been built successfully
```


<Pw>


## Portable Commands


The `COMMAND` argument can run any executable program that is installed on our machine, and accessible from the command line.


However, quite often, the commands we need will be basic, built-in options that are included with most platforms.  `echo` is an example of this, but copying files using `cp` is another common requirement of our scripts.


However, there is a portability problem here.  `cp` exists on Linux and macOS, but Windows' equivalent is called `copy`.  Commands that exist on multiple platforms may also work slightly differently, perhaps requiring different arguments.


We already know a few ways to solve this - the most obvious being something like an `if(WIN32)` check, but CMake provides a more elegant solution.  The `cmake` executable bundles a suite of commands that are commonly needed by build scripts, including portable implementations of things like `echo` and `cp`/`copy`.


Rewriting one of our `echo` examples to use the version of `echo` implemented by `cmake` would look like this:


```c++
#<cmake>
add_custom_command(TARGET GreeterApp POST_BUILD
  COMMAND ${CMAKE_COMMAND} -E echo#<h>
  "POST_BUILD: GreeterApp has been built successfully."
)
```


`${CMAKE_COMMAND}` is a variable that holds the absolute path to the `cmake` executable itself.


The `-E` flag (for "execute") tells CMake not to start a build, but to instead run one of its own built-in, cross-platform utility commands.


You can get a full list of available commands by running `cmake -E help`, but some of the most useful are:

- `copy`: Copies files.
- `make_directory`: Creates a directory.
- `copy_directory`: Copies entire directories.
- `copy_directory_if_different`: Copies only the content that has changed from one directory to another
- `rename`: Renames a file or directory.
- `remove`: Deletes files.

By using `${CMAKE_COMMAND} -E <command>` instead of a native shell command, we ensure our custom commands will work on any platform.


## Practical Example: Post-Build File Copying


Let's implement a classic and highly useful scenario: automatically copying our final executable to some other directory after a successful build. This is a common requirement for gathering all the necessary artifacts for testing or packaging.


We'll add this logic to `app/CMakeLists.txt`.  First, let's create a variable to store our destination, and use a `file()` command to ensure it exists:


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


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

add_executable(GreeterApp src/main.cpp)

# Define the destination directory and ensure it exists
set(DEPLOY_DIR "${PROJECT_SOURCE_DIR}/deploy") #<h>
file(MAKE_DIRECTORY ${DEPLOY_DIR}) #<h>
```


</CodeFile>


Next, we'll add our custom command.  The `cmake -E` mode includes a `copy` command that we can use for this.  Remember, we can get the output of a target using the `<TARGET_FILE:...>` generator expression:


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


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

add_executable(GreeterApp src/main.cpp)

set(DEPLOY_DIR "${PROJECT_SOURCE_DIR}/deploy")
file(MAKE_DIRECTORY ${DEPLOY_DIR})

add_custom_command(TARGET GreeterApp POST_BUILD #<h>
  COMMENT "Copying executable to ${DEPLOY_DIR}" #<h>
  COMMAND ${CMAKE_COMMAND} -E copy #<h>
    $<TARGET_FILE:GreeterApp> #<h>
    ${DEPLOY_DIR} #<h>
) #<h>
```


</CodeFile>


Let's review the key components of this script:

1. We create a variable `DEPLOY_DIR` to hold our destination path. This avoids hardcoding the path multiple times and makes the script easier to read and modify. We use `file(MAKE_DIRECTORY)` to ensure this directory exists before we try to copy into it.
2. We use a `POST_BUILD` command because we want to act on the final, successfully built executable.
3. We add a `COMMENT` to explain what this command is doing.  This comment may also get output into the build log
4. To copy a file, we use the portable `${CMAKE_COMMAND} -E copy`.
5. We use the `$<TARGET_FILE:GreeterApp>` generator expression. This is the **only** reliable way to get the path to the final executable. It correctly resolves to `GreeterApp.exe` on Windows and `GreeterApp` on Linux, and it works regardless of the build configuration or generator.
6. We provide our `DEPLOY_DIR` as the destination directory we want our output copied to.

Now, the next time we build our executable, it will be copied to the `/deploy` directory in our project root.


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


If you look in your project's root, you'll find a new `deploy/` directory containing your `GreeterApp` executable.  You may also see our `COMMENT` output to the build log:


```c++
//<o>
Linking CXX executable GreeterApp
Copying executable to D:/Projects/cmake/deploy
```


Remember, running a build may not actually build our executable if it is already in our `/build` folder and our build system thinks it is up-to-date.  If our commands aren't working, try deleting the existing executable (or the entire build directory) first.


On some environments, the `COMMENT` may not show by default unless we increase the output verbosity.  If it is important that the message is visible, we can use the `echo`  technique from before.  We can pass multiple `COMMAND` arguments like this:


```c++
#<cmake>
add_custom_command(TARGET GreeterApp POST_BUILD
  COMMAND ${CMAKE_COMMAND} -E echo #<h>
    "Copying executable to ${DEPLOY_DIR}" #<h>
  COMMAND ${CMAKE_COMMAND} -E copy
    $<TARGET_FILE:GreeterApp>
    ${DEPLOY_DIR}
)
```


### Comparing `install()` vs. `POST_BUILD` Copy


For more complex deployment and packaging scenarios, using the `install()` workflow we covered in <InlineLessonPromo url="cmake/creating-a-consumable-package" title="Creating a Consumable Package" description="Learn how to make your libraries consumable by other projects using CMake by turning your build-tree into a distributable install-tree.">an earlier lesson</InlineLessonPromo> is generally recommended. It provides fine-grained control over the entire process.  It also makes our program easier to package with CPack, which we'll cover later in the course.


However, for simple projects, or for simple tasks within a larger project, a `POST_BUILD` custom command is easier, more direct, and perfectly appropriate.


## Understanding the Limitations


There's an important aspect of `add_custom_command(TARGET ...)` that often trips up beginners. If we run our build again, without changing anything, our commands may not be executed.


This is because a custom command attached to a target is considered part of that target's dependency graph. The build system is smart; it sees that `GreeterApp` is already up-to-date (its source files haven't changed), so it doesn't rebuild it. And if the target isn't rebuilt, its associated pre- and post-build commands are not run.


This is usually the desired behavior. You don't want to re-copy a file every single time you build if nothing has changed.


But what if you have a task that you **always** want to be able to run on demand, regardless of any changes? That's the job of a **custom target**, which we'll cover in the next chapter.


## Summary


The `add_custom_command(TARGET ...)` command lets us integrate external scripts and tools into our build process, attaching them to the lifecycle of your existing targets.

- **Three Lifecycle Hooks**: You can run commands at `PRE_BUILD`, `PRE_LINK`, or `POST_BUILD` stages. `POST_BUILD` is the most common.
- **Portability**: The `${CMAKE_COMMAND} -E <command>` approach provides portable implementations of common command line tasks, such as working with the file system.
- **Use Generator Expressions**: Use `$<TARGET_FILE:TargetName>` to reliably get the path to a target's output file.
- **It Only Runs When the Target Rebuilds**: A custom command attached to a target is part of that target's build. If the target is up-to-date, the command will not be executed.

<Preview>


### Generating Files with Protobuf


In the next lesson, we'll walk through a larger practical example of adding a custom command to our build.


We'll integrate **Protocol Buffers**, or Protobuf for short. It's Google's language-neutral mechanism for sharing data across different applications.


To help with this, it automatically generates C++ classes for serializing and deserializing this data.  The generation of this source code - `.cpp` and `.h` files - needs to be automated and integrated into our build process.


This makes it a perfect candidate to be used with the `add_custom_command()` techniques we learned here.


</Preview>


</Pw>

`add_custom_command()` Documentation

cmake(1) Manual - Command-Line Tool

Why does CMake make a distinction between a "target" and a "command"?

Master `add_custom_command(TARGET)` in CMake to automate build steps. This tutorial covers `PRE_BUILD` and `POST_BUILD` events, portable commands with `cmake -E`, and practical examples like copying binaries after compilation.

CMake Custom Commands: Attaching Actions to Build Targets

Using the `TARGET` Signature of `add_custom_command()`

Practical Example: Post-Build File Copying

Comparing `install()` vs. `POST_BUILD` Copy

Integrating Tools with `add_custom_command()`

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Managing C++ Projects Using CMake

Integrating Tools with add_custom_command()

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Integrating Tools with `add_custom_command()`