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 established a recommended directory structure for our projects. This organization brings order to _**our**_ code, but modern applications are rarely built in isolation. They stand on the shoulders of giants: third-party libraries that provide everything from low-level graphics rendering to complex data analysis.


Integrating these external dependencies can be a challenge. How do you tell your compiler where to find a library's header files? How do you tell your linker which library files to use? And how do you manage this across different platforms, where file names and conventions vary wildly?


This lesson will cover the concepts needed to manage these external dependencies. We'll explore include paths and library paths and confront the issues of versioning and binary compatibility


## Header-Only Libraries


When we download a C++ library for our project, they will be in one of three forms:

1. One or more header files, in addition to a library that has already been compiled (such as a `.a` or `.lib` file)
2. One or more header files, in addition to the library source code.  This allows us to compile the library ourselves.
3. One or more header files, with no additional library files or source code required.  This is called a "header-only" library

We'll mostly focus on scenario 1 and 2 in this lesson, but let's talk about header-only libraries briefly here.  As the name suggests, they're distributed as one or more header files which we can `#include` anywhere they are neeeded.  


All the code required to use the library is within those header files.  As such, all the definitions are available to the compiler after the preprocessor creates the translation unit - no additional linking is required.


This makes the library very easy to use, but it means the preprocessor will be creating larger translation units, making compilation slower.  Because of this, the header-only approach is typically only used for small, simple libraries.


Larger libraries are generally distributed using option 1 or 2, which is what we'll focus on in the rest of this lesson.


## Creating a Library


When you use an external library, you're interacting with it at two distinct stages of the build process: compilation and linking. Each stage requires you to provide a specific piece of information: a path.


Let's imagine we've downloaded a simple third-party library called "SuperLog" that provides logging functionality.  The library is provided in the form of a header file `superlog.h` and a static library `libsuperlog.a`, or source code that we can compile to create `libsuperlog.a` ourselves.


<CodeViewer>


<CodeFile path="superlog.h">


```c++
#include <string_view>

namespace superlog {
  void initialize();
  void print(const std::string_view& content);
}
```


</CodeFile>


<CodeFile path="superlog.cpp">


```c++
#include <iostream>
#include <string_view>

namespace superlog {
void initialize() {
  std::cout << "SuperLog is initialized\n";
};

void print(const std::string_view& content) {
  std::cout << content << '\n';
}
}
```


</CodeFile>


</CodeViewer>


We covered the library compilation process in the previous chapter.  For example, using GCC, our command to create our object file would be something like this:


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


Followed by a call to `ar` to archive our object file into a library:


```c++
//<ti>
ar rcs libsuperlog.a superlog.o
```


Let's create a program that wants to use this library.


<Pw>


## Using a Library


Once we have our library ready, we'd place it in the designated place within our project, such as a `libs/` directory:


```plain text
my_project/
├─ libs/
│ └─ SuperLog/
│  ├─ include/
│    └─ superlog.h
│  └─ lib/
│    └─ libsuperlog.a
└─ src/
  └─ main.cpp
```


Source files in our project that want to use the library would `#include` the appropriate header, and call upon the library features in the usual way:


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


```c++
// This probably won't work yet
#include "superlog.h"//<e>

int main() {
  superlog::initialize();
  superlog::print("Hello from the library!");
  return 0;
}
```


</CodeFile>


If we try to compile this directly, we'll likely hit two roadblocks - one at the compilation stage, and one at the linking stage.


### Compilation: The Include Path


First, the compiler needs to find `superlog.h`. When the preprocessor sees `#include "superlog.h"`, it looks for that file. If it's not in a known location, the build will fail immediately.  Let's try it:


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


Note we're calling our output `my_app` in these examples but, if you're on Windows, you would include the `.exe` extension, as in `my_app.exe`.  Either way, our compilation will likely fail at our `#include` directive:


```c++
//<oe>
src/main.cpp:1:10: fatal error: superlog.h: No such file or directory
    1 | #include "superlog.h"
      |          ^~~~~~~~~~~~
compilation terminated.
```


To fix this, we need to tell the compiler where to search for header files. We do this by providing an include path using the `-I` flag.


