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 last lesson, we saw how C++ source code is transformed into machine code. The compiler takes each `.cpp` file, preprocesses it into a translation unit, and compiles it into an **object file**, typically with a `.o` extension on Unix, and `.obj` on Windows.


We now have a collection of these object files, each an island of compiled code. An object file for `main.cpp` might contain a call to a function like `calculateScore()`, but it has no idea where the actual machine code for `calculateScore()` lives. The compiler just left a note saying, "I need the address of `calculateScore()`."


This is where the _**linker**_ comes in. The linker is the final piece of the puzzle in the C++ build process. It's the master assembler that takes all our separate, compiled object files and stitches them together to create a single, cohesive executable program.


<Img hasTransparency invertible file="cmake-linking.png" alt="Diagram showing the C++ linking process" width="1200" height="841" blurHash="L12=$Exu00ayRjayoffQ00of~qj[" />


In this lesson, we'll learn about this linking process. We'll explore the linker's primary job of resolving symbols, see how it combines object files into an executable, and, most importantly, learn to diagnose and fix the linker errors that every C++ developer eventually faces.


Note that this lesson is entirely theoretical and relatively advanced.  Understanding it is not required to follow along with the rest of the course, so feel free to skip ahead if this is not interesting or doesn't make sense.


## The Linker's Role and Symbol Resolution


After the compiler has done its job on each source file, we're left with a set of object files. Each object file is a container of machine code, but it's incomplete. It knows about the functions and variables it defines, but it only has placeholders for the ones it uses from other files.


The linker's job is to resolve these placeholders and merge everything into a final, runnable program.


It accomplishes this through two main tasks: _**symbol resolution**_ and _**relocation**_.


### Symbols and Symbol Tables


In the context of linking, a **symbol** is simply a name that refers to a function or a global variable. When the compiler processes `main.cpp`, it generates a **symbol table** for the resulting `main.o` object file. This table lists all the symbols the object file is aware of, categorized in two ways:

1. **Defined Symbols**: These are the functions and global variables that are implemented _within this object file_. These symbols are "exported" and made available for other object files to use. For example, if `math.cpp` contains the definition of `int add(int, int)`, then `add` is a defined symbol in `math.o`.
2. **Undefined Symbols (or External References)**: These are symbols that are used in this object file but are defined elsewhere.  The object file essentially says, "I need to call a function named `add`, but I don't know where it is. Please find it for me."

### The Resolution Process


Symbol resolution is the process where the linker connects the dots. It iterates through all the object files you give it and builds a global map of all defined symbols. Then, for every undefined symbol in each object file, it searches this global map to find a matching defined symbol.


Let's imagine a simple project with two files:


<CodeViewer>


<CodeFile path="math.cpp">


```c++
// This file defines the 'add' function.
int add(int a, int b) {
  return a + b;
}
```


</CodeFile>


<CodeFile path="main.cpp">


```c++
#include <iostream>

// We need to declare 'add' so the
// compiler knows about it.
int add(int a, int b);

int main() {
  std::cout << "3 + 4 = " << add(3, 4);
  return 0;
}
```


</CodeFile>


</CodeViewer>


When we compile these, we get `math.o` and `main.o`.

- The symbol table for `math.o` says: "I _**define**_ a symbol named `add`."
- The symbol table for `main.o` says: "I _**use**_ a symbol named `add`, but it's undefined here."

When we link them, the linker sees the undefined reference to `add` in `main.o`, finds the definition of `add` in `math.o`, and connects them.


<Img hasTransparency invertible file="cmake-symbol-resolution.png" alt="Diagram showing linker symbol resolution" width="1200" height="556" blurHash="L13l5OM{00-;RjofofRj00%M~qIU" />


Once the linker knows the final memory address for the `add` function, it performs **relocation**. It goes back to the machine code in `main.o` and replaces the placeholder in the `call` instruction with the actual memory address of `add`. This "patching" process ensures that when the program runs, the function call jumps to the correct location.


<Pw>


## Static Linking - Combining Objects into an Executable


The process we've been describing is known as **static linking**. It's the most straightforward way to build a program.


In static linking, the linker takes all the input object files and copies their machine code and data directly into the final executable file. The result is a single, self-contained program that includes all the necessary code from your project.


When you run a command like `g++ main.cpp math.cpp -o my_app`, the `g++` driver first compiles `main.cpp` and `math.cpp` into `main.o` and `math.o` behind the scenes. Then, it invokes the linker (`ld` on Linux) with these object files.


