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

We've spent the last two chapters deep in the trenches of the C++ build process. We've manually wrangled compiler flags, linker paths, and platform-specific library names. We've seen how `Makefiles` can turn into unmaintainable monsters, and how IDE project files lock us into a single vendor's ecosystem.


If you're feeling a bit overwhelmed by the complexity, that's a good sign. It means you understand the problem. Building C++ software, especially at scale, is _**hard**_.


Now, it's time to introduce the solution. This lesson marks our transition from understanding the problem to mastering the tool that solves it. Let's talk about why CMake has become the de facto standard for building C++ projects.


## Build Challenges in Complex Projects


As we saw in the <InlineLessonPromo slug="cmake/build-systems-and-their-limitations">previous lesson</InlineLessonPromo>, simple build automation tools like `make` or IDEs start to break down as a project grows. The core challenges they fail to address can be boiled down to a few key areas.


### Portability: The "Works on My Machine" Nightmare


This is the number one problem. A `Makefile` written for GCC on Linux is useless on Windows. It uses Unix-style paths, relies on shell commands like `rm`, and calls `g++` with flags that `cl.exe` (the MSVC compiler) doesn't understand.


An IDE project is even worse. A Visual Studio solution (`.sln`) is completely alien to an Xcode user on a Mac. To support multiple platforms, you end up maintaining multiple, parallel build scripts. When you add a new source file, you have to remember to add it to the `Makefile`, the `.vcxproj` file, and the `.xcodeproj` file. It's a recipe for disaster.


### Reproducibility and Consistency


How can you guarantee that every developer on your team, plus your automated build server, is building the software in the same way?


Without a single, shared definition of the build process, inconsistencies creep in. One developer might have a slightly different set of compiler flags. Another might link against a different version of a library. This leads to bugs that are impossible to track down because the build is not reproducible.


### Maintainability and Scalability


As a project grows to include dozens of libraries and executables, a single `Makefile` becomes an unreadable, tangled mess of rules and variables. IDE solutions with hundreds of projects are just as bad, with build settings hidden across thousands of lines of verbose XML that nobody wants to edit by hand.


Managing dependencies, setting compiler flags, and defining new build targets becomes a specialized, high-risk task that slows down development for everyone. The build system, which should be a helpful tool, becomes a major source of technical debt.


## How CMake Helps


CMake's brilliance is that it doesn't try to be just another build system. Instead, it's a _**meta-build system**_.


This is the most important concept to understand. **CMake does not compile your code.** It doesn't run the linker. Instead, it _generates the files that do_.


You write a set of simple, high-level, platform-independent text files called `CMakeLists.txt`. These files describe your project: what your executable targets are, what source files they're built from, and what libraries they depend on.


Then, you run CMake and tell it what kind of project you want to generate. This is the "generator" step.


<Img hasTransparency invertible file="cmake-generation.png" alt="Diagram showing the CMake generation process" width="1200" height="308" blurHash="L14LUYj[00D%9Fay-;t700ay~q%M" />


We don't consider these generated files to be part of our project - they're just temporary.  They are generated when required and deleted when they are no longer needed.  It is only the `CMakeLists.txt` file that gets maintained in our project.


The process gives you the best of both worlds:

1. **A Single Source of Truth**: Your `CMakeLists.txt` files are the only place where your project's build logic is defined. They are plain text, easy to read, and live in your version control system right alongside your source code.
2. **Native Tool Performance**: You still get to use the best, most performant build tools for each platform (like `make` or Ninja on Linux, and the highly optimized MSBuild engine in Visual Studio) without having to write their configuration files by hand.

<Pw>


## CMake vs Compiler Commands


The following `gcc` terminal command includes 3 pieces of build configuration:

- The output will be an executable called `my_app`, compiled from a `main.cpp` source file
- It provides an include directory, which the source code might require for some `#include` directive
- It defines a `DEBUG` preprocessor macro, which the source code might be checking for in some `#ifdef` directive

```c++
//<ti>
g++ -c main.cpp -o main.o -I/path/to/headers -DDEBUG
```


CMake provides a high-level, descriptive language. Instead of writing low-level compiler commands, you use abstract commands that express your intent.


The equivalent configuration in a `CMakeLists.txt` file would look like this:


```c++
#<cmake>
add_executable(my_app main.cpp)
target_include_directories(my_app PUBLIC /path/to/headers)
target_compile_definitions(my_app PUBLIC DEBUG)
```


Because these commands are contained within a file (`CMakeLists.txt`) rather than an ad-hoc terminal command, this configuration is also easier to share.  It can be saved and included as a first-class part of your project, just like your source code.


