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, we've operated under a key assumption: all our source files are written by hand. But what if they're not? In many modern C++ projects, a significant portion of the code isn't written by developers; it's **generated** by other tools.


This lesson introduces the `add_custom_command()` command, CMake's primary mechanism for integrating these external tools into your build process. We'll learn how to use its `OUTPUT` argument to transform a static build into a dynamic one where source code is generated on the fly.


## Case Study: Protocol Buffers (Protobuf)


To make this concrete, we'll use a real-world example.  The applications we write often need to communicate with other programs.  Or, if we were making a chat program or a multiplayer game, it may need to communicate with other instances of our program, being run by a different user.


Solving this is a three step process:

- We **serialize** the data we want to send into a format where it can be transmitted
- We send this data to the program we want to communicate with, usually over some network such as the internet
- That other program deserializes it into a format it can natively understand, such as a C++ object.

**Protocol Buffers**, or Protobuf for short, is Google's language-neutral mechanism for helping with requirements such as these.


The workflow is as follows:

1. You define your data structures (called "messages") in a simple text file with a `.proto` extension.  These describe the type of data you need to send between programs
2. You run the Protobuf compiler, `protoc`.
3. `protoc` reads your `.proto` file and generates the code to help us implement our messaging features.  Protobuf supports a wide range of languages but, for C++, it will use the familiar convention of generating header and source files.

These generated files contain all the boilerplate code for setting, getting, reading, and writing your data, saving you from a mountain of tedious work.


In these cases, the generated code becomes a **dependency**. If we change the definition file, the generated code must be recreated before our project can use it. Manually running the code generator is tedious and error-prone, so this is a perfect opportunity to apply what we've learned in this chapter to automate it using CMake.


## Setting Up the Protobuf Target


Let's integrate Protobuf into our `Greeter` project. We'll create a new, self-contained CMake target called `DataModel` whose job is to manage our Protobuf definitions and the code generated from them.


### Step 1: Install Protobuf


