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

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

Building C++ Programs

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

The Compilation Pipeline

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

Object Files and the Linking Process

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

Static and Shared Libraries

The C++ Build Process

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

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

Organizing a C++ Project

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

Managing Libraries and Dependencies

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

Automated Build Systems and Their Limitations

Project Structure and Dependency Management

Setting up CMake and creating your first project

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

Why CMake?

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

Setting Up a CMake Environment

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

Writing a CMakeLists File

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

Building and Running CMake Projects

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

CMake Project Structure and Subdirectories

Introducing CMake

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

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

CMake Variables and Logging

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

The CMake Cache

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

CMake Commands, Arguments, and Lists

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

CMake Conditionals and Loops

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

Working with the File System

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

Modularizing CMake Code

CMake Language and Fundamentals

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

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

Target Properties

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

Relationships Between Targets

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

Indirect Relationships and the Dependency Graph

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

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

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

Using Shared Libraries

Targets and Dependencies

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

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

Build Configurations (Debug, Release, etc.)

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

Cross-Platform Configurations

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

Handling Different Architectures

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

Cross-Compilation and Toolchain Files

Platforms and Build Configurations

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

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

Finding Dependencies using `find_package()`

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

Creating a Consumable Package

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

Using Installed Packages

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

Fetching External Dependencies

Creating and Consuming Packages

Integrating the vcpkg and Conan package managers to handle external dependencies

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

Integrating CMake and vcpkg

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

vcpkg Commands and Versioning

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

Cross-Compiling with vcpkg

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

Using Conan with CMake

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

Cross-Compilation with Conan

Package Managers

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

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

CMake Presets

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

User Presets and Inheritance

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

Environment Variables and Conditional Presets

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

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

Generator Expressions and Conditional Logic

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

Integrating Tools with `add_custom_command()`

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

Generating Files with Protobuf and `add_custom_command()`

Custom Commands

An introduction to automating common workflow chores by creating custom targets

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

Custom Targets and Build Utilities

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

Using Clang-Format

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

Using File Sets

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

Generating Documentation with Doxygen

Custom Targets

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

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

Automated Testing and CTest

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

Integrating GoogleTest with CMake

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

Assertions and Parameterized Tests

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

Dependency Injection and Mocking

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

Testing Executables

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

Managing a Test Suite

Automated Testing

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

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

Using AddressSanitizer (ASan)

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

Using Google Benchmark

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

Using Clang-Tidy

Automated Analysis

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

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

Source Control with Git

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

Build Servers and Continuous Integration

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

Packaging with CPack

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

Packaging with GitHub Actions

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

Creating Installers with CPack and GitHub Actions

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

Deployment with GitHub Releases

Continuous Integration and Packaging

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

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

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

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

The Full Build Pipeline

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

Complete CMake Language Mastery

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

Advanced Target Management

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

In-Depth Dependency Management

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

Total Workflow Automation

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

End-to-End CI/CD and Deployment

What You'll Learn

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

Intro to C++ Programming

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

New to Programming?

Managing C++ Projects Using CMake

In the previous chapter, we dissected the C++ build process. We followed our code on its journey from human-readable source files to machine-code-filled object files, and finally watched the linker stitch everything together into a runnable program.


Now, we need to zoom out. Before we write a single line of C++ or configure a build system, we need a plan. Where do our files live? How do we keep our source code from becoming a tangled mess?


A well-organized project is a joy to work on: it's easy to navigate, simple to build, and straightforward to scale. A messy project, on the other hand, is a recipe for headaches, bugs, and wasted time.


In this lesson, we'll establish a solid foundation by exploring standard conventions for project layouts. We'll learn where to put source files, header files, libraries, and tests, and how to structure a project that can grow from a single executable into a complex system of interconnected libraries.


## Typical Project Directory Layout


When you start a new project, it's tempting to just throw all your files into one big folder. This works for a program with two or three files, but it breaks down almost immediately. As soon as you add tests, external libraries, or build artifacts, your root directory becomes a chaotic junk drawer.


To bring order to this chaos, we typically converge on a few common-sense conventions for directory structures. While there's no single, universally agreed standard, most well-structured projects look something like this:


```plain text
//<nh>
my_game/
├─ src/
├─ include/
├─ libs/
├─ build/
├─ tests/
└─ docs/
```


Let's break down the purpose of each of these directories.


### Source Files


The `source/` or `src/` directory is the heart of your project. This is where your `.cpp` files live. These files contain the implementation details: the bodies of your functions, the definitions of your class methods, and the core logic of your application.


By keeping all your implementation files in one place, you create a clear separation between _what_ your code does (its interface, defined in headers) and _how_ it does it (its implementation, defined in source files).


