Modules and Packages

As a program grows you need to split it across files, keep names from colliding, and pull in third-party libraries. In C++ that job has traditionally been shared by three things: header and source files, namespaces, and the build system. This chapter covers that classic setup, then looks at CMake targets, package managers, and where C++20 modules fit in.

Headers and source files

The usual convention is to put declarations in a header (.h or .hpp) and definitions in a source file (.cpp). Other files #include the header to learn what exists; the linker later connects the calls to the actual code.

// math_utils.hpp
#pragma once

namespace mathx {
int gcd(int a, int b);
double mean(const int* values, int count);
}

// math_utils.cpp
#include "math_utils.hpp"

namespace mathx {
int gcd(int a, int b) {
    while (b != 0) {
        int t = a % b;
        a = b;
        b = t;
    }
    return a;
}

double mean(const int* values, int count) {
    if (count == 0) return 0.0;
    long long sum = 0;
    for (int i = 0; i < count; ++i) sum += values[i];
    return static_cast<double>(sum) / count;
}
}

#pragma once keeps a header from being processed twice in the same translation unit. It isn't part of the standard, but every mainstream compiler supports it; the portable alternative is a classic #ifndef/#define include guard.

Separate compilation

Each .cpp file is compiled on its own into an object file, and the linker stitches the object files together. Change one source file and only that file needs recompiling.

g++ -std=c++20 -c math_utils.cpp -o math_utils.o
g++ -std=c++20 -c main.cpp -o main.o
g++ main.o math_utils.o -o app

Two linker errors come up constantly. "Undefined reference" means something was declared and used but never defined in any object file you linked. "Multiple definition" usually means a function body lives in a header that several source files include. If you really want a function defined in a header, mark it inline, or make it a template or a member function defined inside the class body.

Namespaces

Namespaces group names under a common prefix so that libraries don't trip over each other. Everything in the standard library lives in std.

#include <iostream>
#include "math_utils.hpp"

namespace app::config {          // C++17 nested namespace syntax
constexpr int retries = 3;
}

int main() {
    std::cout << mathx::gcd(12, 18) << '\n';   // 6
    std::cout << app::config::retries << '\n';

    using mathx::gcd;                           // bring in just this name
    std::cout << gcd(8, 12) << '\n';
}

Never write using namespace std; in a header: it leaks every standard name into every file that includes yours. Inside a source file, importing a few specific names with using in a narrow scope is the safer habit.

CMake targets

Modern CMake is organized around targets. Libraries and executables are targets, and the target_* commands attach include paths, compile options and dependencies to them.

cmake_minimum_required(VERSION 3.20)
project(calc LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_library(mathx src/math_utils.cpp)
target_include_directories(mathx PUBLIC include)

add_executable(calc src/main.cpp)
target_link_libraries(calc PRIVATE mathx)

PUBLIC means a setting also propagates to anything that links against the target; PRIVATE keeps it internal. Here calc automatically gets the include directory just by linking to mathx, with no extra configuration.

Package managers

C++ has no official package manager, but a few tools have become standard practice:

In vcpkg's manifest mode you keep a vcpkg.json at the project root and point CMake at the vcpkg toolchain when configuring:

# vcpkg.json, for example: { "name": "calc", "dependencies": [ "fmt" ] }
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake
cmake --build build

Your CMakeLists.txt then uses the library with find_package(fmt CONFIG REQUIRED) and target_link_libraries(calc PRIVATE fmt::fmt). With Conan, you run conan install . --build=missing to fetch or build dependencies, then configure CMake with the toolchain file Conan generates.

C++20 modules

C++20 introduced modules to address the long-standing costs of textual #include: slow builds from reparsing the same headers, and macros leaking between files. A module exposes only what it explicitly exports.

// greet.cppm (module interface unit; some toolchains prefer .ixx)
module;                 // global module fragment: classic #includes go here
#include <string>

export module greet;

export std::string greet(const std::string& name) {
    return "Hello, " + name;
}

A consumer simply writes import greet;. C++23 goes further with import std;, which makes the whole standard library available in one line. That said, compiler and build system support for modules is still uneven, so check the documentation for your exact compiler and CMake version before adopting them in a real project. Most existing libraries are still distributed as headers.

Summary

• Put declarations in headers and definitions in source files; compile sources separately and link them.
• Use namespaces to avoid collisions, and keep using namespace out of headers.
• Describe builds in CMake with add_library, add_executable and target_link_libraries.
• Bring in third-party code with vcpkg, Conan or FetchContent.
• C++20 modules are promising, but confirm your toolchain supports them first.