The linker performs its magic:

1. It combines the code sections (often called `.text`) from all object files into a single code section in the executable.
2. It combines the data sections (`.data`, `.rodata`) similarly.
3. It resolves all symbols and performs relocations as described above.
4. It adds some essential **runtime startup code**. This is a small piece of code provided by the C++ runtime library that runs _before_ your `main()` function. It sets up the stack, initializes global variables, and prepares the command-line arguments - `argc` and `argv` - before finally calling your `main()` function.

The final output is an executable file that the operating system can load into memory and run. Because all the necessary code from your object files is copied into it, it has no external dependencies on them at runtime.


This self-contained nature is the hallmark of static linking. We'll contrast this with dynamic linking in the next lesson.


## Undefined Reference / Unresolved External Symbol


Since the linker works across your entire project, it's the first tool to spot inconsistencies between different source files. Compile-time errors happen within a single translation unit, but _**linker errors**_ happen when the pieces don't fit together.


Undefined references and unresolved external symbols are the most frequent linker error, and it means exactly what it says: you used a symbol, but the linker couldn't find a definition for it anywhere.


The error message will look something like this:


```c++
//<oe>
main.o: In function `main':
main.cpp:(.text+0x15): undefined reference to `add(int, int)'
collect2: error: ld returned 1 exit status
```


On Windows with MSVC, it's "LNK2019: unresolved external symbol".


This error occurs when the linker can't find the implementation for a function or variable you've used. Here are the usual suspects:


### You Forgot to Define a Function


You declared it in a header file, used it in `main.cpp`, but never wrote the function body anywhere.


<CodeFile path="math.h">


```c++
#pragma once

int add(int a, int b); // Declaration only
// No definition! //<e>
```


</CodeFile>


### You Forgot to Link a Source File


The function is defined in `math.cpp`, but you only told the compiler to build `main.cpp`:


```c++
//<ti>
g++ main.cpp -o my_app
```


We need to ensure we provide all the required files:


```c++
//<ti>
g++ main.cpp math.cpp -o my_app
```


### A Name Mismatch


Another common reason for unresolved external symbols is that you might have a subtle difference between the declaration and the definition.


For example, if one is `const` and the other isn't, the compiler "mangles" their names into different symbols. The linker sees them as two completely different functions.


<CodeFile path="math.h">


```c++
#pragma once

// Declaration
int multiply(int a, int b);
```


</CodeFile>


<CodeFile path="math.cpp">


```c++
// Definition has a different signature
int multiply(const int a, int b) { //<e>
  return a * b;
}
```


</CodeFile>


To the linker, `multiply(int, int)` is a different symbol than `multiply(const int, int)`. The call in `main.cpp` will be looking for the first one, but only the second one is defined.


## Multiple Definition / Symbol Redefined


The second most common linker error is the opposite problem: the linker found _**more than one**_ definition for the same symbol. This violates a fundamental principle of C++.


<Definition>


### The One Definition Rule (ODR)


The One Definition Rule (ODR) is a core concept in C++. In simple terms, it states that any variable or non-inline function must have _**exactly one definition**_ in the entire program.


You can declare it as many times as you want - often by including the same header in multiple source files - but there can only be one implementation.


</Definition>


A "multiple definition" error usually means you've violated the ODR. The most common cause is defining a function or a global variable in a header file.


### Why do I get a Multiple Definition Error?


When you `#include` a header, its contents are textually pasted into the source file. If that header contains a function definition, every `.cpp` file that includes it will get its own copy of that function's machine code.


<CodeFile path="util.h" status="New">


```c++
#pragma once

// BAD: Function defined in a header file //<w>
int getID() { //<w>
  return 42;
}
```


</CodeFile>


Now imagine `main.cpp` and `player.cpp` both include `util.h`.

- When `main.cpp` is compiled, `main.o` gets a definition of `getID()`.
- When `player.cpp` is compiled, `player.o` also gets a definition of `getID()`.

When the linker tries to combine `main.o` and `player.o`, it sees two different definitions for `getID()` and complains:


```c++
//<oe>
player.o: In function `getID()':
player.cpp:(.text+0x0): multiple definition of `getID()'
main.o:main.cpp:(.text+0x0): first defined here
ld: 1 duplicate symbol for architecture x86_64
```


The fix is to follow the standard C++ practice:

- **Declare** in the header file (`.h`).
- **Define** in a corresponding source file (`.cpp`).

<CodeViewer>


<CodeFile path="util.h" status="Updated">