### Include Files


If `src/` is the "how", the `include/` directory is the "what". This folder contains the public header files (`.h` or `.hpp`) for your project. These headers define the public API (Application Programming Interface) of your libraries and executables. They contain declarations for classes, functions, and variables that you want other parts of your project -or even external projects - to be able to use.


Separating public headers into an `include/` directory makes your project's interface explicit. Anyone looking at this folder can immediately understand what functionality your project exposes to the outside world.


### External Library Files


Few C++ projects exist in a vacuum. You'll almost certainly use external libraries for everything from graphics (SDL, SFML) and networking (Boost.Asio, cpr) to data serialization (nlohmann/json, Cereal).


The `libs/` or `external/` directory is the conventional place to put this external code. Whether you're including the source code directly or just storing pre-compiled library files (`.a`, `.lib`, `.so`, `.dll`) and their headers, keeping them in a dedicated folder prevents third-party code from getting mixed up with your own.


### Build Output


This is perhaps the most important directory for maintaining a clean project. The `build/` directory is where all the output of your build process should go. This includes:

- Object files (`.o`, `.obj`)
- Library files (`.a`, `.lib`, `.so`, `.dll`)
- Executables
- Build system files (e.g., Makefiles, Visual Studio solutions)

By directing all build artifacts into a separate `build/` directory, you practice what's known as an _out-of-source build_. Your original source tree (`src/`, `include/`, etc.) remains pristine and untouched. If you want to clean your project, you can just delete the `build/` directory and start over.


This separation is a fundamental concept that we will emphasize throughout this course, as it's a cornerstone of modern CMake usage.


### Other Common Directories

- `tests/`: For automated test scripts.  We'll cover automated testing later in the course
- `docs/`: For documentation files, explaining how the project works.
- `assets/` or `data/`: For non-code resources your application needs at runtime, such as images, fonts, configuration files, or 3D models.
- `tools/`: For utility scripts or small programs used during development, but not part of the final product (e.g., a script to format code or generate asset files).

Adopting a structure like this from the very beginning will pay dividends in the long run, making your project vastly more organized and professional.


The project root typically also contains a few important files.  Typically these are files that allow the project to be compiled, such as a `vcxproj` file if you're using Visual Studio, or a `CMakeLists.txt` file if you're using CMake.


<Pw>


## Header and Source File Organization


Now that we have a high-level directory structure, let's zoom in on the relationship between `src/` and `include/`.


### The `.h`/`.cpp` Pair


As a general rule, every `.cpp` file that defines significant functionality should have a corresponding `.h` file.

- The header file (`.h` or `.hpp`) defines the _**interface**_. It's like a contract, telling the world, "I provide a class named `Player` with these public methods."
- The source file (`.cpp`) provides the _**implementation**_. It fulfills the contract, containing the actual code for the `Player` class methods.

For example, a `Player` component in a game would have:

- `include/Player.h`: Contains the `class Player { ... };` definition.
- `src/Player.cpp`: Contains the implementations, like `Player::update() { ... }`.

Any other part of your code that needs to interact with a `Player` will simply `#include "Player.h"`. It doesn't need to know about `Player.cpp` - that's a detail the linker will handle later.


### Public vs. Private Headers


Not all headers are created equal. Some headers define the public-facing API of a library, while others are internal implementation details that should not be used by outside code.


This leads to a common organizational pattern:

- Public headers go in `include/`. These are the headers you intend for consumers of your library to use.
- Private headers stay in `src/`. These headers are only included by the `.cpp` files within the same module. They are not part of the public interface.

Let's refine our `Player` example. Imagine the `Player` class uses a helper class, `AnimationState`, that no one else needs to know about.


The directory structure might look like this:


```plain text
//<nh>
my_game/
├─ include/
│ └─ Player.h
└─ src/
  ├─ Player.cpp
  └─ AnimationState.h
```


In this case, `Player.cpp` would include both headers:


<CodeFile path="src/Player.cpp">


```c++
// Include our own public header
#include "Player.h"

// Include the private helper header
#include "AnimationState.h"

// ... implementation of Player methods ...
```


</CodeFile>


This convention makes your library's public API crystal clear. Anything in `include/` is fair game for users; anything in `src/` is an implementation detail that can be changed without breaking client code.


For this reason, many projects are structured with `public/` and `private/` directories, instead of the `include/` and `src/` pattern we're describing here.


### Include Path Best Practices


How you write your `#include` directives matters. A common practice is to structure your `include` directory to mirror your project's modules or namespaces and to use those paths in your include directives.