```c++
//<ti>
g++ -o my_app src/main.cpp -Ilibs/SuperLog/include
```


The `-I` flag adds `libs/SuperLog/include` to the list of directories the compiler will search when it encounters an `#include` directive. This allows it to find `superlog.h`, and the compilation phase now succeeds.


However, we're not done. The command will still fail, but at the next stage.


### Linking: The Library Path


Even though `main.cpp` compiled successfully into `main.o`, we now have a linker error that will look something like this:


```c++
//<oe>
main.cpp: undefined reference to `superlog::initialize()'
main.cpp: undefined reference to `superlog::print()'
```


The compiler was happy because `superlog.h` _**declared**_ the functions, but the linker is unhappy because it can't find their _**definitions**_. The machine code for `superlog::initialize()` and `superlog::print()` lives inside `libsuperlog.a`, and we haven't told the linker that this file exists.


We need to provide two more pieces of information:

1. Library Path: The directory where the library file (`.a`, `.lib`, etc.) is located. We use the uppercase `L` flag for this.
2. Library Name: The name of the library to link against. We use the lowercase `l` flag for this.

Let's add these flags to our command:


```c++
//<ti>
g++ -o my_app src/main.cpp -Ilibs/SuperLog/include -Llibs/SuperLog/lib -lsuperlog
```

- `-Llibs/SuperLog/lib`: Tells the linker to add `libs/SuperLog/lib` to its search paths for libraries.
- `-lsuperlog`: Tells the linker to find and link a library named `superlog`. The linker is smart enough to prepend `lib` and append `.a` (or `.so`) automatically, so it looks for `libsuperlog.a`.

With these flags, the linker finds `libsuperlog.a`, extracts the compiled code for the `superlog` functions, and successfully builds our `my_app` executable:


```c++
//<ti>
./main
```


```c++
//<o>
SuperLog is initialized
Hello from the library!
```


As we're starting to see, managing these `-I`, `-L`, and `-l` flags manually is already tedious and getting difficult to follow, even for this incredibly simple program. This is precisely one of the core jobs of a build system like CMake.


## Versioning and Compatibility


There is additional complexity with dependencies.  Libraries are constantly being updated to fix bugs, add features, or improve performance. This introduces the concepts of **versioning and compatibility**.


To understand this, we first need to distinguish between two types of "interfaces."


<Definition>


### API vs. ABI


The **API** (Application Programming Interface) is the interface for the programmer. It's defined by the header files - the function names, class definitions, and parameters you use in your source code. If the API is stable, your code will continue to compile without changes.


The **ABI** (Application Binary Interface) is the interface for the compiler and linker. It's the low-level, binary contract that dictates how functions are called, how data structures are laid out in memory, and how names are mangled.


</Definition>


An ABI break occurs when a change to the library's source code results in incompatible machine code, even if the API looks the same. Examples of ABI-breaking changes include:

- Adding a virtual function to a class.
- Changing the order of non-static member variables.
- Changing a function's parameter types (e.g., from `int` to `long`).
- Compiling the library with a different compiler or even different optimization flags.

### Why ABI Stability Matters


The type of library you use dictates how much you need to worry about ABI stability.


**With Static Libraries**: ABI incompatibility is not a major issue. If you get a new version of a static library that has an ABI break, you simply recompile your entire application. Since all the code is bundled into your executable, everything is guaranteed to be consistent.


**With Shared Libraries**: ABI incompatibility is the root cause of "DLL Hell." Imagine your application was built and linked against `libsuperlog.so` version 1.0. Later, a user installs another program that replaces it with `libsuperlog.so` version 2.0, which has an ABI break.


The next time you run your application, the OS loader will load the new, incompatible library. When your code tries to call a function, it might jump to the wrong address or misinterpret the memory layout of a class, leading to a crash.


### Semantic Versioning


To manage this, the software community developed **Semantic Versioning** (SemVer) as a convention.  Software using the semantic versioning convention are identified by three numbers, such as `2.1.5`.  These numbers correspond to:

- the **MAJOR** version (`2` in this example)
- the **MINOR** version (`1` in this example)
- the **PATCH** version (`5` in this example).

