Library Linking — Link against a library conceptually (include paths vs link flags) (intro)

From the earliest days of compiled programming languages, developers recognized that no program is truly self-contained. Even the simplest C or C++ program that prints text to the console relies on functions written by someone else — functions that live in a library. The challenge, then, has always been twofold: how does the compiler know the declarations (the shapes) of those external functions, and how does the final executable locate the compiled machine code that implements them? These two questions map directly onto the distinction between include paths and link flags, a separation that has shaped build systems for over half a century.

The central question this lesson addresses is deceptively simple: when you write #include <somelib/header.h> and call a function from that library, what exactly must you tell your compiler and linker so that the final binary actually works? Understanding the answer — and in particular, understanding that the compiler and linker are separate tools with separate responsibilities — is essential before you can confidently integrate any third-party library into a C++ project.

Before diving into flags and file paths, it is important to internalize the conceptual model that underlies C++ library linking. The entire build process can be decomposed into distinct phases, each with its own inputs and outputs, and the confusion that beginners encounter almost always stems from conflating what the compiler needs with what the linker needs. The following four principles form the conceptual foundation for everything that follows.

The diagram below illustrates the complete journey from source code to executable, emphasizing where include paths and link flags intervene. Notice that the preprocessor and compiler operate on each translation unit independently (the left half), while the linker operates on the collection of all object files and libraries together (the right half). This phase separation is the single most important mental model for understanding library linking.

Observe the asymmetry in the diagram: the -I flag is consumed during the preprocessing/compilation stage, before any machine code is generated, while the -L and -l flags are consumed only during the linking stage, after all translation units have been individually compiled. When you invoke g++ main.cpp utils.cpp -I/usr/include/mylib -L/usr/lib/mylib -lmylib -o my_program, the driver program g++ orchestrates both phases automatically, which is why beginners often do not realize that two entirely different tools are at work under the hood.

The Preprocessor's Search Algorithm

When the preprocessor encounters a directive like #include <mylib/vector_math.h>, it searches an ordered list of directories for a file at the relative path mylib/vector_math.h. This search list is composed of system default directories (e.g., /usr/include on Linux) plus any directories you add with the -I flag. The order matters: directories specified via -I are searched before system defaults, which allows you to override system headers if necessary. Angle-bracket includes (#include <...>) and quoted includes (#include "...") differ subtly: quoted includes first search the directory of the including file, then fall back to the same search path as angle brackets.

The Linker's Symbol Resolution

After compilation, each object file contains a symbol table — a list of names (functions, global variables) that the object either defines or references. A reference without a corresponding definition is called an undefined symbol. The linker's job is to scan all provided object files and libraries, matching every undefined symbol to exactly one definition. The -L flag adds directories to the linker's library search path — analogous to -I for the preprocessor. The -l flag names a specific library: -lmylib tells the linker to search for a file named libmylib.a (static) or libmylib.so (dynamic) in the search path. If any undefined symbols remain after all libraries have been scanned, the linker emits the dreaded "undefined reference" error.

Flag Summary Table

Understanding the conventional filesystem layout of a library makes include paths and link flags feel intuitive rather than arbitrary. Most well-organized C++ libraries follow a two-directory pattern: an include directory containing public headers and a lib directory containing the compiled binary. On Unix-like systems, a library installed to a prefix like /usr/local would typically place headers under /usr/local/include/mylib/ and binaries under /usr/local/lib/. This convention is why -I/usr/local/include and -L/usr/local/lib are so common.

Naming Conventions Across Platforms

Notice a subtle but critical convention on Unix-like systems: when you pass -lfoo, the linker automatically prepends lib and appends the appropriate extension (.a or .so), so the flag -lfoo resolves to libfoo.a or libfoo.so. You do not write -llibfoo; that would cause the linker to search for liblibfoo.so, which almost certainly does not exist.

Suppose you have installed a third-party linear algebra library called linalg into /opt/linalg. Its headers are in /opt/linalg/include and its compiled static library is at /opt/linalg/lib/liblinalg.a. Your source file solver.cpp uses #include <linalg/matrix.h> and calls linalg::invert(). Let's build it step by step.

Both static and dynamic linking use the same -L and -l flags at build time, but they differ profoundly in what happens to the library's machine code. In static linking, the linker copies the needed object code from the .a archive directly into the output executable. In dynamic linking, the linker merely records a reference to the shared object (.so / .dll), and the operating system's dynamic loader resolves the reference at runtime.

In practice, manually specifying -I, -L, and -l on the command line is tedious and error-prone for projects with many dependencies. This is precisely the problem that build systems like CMake, Meson, and Bazel solve. They abstract the per-platform flag details behind higher-level commands. For instance, CMake's find_package() locates a library's installed configuration and automatically populates the correct include directories and link targets. Understanding the underlying flags, however, remains essential: when a build fails, the error messages refer to the raw flags, and you need to know which phase went wrong.