First, we need to set up Protobuf as a dependency.  The [official documentation](https://protobuf.dev/installation/) lists some installation options, but it's also available through both vcpkg and Conan.


We'll use <InlineLessonPromo url="cmake/conan-package-manager" title="Using Conan with CMake" description="Discover Conan, the binary-first C++ package manager, and learn how to integrate it with CMake using profiles and lockfiles for fast, reproducible builds.">Conan</InlineLessonPromo> in our examples.  If you want to follow along using the same approach, a basic `conanfile.txt` and `CMakePresets.json` are below:


<CodeViewer>


<CodeFile path="conanfile.txt" status="Updated" defaultOpen>


```json
[requires]
protobuf/6.30.1

[generators]
CMakeDeps
CMakeToolchain
```


</CodeFile>


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


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


</CodeFile>


</CodeViewer>


### Step 2: Create the `.proto` Definition


Next, we'll create the definition file for our data. We'll create a new `datamodel` directory and, inside it, a `proto` directory to hold our definition. Let's imagine our program needs to communicate information about a person, so we'll define a simple `Person` message type using protobuf's syntax:


<CodeFile path="datamodel/proto/person.proto" status="New">


```protobuf
syntax = "proto3";

message Person {
  string name = 1;
  int32 id = 2;
  string email = 3;
}
```


</CodeFile>


We're mostly focused on CMake in this course and just using protobuf as an example.  However, if you want to learn about protobuf, their [official guide](https://protobuf.dev/programming-guides/proto3/) is a good introduction.


### Step 3: Using Protobuf


Our program will create a message, serialize it to a string, and then send it.  The receiving program will deserialize (or "parse") the message into a format it can use.


In our case, we'll simulate this by having the same program be both the sender and receiver of the message.  In a realistic scenario, they'd be different programs, or different instances of the same program running on different machines.  The serialized message (stored in a `std::string` in this example) would be transmitted between them, usually over a network.


Note that this file currently isn't compilable, as protobuf hasn't yet generated the `person.pb.h` header that defines the `Person` type we're trying to use here:


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


```c++
#include <iostream>
#include <string>
#include "person.pb.h" // This doesn't exist yet //<e>

int main() {
  // Create a message
  Person p1;
  p1.set_name("Jane Doe");
  p1.set_id(1234);
  p1.set_email("jane.doe@example.com");

  // Sender serializes the message
  std::string serialized;
  p1.SerializeToString(&serialized);

  // Send the message
  // ...

  // Receiver deserializes and uses the message
  Person p2;
  p2.ParseFromString(serialized);
  std::cout << "Hello " << p2.name();

  return 0;
}
```


</CodeFile>


### Step 4: Set up the `CMakeLists.txt` for the `DataModel` Library


Finally, let's create the `CMakeLists.txt` for our new `datamodel` component and add it to the root `CMakeLists.txt`. This is where we'll do the heavy lifting but, for now, we'll just make sure it can find the `protobuf` package:


<CodeFile path="datamodel/CMakeLists.txt" status="New" defaultOpen>


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

find_package(protobuf REQUIRED)
```


</CodeFile>


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


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

add_subdirectory(app)
add_subdirectory(datamodel)#<h>
```


</CodeFile>


With this setup, our project should now be able to generate our project.  If you're following along using Conan and the presets provided above, this can be tested by running the following commands from the project root:


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


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


The build step will currently fail because `person.pb.h` doesn't exist:


```javascript
//<ti>
cmake --build --preset conan
```


```javascript
//<oe>
fatal error: person.pb.h: No such file or directory
    3 | #include "person.pb.h"
      |          ^~~~~~~~~~~~~~
compilation terminated.
```


Next, we'll write the CMake command to automatically generate this file as part of our build process.


<Pw>


## Calling `protoc` using a Custom Command


To generate the files containing the source code we need for our `Person` type, we need to invoke the `protoc` compiler.  We'll use CMake to automate this, with the help of `add_custom_command()`.


The `add_custom_command(OUTPUT ...)` signature defines a rule to generate files. It also establishes a dependency in the build graph: if another target needs one of the output files, CMake will ensure that this command runs first to generate it.


Let's build the command piece by piece in `datamodel/CMakeLists.txt`.


### Step 1: Define the Input and Output Files


Let's start by creating variables for the files we're working with.  We already have our input `person.proto` file, which `protoc` will use to generate a `person.pb.h` header and a `person.pb.cc` source file.  We'll create variables to keep track of these file paths:


<CodeFile path="datamodel/CMakeLists.txt">


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

find_package(protobuf REQUIRED)

# Define the path to our input .proto file
set(PROTO_FILE "${CMAKE_CURRENT_SOURCE_DIR}/proto/person.proto")

# Define the paths for the generated output files
set(GENERATED_H "${CMAKE_CURRENT_BINARY_DIR}/person.pb.h")
set(GENERATED_CC "${CMAKE_CURRENT_BINARY_DIR}/person.pb.cc")
```


</CodeFile>


### Step 2: Write the Command


Now we can construct the `add_custom_command()` call.


<CodeFile path="datamodel/CMakeLists.txt">


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

find_package(protobuf REQUIRED)
set(PROTO_FILE "${CMAKE_CURRENT_SOURCE_DIR}/proto/person.proto")
set(GENERATED_H "${CMAKE_CURRENT_BINARY_DIR}/person.pb.h")
set(GENERATED_CC "${CMAKE_CURRENT_BINARY_DIR}/person.pb.cc")

add_custom_command(#<h>
  OUTPUT ${GENERATED_H} ${GENERATED_CC}#<h>
  DEPENDS ${PROTO_FILE}#<h>
  COMMENT "Using protobuf to generate C++ files from person.proto"#<h>
  COMMAND#<h>
    ${Protobuf_PROTOC_EXECUTABLE}#<h>
    --cpp_out=${CMAKE_CURRENT_BINARY_DIR}#<h>
    --proto_path=${CMAKE_CURRENT_SOURCE_DIR}/proto#<h>
    ${PROTO_FILE}#<h>
)#<h>
```


</CodeFile>


Let's break down each argument:


**`OUTPUT`**: This is the most important part. We use this to provide a list of one or more files that this command is expected to create.  We pass the variables storing the paths to the files that will be created by our command.


**`DEPENDS`**: This lists the input files the command depends on. In our case, we're telling CMake that our command depends on the `person.proto` file we created.  In other words, if `person.proto` is modified, the build system will need to re-run this command because any existing output files (`person.pb.h` and `person.pb.cc`) are now stale.


**`COMMENT`**: An optional string that explains what the command is doing.  This may be printed to the console during the build, letting the user know what's happening.


**`COMMAND`**: The actual command to execute, which is `protoc` and its arguments in our case:

- `${Protobuf_PROTOC_EXECUTABLE}`: We use a variable provided by `find_package(protobuf)` to get the path to the `protoc` compiler.
- `--cpp_out`: An argument to `protoc` telling it where to place the generated C++ files. We'll stick to the pattern of placing automatically generated files in our build directory, which makes cleaning things up easier.
- `--proto_path`: An argument to `protoc` telling it where to look for `.proto` files, similar to a C++ include path.
- `${PROTO_FILE}`: The final argument is the input file to process.

## Integrating the Generated Files


We've defined the _rule_ to generate the files, but we haven't told any of our C++ targets to actually _use_ them. This is the final step.


### Step 1: Create the `DataModel` Library


We'll create a library that encapsulates our generated code. This library will be responsible for compiling the generated `.pb.cc` file.


<CodeFile path="datamodel/CMakeLists.txt">


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

find_package(protobuf REQUIRED)
set(PROTO_FILE "${CMAKE_CURRENT_SOURCE_DIR}/proto/person.proto")
set(GENERATED_H "${CMAKE_CURRENT_BINARY_DIR}/person.pb.h")
set(GENERATED_CC "${CMAKE_CURRENT_BINARY_DIR}/person.pb.cc")

add_custom_command(
  OUTPUT ${GENERATED_H} ${GENERATED_CC}
  DEPENDS ${PROTO_FILE}
  COMMENT "Using protobuf to generate C++ files from person.proto"
  COMMAND
    ${Protobuf_PROTOC_EXECUTABLE}
    --cpp_out=${CMAKE_CURRENT_BINARY_DIR}
    --proto_path=${CMAKE_CURRENT_SOURCE_DIR}/proto
    ${PROTO_FILE}
)

add_library(DataModel ${GENERATED_CC})#<h>
```


</CodeFile>


By listing `${GENERATED_CC}` as a source file for `DataModel`, we have created the **file-level dependency**.


CMake now knows: "To build `DataModel`, I need the file `person.pb.cc`.  That file does not currently exist, but I see a custom command that `OUTPUT`s it.  So, I will run that command first."


### Step 2: Set Usage Requirements


Any target that uses our `DataModel` library will need the location of the header files it generates - `person.pb.h` in our case.


This will be same location we passed to the `--cpp_out` argument to `protoc`, which was `${CMAKE_CURRENT_BINARY_DIR}`.  We declare this include directory using `target_include_directories()` as usual:


```c++
target_include_directories(DataModel PUBLIC
  ${CMAKE_CURRENT_BINARY_DIR}
)
```


Consumers of our `DataModel` will also have a dependency on the protobuf library itself, so we need to link against it.  This library is called `protobuf::libprotobuf`, which we can confirm from the documentation or by checking the log output of the `find_package()` command.


Again, we declare this using the standard `target_link_libraries()` command:


```c++
target_link_libraries(DataModel PUBLIC
  protobuf::libprotobuf
)
```


Our completed target looks like this:


<CodeFile path="datamodel/CMakeLists.txt">


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

find_package(protobuf REQUIRED)
set(PROTO_FILE "${CMAKE_CURRENT_SOURCE_DIR}/proto/person.proto")
set(GENERATED_H "${CMAKE_CURRENT_BINARY_DIR}/person.pb.h")
set(GENERATED_CC "${CMAKE_CURRENT_BINARY_DIR}/person.pb.cc")

add_custom_command(
  OUTPUT ${GENERATED_H} ${GENERATED_CC}
  DEPENDS ${PROTO_FILE}
  COMMENT "Using protobuf to generate C++ files from person.proto"
  COMMAND
    ${Protobuf_PROTOC_EXECUTABLE}
    --cpp_out=${CMAKE_CURRENT_BINARY_DIR}
    --proto_path=${CMAKE_CURRENT_SOURCE_DIR}/proto
    ${PROTO_FILE}
)

add_library(DataModel ${GENERATED_CC})

target_include_directories(DataModel PUBLIC#<h>
  ${CMAKE_CURRENT_BINARY_DIR}#<h>
)#<h>

target_link_libraries(DataModel PUBLIC#<h>
  protobuf::libprotobuf#<h>
)#<h>
```


</CodeFile>


### Step 3: Link the App


Now that we have all our protobuf plumbing abstracted away in our `DataModel` target, we just need to update our application to link against it:


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


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

add_executable(GreeterApp src/main.cpp)

target_link_libraries(GreeterApp PRIVATE DataModel)#<h>
```


</CodeFile>


Because we set the include directories and Protobuf library link as `PUBLIC` on `DataModel`, `GreeterApp` inherits them automatically. The `app/CMakeLists.txt` remains clean; it doesn't need to know any of the messy details about code generation. It just consumes the `DataModel` library.


### Step 4: Building and Testing


Now, if we configure and build our project, everything should work seamlessly. If you're following along using Conan and the provided presets, the full build process will look like this from the project root:


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


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


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


We can then run `GreeterApp` or `GreeterApp.exe` to confirm everything is working:


```javascript
//<ti>
./build/app/GreeterApp.exe
```


```javascript
//<o>
Hello Jane Doe
```


## The `protobuf_generate()` Command


This lesson walked through an example of manually using `add_custom_command(OUTPUT)` as it is the generic way of handling all file-generation tasks within builds.


However, some libraries offer convenient helpers that make them easier to integrate into CMake builds.  Protobuf in particular includes the `protobuf_generate()` command that wraps the more verbose `add_custom_command()` invocations in a friendlier interface.


It also accepts our target as an argument, and will automatically provide it with the source files it generates.


A variation of our `datamodel/CMakeLists.txt` that uses this helper might look something like this:


<CodeFile path="datamodel/CMakeLists.txt">


```c++
cmake_minimum_required(VERSION 3.21)

find_package(protobuf REQUIRED)

# Create the target first as protobuf_generate requires it
add_library(DataModel)

# This replaces our add_custom_command() call
protobuf_generate(#<h>
  TARGET DataModel#<h>
  LANGUAGE cpp#<h>
  PROTOS proto/person.proto#<h>
  IMPORT_DIRS ${CMAKE_CURRENT_SOURCE_DIR}/proto#<h>
)#<h>

target_include_directories(DataModel PUBLIC
  ${CMAKE_CURRENT_BINARY_DIR}
)

target_link_libraries(DataModel PUBLIC
  protobuf::libprotobuf
)
```


</CodeFile>


## Summary


The `add_custom_command(OUTPUT ...)` command is the primary way of integrating external tools to generate files within a CMake build.

- **Code Generation:** Boilerplate code can often be generated automatically, which reduces the workload and improves consistency.  Protobuf is a classic example, generating the boilerplate required for communication between programs.
- **File-Level Dependencies:** The `OUTPUT` argument tells CMake what files the command creates, allowing it to build a dependency graph.
- **Integration:** After defining the command, you integrate the generated files into a target just like any other source file using commands like `add_library()` , `add_executable()`, or `target_sources()` (which we cover later in the course).
- **Encapsulation:** Wrapping complexity behind a friendly interface is a good practice.  We can wrap the entire code generation process and its dependencies inside a self-contained library target.

<Preview>


### Custom Targets and Build Utilities


We've learned how to attach a command to an **existing target**. But what about developer utilities that aren't tied to the compilation of any specific library or executable?  For example, how do we create a standalone `format` target to run `clang-format`, or a `docs` target to generate documentation?


In the next lesson, we will introduce `add_custom_target()`. This command lets us create our own "phony" targets that exist solely to run commands, giving us named entry points for all our common development and maintenance tasks.


</Preview>


</Pw>

`add_custom_command()` Documentation

Protocol Buffers Documentation

protobuf port

Deep CMake for Library Authors (CppCon 2019)

How to use a custom command to generate a source file in CMake?

Custom Commands and Targets

Master CMake's add_custom_command(OUTPUT) to integrate code generators. This step-by-step tutorial uses Protocol Buffers (Protobuf) to show you how to generate C++ source files and integrate them into your targets.

CMake Custom Commands Tutorial: Generating Files with Protobuf

Step 4: Set up the `CMakeLists.txt` for the `DataModel` Library

Step 1: Define the Input and Output Files

Generating Files with Protobuf and `add_custom_command()`

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Managing C++ Projects Using CMake

Generating Files with Protobuf and add_custom_command()

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Generating Files with Protobuf and `add_custom_command()`