When we release an update to our library, the way in which we adjust these numbers communicates the nature of the change we made in that new version.  For example, if the current version of our library is `2.1.5` and we want to release a new version, our version number would be:

- `2.1.6` if our change is backward-compatible bug fixes (a **PATCH** version).
- `2.2.0` if our change is backward-compatible feature additions (a **MINOR** version).
- `3.0.0` if our change is not backward-compatible (a **MAJOR** version).

A **MAJOR** version bump is a clear signal: if you update to this version, you will need to recompile your code, and you may need to change it to accommodate API changes.


Changes that necessitate a major version change are sometimes called **breaking changes**, and a goal of good software management and interface design is to minimize the frequency with which breaking changes need to be made.


## Platform Differences


As if managing paths and versions wasn't enough, different operating systems have their own conventions for naming and using libraries.


### Linux / macOS


**Static Library**: A file named `lib<name>.a` (e.g., `libsuperlog.a`).


**Shared Library**: A file named `lib<name>.so` (e.g., `libsuperlog.so`). On macOS, this is `.dylib`.


**Linking**: The `l<name>` flag works for both. The linker typically prefers the shared version (`.so`) if both are found in the same directory.


### Windows (with MSVC)


Windows has a more complex system for dynamic linking.


**Static Library**: A file named `<name>.lib` (e.g., `superlog.lib`). This contains all the object code, just like a `.a` file.


**Shared Library**: A dynamic library consists of two files:

1. The **DLL** (`<name>.dll`): This is the actual library that contains the executable code and is needed at runtime.
2. The **Import Library** (`<name>.lib`): This is a special, small `.lib` file that you link against at build time. It doesn't contain the actual code. Instead, it contains information that tells the linker how to create the necessary stubs to call into the `.dll` when the program runs.

This dual-file system for DLLs is a frequent source of confusion. When linking against a DLL on Windows, you link against its import `.lib` file, but you must distribute the `.dll` file with your application.


Manually managing these platform-specific conventions is another major headache that CMake eliminates.


## Summary


Managing external dependencies is a multi-faceted problem that sits at the intersection of compiling, linking, and deployment. Without a good build system, it's a manual, error-prone, and non-portable process.

- **Compiler and Linker Paths**: You must tell the compiler where to find headers (`I` for include paths) and the linker where to find library files (`L` for library paths) and which libraries to use (`l` for library names).
- **Usage Differences**: Using a static library results in a large, self-contained executable. Using a shared library results in a smaller executable but requires the library file to be present at runtime.
- **Compatibility is Key**: API changes break your source code. ABI changes break your running program. Understanding the difference is important for working with shared libraries, and Semantic Versioning helps communicate these changes.
- **Platform Divergence**: Windows, Linux, and macOS have different naming conventions (`.lib`/`.dll` vs. `.a`/`.so`) and different mechanisms for finding shared libraries at runtime. The Windows "import library" is a particularly important platform-specific detail.

We have now explored the major components of a C++ project: the source code organization, the build pipeline, and the management of external libraries.


We've also seen the manual, command-line approach to handling them and the pain points that arise. In the next chapter, we'll start introducing tools that help us manage a lot of this complexity.


<Preview>


### Build Systems and Their Limitations


Before we introduce CMake, our ultimate solution, it's helpful to look at some of the alternatives.  This will set the stage perfectly for understanding why CMake was created and the problems it is designed to solve.


These approaches are still widely used, particularly in older projects, so an understanding of how they work is also directly useful.


In the next lesson, we'll examine traditional build tools like Makefiles and IDE-specific project files (like Visual Studio Solutions).


</Preview>


</Pw>

Options for Linking

Dynamic-Link Libraries (DLLs)

DLL Hell

Application binary interface (ABI)

Policies/Binary Compatibility Issues With C++

Semantic Versioning 2.0.0

A complete guide to managing third-party libraries and external dependencies in C++. Learn about include paths, library paths, static vs. shared library trade-offs, ABI stability, versioning, and platform differences between Windows (.lib/.dll) and Linux (.a/.so).

Managing Libraries and Dependencies

Understanding the Basics

Practical Applications

Common Mistakes

Next Steps

Additional Resources

Assessment Preparation

Managing C++ Projects Using CMake