For example, if your `Player` class was part of a `Game` namespace, instead of placing the header at `include/Player.h`, you might use `include/Game/Player.h`. Then, a file that includes this header might do so like this:


```c++
#include "Game/Player.h"//<h>

void SomeFunction() {
  Game::Player SomePlayer;
  // ...
}
```


This has two major benefits:

1. It avoids name collisions. What if you use a third-party library that also has a `Player.h`? By namespacing your includes with a project-specific folder, you eliminate ambiguity.
2. It makes dependencies explicit. Seeing `#include "Game/Player.h"` immediately tells the reader that this code depends on the `Game` module of your project.

To make this work, you just need to tell your compiler (or, later, CMake) to add the `include/` directory to its list of search paths.


<Aside>


### Include Directive Syntax


You've likely seen both angle brackets and double quotes used for includes. The general convention is:

- `#include <...>` is for system headers or headers from external libraries that are on the system's standard include path (e.g., `<iostream>`, `<vector>`).
- `#include "..."` is for your own project's headers. The compiler typically searches for these relative to the current file's location first, before checking the system paths.

The Google C++ Style Guide recommends using quotes for all non-system headers, including those from your own project and from third-party libraries within your project tree.


This clearly distinguishes between what's part of the language/system and what's part of your application's ecosystem.


</Aside>


## Managing Multiple Modules or Libraries


The structure we've discussed works great for a single library or executable. But real-world projects are rarely that simple. A typical application might be composed of:

- A core library containing fundamental data structures and logic.
- A physics library.
- A rendering library.
- A main application executable that ties them all together.

Organizing a project like this requires breaking it down into logical modules or components. Each module can be thought of as a mini-project that builds into its own library.


Our directory structure can be extended to handle this. A common approach is to create subdirectories within `src/` and `include/` for each module:


```c++
//<nh>
my_game/
├─ include/
│ ├─ core/
│ │ └─ GameState.h
│ └─ graphics/
│   └─ Renderer.h
└─ src/
  ├─ core/
  │ ├─ GameState.cpp
  │ └─ private_core_helper.h
  └─ graphics/
    └─ Renderer.cpp
```


Or, alternatively, to create subdirectories within the root project for each module:


```c++
//<nh>
my_game/
├─ core/
│ ├─ include/
│ │ └─ GameState.h
│ └─ src/
│   ├─ GameState.cpp
│   └─ private_core_helper.h
└─ graphics/
  ├─ include/
  │ └─ Renderer.h
  └─ src/
    └─ Renderer.cpp
```


Either of these modular approaches has a few benefits:

- Separation of Concerns: Each module has a single, well-defined responsibility. The `core` team doesn't need to know the details of how the `graphics` team implements rendering.
- Faster Recompilation: If you only change a file in the `graphics` library, you only need to recompile that library and then re-link the final application. You don't need to recompile the `core` library.
- Reusability: You could easily take the `graphics` library from this project and reuse it in a different game.

This is the physical file layout that modern CMake is designed to work with. In the upcoming chapters, you will learn the CMake commands like `add_library()`, `add_executable()`, and `target_link_libraries()` that map directly onto this clean, modular directory structure.


## Summary


Before diving into a build system, establishing a sane project structure is important. It's the architecture of your codebase at the filesystem level, and getting it right makes everything that follows - compiling, linking, testing, and scaling - much easier.

- Use a Standard Layout: Start with a conventional directory structure (`src`, `include`, `build`, `tests`, `libs`). This separation keeps your project clean and understandable.
- Separate Interface from Implementation: Use `include/` for public headers that define your project's API and `src/` for the `.cpp` files and private headers that contain the implementation details.
- Organize for Scale: For larger projects, break your code into logical modules or libraries. Mirror this modular structure in your directories (e.g., `src/core`, `src/graphics`). This promotes separation of concerns and improves build times.
- Embrace Out-of-Source Builds: Always keep your build artifacts separate from your source code by using a dedicated `build/` directory.

With a well-organized project structure in place, we are now ready to start thinking about how to manage the code we _didn't_ write. In the next lesson, we'll tackle the challenges of managing third-party libraries and external dependencies.


</Pw>

Header Files

The Pitchfork Layout (PFL)

Best Practices for Structuring C++ Projects

Google C++ Style Guide

Back to basics: How to organize your C/C++ project

Large-Scale C++ Software Design

Directory structure for a C++ library

Canonical Project Structure

Making and Working with Libraries in C++

Discover the best practices for organizing C++ projects. This lesson covers typical directory layouts like src/ and include/, header file organization, and how to structure a project with multiple libraries and executables, setting you up for success with CMake.

Organizing a C++ Project

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Managing C++ Projects Using CMake