When another developer then downloads your project, their installation of CMake can use this file to generate correct, platform-specific commands in whichever format they prefer.


## CMake vs. Traditional Build Systems


Let's make a direct comparison to see how CMake's approach solves the problems we identified.


### CMake vs. Makefiles


| Feature             | Makefile                                               | CMake                                                               |
| ------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| **Portability**     | **Low**. Tied to a specific shell and compiler.        | **High**. Generates Makefiles, VS solutions, etc., from one script. |
| **Language**        | Low-level, imperative commands.                        | High-level, descriptive targets and properties.                     |
| **Dependencies**    | Manual tracking. Error-prone.                          | Automatic dependency detection is built-in                          |
| **Maintainability** | Becomes very complex and unreadable in large projects. | Modular design with `add_subdirectory()` keeps projects clean.      |


We'll cover CMake's dependency detection mechanisms and modularity later in the course.


In general, a big difference is one of philosophy. A `Makefile` is a script that says _**how**_ to build - it includes things like the specific compiler flags that should be used.


A `CMakeLists.txt` file is a description of _**what**_ to build. CMake handles the "how" for you.


### CMake vs. IDE Projects (e.g., Visual Studio)


| Feature             | IDE Project (`.vcxproj`)                                        | CMake                                                             |
| ------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Portability**     | **None**. Locked into a single IDE and OS.                      | **High**. Generate a project for any supported IDE.               |
| **Version Control** | Poor. XML files are verbose and cause merge conflicts.          | Excellent. `CMakeLists.txt` are clean, human-readable text files. |
| **Automation**      | Difficult. Requires platform-specific tools like `msbuild.exe`. | Trivial. `cmake --build` works everywhere.                        |
| **Source of Truth** | Opaque. Build logic is hidden in GUI property pages.            | Clear. `CMakeLists.txt` is the single, editable source of truth.  |


Using an IDE's native project system is convenient for solo developers on a single platform. But for any collaborative, cross-platform, or automated project, CMake is usually a better choice.


It lets you use your favorite IDE for editing and debugging, while keeping the underlying build definition portable and clean.


Most modern IDEs, including Visual Studio, VS Code, and CLion, now have first-class, integrated support for CMake projects.


<Aside>


### CMake Alternatives


The C++ ecosystem is huge, and many other build systems exist. Some popular alternatives include:

- **Meson**: A newer build system that is often praised for its speed and simpler syntax. It also uses the generator model, often with Ninja as its preferred backend.
- **Bazel**: Google's build system, designed for massive, multi-language monorepos. It is extremely powerful but has a steeper learning curve.
- **xmake**: A Lua-based build utility that aims for ease of use.

While these are all excellent tools, CMake remains the most widely adopted and supported build system in the C++ world, and its lead is increasing over time.


Learning it gives you a skill that applies to a huge number of open-source and commercial projects.


</Aside>


## Summary


We've now seen the chasm between the low-level intricacies of managing projects and the cleaner, more organized approach we'd prefer to use.  By acting as a meta-build system, CMake helps bridge this chasm:

- **It's Portable**: One `CMakeLists.txt` can generate a build system for Windows, Linux, and macOS.
- **It's Maintainable**: Its high-level, descriptive language keeps build scripts clean and readable, even for large projects.
- **It's the Industry Standard**: From tiny open-source libraries to massive AAA game engines, CMake is increasingly becoming the tool of choice.

Now that we understand _why_ CMake is so useful, let's finally start to use it!


<Preview>


### Getting Your Hands Dirty


In the next lesson, we will install CMake on our system and verify our setup. We'll explore the different ways to run CMake - from the command line, through its GUI, and inside an IDE - and configure our environment to ensure everything is working.


</Preview>


</Pw>

Build Systems and Their Limitations

CMake Documentation

CMake

Awesome CMake - A curated list of awesome CMake resources

Professional CMake: A Practical Guide

More Modern CMake - Deniz Bahadir

What is the difference between using a Makefile and CMake to compile the code?

CMake vs. Make: What's the Difference?

Introduction to modern CMake for beginners

Learn why CMake is the industry standard for C++ build automation. This lesson explains how CMake addresses the challenges of portability, maintainability, and reproducibility that plague traditional tools like Makefiles and IDE projects.

Why Use CMake? An Introduction to Modern C++ Build Systems

Portability: The "Works on My Machine" Nightmare

CMake vs. IDE Projects (e.g., Visual Studio)

Why CMake?

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Managing C++ Projects Using CMake