```c++
#pragma once

// GOOD: Declaration in the header
int getID(); //<h>
```


</CodeFile>


<CodeFile path="util.cpp" status="New">


```c++
#include "util.h"

// GOOD: Definition in one source file
int getID() { //<h>
  return 42;
}
```


</CodeFile>


</CodeViewer>


Now, only `util.o` will contain the definition for `getID()`. Other object files will have an undefined reference, which the linker will happily resolve to the single definition in `util.o`.


For more on how linkage works with `inline`, `static`, and `extern`, we have a dedicated lesson:


<LessonPromo url="pro-cpp/internal-external-linkage" title="Internal and External Linkage" description="A deeper look at the C++ linker and how it interacts with our variables and functions.  We also cover how we can change those interactions, using the `extern` and `inline` keywords" />


## Handling Libraries During Linking


So far, we've only linked object files that we compiled from our own project's source code. But what about external code, like the C++ Standard Library or a third-party library like SDL or Boost?


We don't want to recompile these libraries from source every time we build our project. Instead, we link against their pre-compiled object files, which are conveniently bundled into **libraries**.


A library is just an archive of object files. When linking, you can tell the linker to look inside these libraries to find definitions for any symbols it can't find in your own object files.


The two main types of libraries are **static** and **dynamic**. We'll focus on the static linking process here and explore the differences in the next lesson.


### Static Libraries - `.a` and `.lib`


A **static library** - usually with a `.a` extension on Unix or `.lib` on Windows - is an archive of object files. Think of it as a `.zip` file for `.o` files.


When you link your program against a static library, the linker doesn't just dump the entire library into your executable. Instead, it intelligently searches the library only for the object files that provide definitions for your program's unresolved symbols.


For example, if you use a function from a large math library, the linker will find the specific object file within the library that contains that function and copy _**only that object file's code**_ into your executable. The rest of the library is ignored.


The final executable is still self-contained. The necessary code from the library has been statically linked - copied into your program - just as if you had compiled it from source yourself.


We'll cover this in more detail in the next lesson but, to use a static library, you typically need to tell the linker two things:

- **Library Path**: The directory where the linker can find the library file.
- **Library Name**: The name of the library to link.

When we're using many libraries, managing these paths and names manually is tedious and error-prone, especially for cross-platform projects. This is one of the key problems that CMake is designed to solve.


## Summary


In this lesson, we completed our journey from source code to a runnable program by exploring the final step: linking.

- **The Linker's Role**: The linker is a program that takes one or more object files and libraries, resolves symbol references between them, and combines them into a single executable.
- **Symbol Resolution**: It builds a map of all defined symbols (functions and global variables) from the input files and uses it to fill in the placeholders (undefined symbols) in each object file.
- **Static Linking**: This process copies the required machine code from your project's object files and any static libraries directly into the final executable, creating a self-contained program.
- **Common Linker Errors**: We learned that "undefined reference" errors mean a definition was missing, while "multiple definition" errors mean a symbol was defined more than once, violating the One Definition Rule (ODR).
- **Libraries**: Libraries are archives of pre-compiled object files. The linker can search them to find definitions for symbols not provided by your own code.

<Preview>


### Static vs. Dynamic Libraries


We've focused on static linking, where library code is copied into your executable at build time. But there's another, more common approach: **dynamic linking**.


In the next lesson, we'll focus on dynamic and shared libraries, which can be identified by the `.so` extension on Linux, and `.dll` on Windows.


We'll see how they differ from static libraries, how they are loaded at runtime instead of build time, and discuss the trade-offs between the two approaches in terms of executable size, memory usage, and deployment complexity.


</Preview>


</Pw>

Added note that this lesson is safe to skip

Preprocessor Directives and the Build Process

Header Files

Internal and External Linkage

Linker (computing)

Linker Tools Errors and Warnings

Linkers (Series)

Linkers, part 1: A brief survey of the landscape

One Definition Rule

How does a C++ linker resolve symbols?

Static, Shared Dynamic and Loadable Linux Libraries

{CPP}A deep dive into the C++ linking process. Learn how linkers work, what symbol resolution is, how static linking creates an executable, and why common errors like undefined references and ODR violations occur.

{CPP}C++ Linking Process: How Object Files Become an Executable

Static Linking - Combining Objects into an Executable

Undefined Reference / Unresolved External Symbol

Why do I get a Multiple Definition Error?

Object Files and the Linking Process

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Managing C++ Projects Using CMake