# Translation Units, ODR, and Linkage

> Trace how source files become translation units and how scope, storage duration, linkage, and the One Definition Rule govern symbol visibility across them.

- **Source:** C++ Atlas (https://cppatlas.com/topics/translation-units-and-linkage)
- **Track:** Program structure
- **Estimated reading time:** 8 minutes
- **ISO C++ clauses:** [lex.phases] (https://eel.is/c++draft/lex.phases), [basic.scope] (https://eel.is/c++draft/basic.scope), [basic.stc] (https://eel.is/c++draft/basic.stc), [basic.link] (https://eel.is/c++draft/basic.link), [basic.def.odr] (https://eel.is/c++draft/basic.def.odr), [dcl.link] (https://eel.is/c++draft/dcl.link)
- **cppreference links:** [Phases of translation](https://en.cppreference.com/w/cpp/language/translation_phases), [Storage class specifiers](https://en.cppreference.com/w/cpp/language/storage_duration), [Definitions and ODR](https://en.cppreference.com/w/cpp/language/definition), [inline specifier](https://en.cppreference.com/w/cpp/language/inline), [Language linkage](https://en.cppreference.com/w/cpp/language/language_linkage), [Translation-unit-local entities](https://en.cppreference.com/w/cpp/language/tu_local)

C++ compilers do not compile header files. They compile one **translation unit** at a time, after the preprocessor has flattened every `#include` directive into a single stream of tokens. Most linker errors, duplicate-symbol bugs, and mysterious global-state bugs happen when mental models confuse a `.hpp`/`.cpp` file layout on disk with the language rules governing translation units, linkage, and the One Definition Rule (ODR).

## From source files to translation units

The C++ standard divides compilation into nine **phases of translation** (`[lex.phases]`). Phases 1–4 handle character mapping, line splicing, comment stripping, and preprocessing. In phase 4, `#include` textually pastes header contents into the `.cpp` file and macros expand. What emerges is a **translation unit** (TU): one self-contained stream of preprocessed declarations and definitions.

Phases 5–7 convert literals, concatenate adjacent string literals, and perform syntactic and semantic analysis on that single TU in isolation. Phase 8 instantiates needed templates, and phase 9 links all compiled TUs and resolves external symbols. Because phase 7 never inspects neighboring `.cpp` files, cross-file visibility rests entirely on declarations visible in the current TU.

> **Mental model.** A header file is only a convention for copying the same declarations into multiple translation units before phase 7 begins. The language proper sees only separate translation units and the linker contract between them.

## Scope, storage duration, and linkage

Three independent properties govern every named variable or function in C++: **scope**, **storage duration**, and **linkage**. Treating them as synonyms guarantees confusion, especially around the overloaded `static` keyword.

- **Scope** (`[basic.scope]`) is a compile-time lookup property: which region of source text can refer to an unqualified name.
- **Storage duration** (`[basic.stc]`) is a lifetime property: when the object's storage is allocated and released (automatic, static, thread, or dynamic).
- **Linkage** (`[basic.link]`) is a multi-declaration identity property: whether two declarations of the same name in different scopes or different translation units refer to the *same* entity.

| Linkage kind | Declared via | Shared across TUs? | Typical examples |
| --- | --- | --- | --- |
| No linkage | Block-scope locals, parameters, local classes | Never | Local `int x`, block-scope `static int hits` |
| Internal linkage | `static` at namespace scope, unnamed `namespace`, namespace-scope `const` | Private to one TU | `static void helper()`, `const int kLimit = 8;` |
| External linkage | Non-static namespace-scope entities, `extern`, `inline` globals, classes | Shared across whole program | Non-member functions, `inline constexpr`, classes |
| Module linkage | Non-exported entities in module purview | Shared within one module | Helpers inside a named C++20 module |

Notice how a block-scope `static` variable crosses axes: it has **static storage duration** (living for the entire program run) and **block scope**, yet **no linkage**—two functions each declaring `static int hits = 0;` get completely separate objects. An important subtle twist occurs when a local `static` lives inside an `inline` function with external linkage: the local variable still has no linkage itself, yet the ODR requires every TU's copy of that inline function to share the single static local object!

```cpp
// Block-scope static: static storage duration, no linkage.
int next_ticket() {
    static int counter = 0; // distinct per function, not shared by name across scopes
    return ++counter;
}

// Inline function with external linkage: all TUs share one `instance` object.
inline int& global_counter() {
    static int instance = 0;
    return instance;
}
```

## Internal linkage: static, const, and unnamed namespaces

At namespace scope, C++ grants external linkage by default. Three mechanisms switch a declaration to **internal linkage**, keeping its symbol private to the current translation unit so `.cpp` files never collide at link time.

First, applying `static` to a namespace-scope variable or function gives it internal linkage. Second, an **unnamed namespace** (`namespace { ... }`) gives internal linkage to every variable, function, class, enumeration, and template inside it (`[basic.link]`). Unlike `static`, which cannot mark a class definition, an unnamed namespace hides user-defined types and prevents ODR collisions between `struct Impl` helpers across `.cpp` files.

Third, a namespace-scope variable declared `const` (including `constexpr`, which implies `const` on objects) has internal linkage unless also marked `extern`, `inline`, or `volatile`, or previously declared external.

> **Standardese.** Under `[basic.link]`, a non-volatile, non-template, non-inline namespace-scope variable of non-exported `const`-qualified type has internal linkage unless previously declared otherwise or explicitly marked `extern`.

```cpp
namespace {
struct ScratchBuffer {   // Internal linkage: safe to define differently in another TU
    int size = 64;
};
int helper_calls = 0;    // Internal linkage; `static` here would be redundant
}

static void record_call() {
    ++helper_calls;
}

const int kDefaultPort = 8080;         // Internal linkage (const without extern/inline)
extern const int kSharedVersion = 3;   // External linkage (explicit extern overrides const rule)
```

## The One Definition Rule and inline entities

The **One Definition Rule** (`[basic.def.odr]`) separates declarations (which may appear repeatedly in a TU) from definitions (which actually allocate storage, provide a function body, or define a type). Its rules split into two tiers:

1. **Within a single translation unit**, no variable, function, class type, enumeration, or template may be defined more than once.
2. **Across the entire program**, every **odr-used** non-inline function and non-inline variable with external linkage must have **exactly one** definition. Missing definitions cause undefined-reference linker errors; duplicate definitions cause multiple-definition linker errors.

Certain entities—classes, templates, `inline` functions, and C++17 `inline` variables—*must* be defined in headers across multiple TUs. The ODR permits one definition per TU provided every TU sees identical tokens whose names resolve to the exact same entities. Changing class layout across TUs via macros is **ill-formed, no diagnostic required (IFNDR)**: the linker rarely catches it, and runtime corruption silently ensues.

```cpp
// Safe header constant since C++17: external linkage, merged to a single address.
inline constexpr int kMaxRetries = 5;

// Contrast with plain `const int kLegacyRetries = 5;` in a header:
// each TU receives its own internal-linkage copy with a distinct address.
inline const int* retry_address() {
    return &kMaxRetries; // Every TU observes the exact same pointer value
}
```

> **Pitfall.** Taking the address of a namespace-scope `const` (non-`inline`) or `static` variable inside an external `inline` function causes IFNDR: each TU resolves to a distinct object, violating ODR entity-identity rules.

Using `inline constexpr` (C++17+) avoids this trap in headers by granting external linkage and merging every TU to one object.

## Language linkage and TU-local boundaries

When calling C libraries or exposing ABI symbols, `extern "C"` specifies **language linkage** (`[dcl.link]`). It disables C++ name mangling and selects the C calling convention while leaving **C++ linkage** (internal vs. external) intact.

Two subtleties frequently catch developers off guard. First, `extern "C" { int x; }` defines `x`, whereas `extern "C" int x;` (without braces) treats `extern` as a declaration only. Second, ISO C++ treats function types with different language linkages as distinct types (`[dcl.link]`)—meaning `extern "C" void (*)(int)` differs formally from `void (*)(int)`—though GCC and Clang allow converting between them when calling conventions match.

C++20 also formalized **TU-local** entities (`[basic.link]`): entities with internal linkage or no linkage cannot be exposed from external-linkage `inline` functions or module interfaces without triggering an error.

> **Pitfall.** Inside `extern "C" { int global_flag; }`, the braces suppress the `extern` storage-class effect on `global_flag`, turning it into a tentative definition that causes duplicate-symbol errors if placed in a header. Always write `extern "C" extern int global_flag;` for header declarations inside a linkage block.

## What to remember

- A **translation unit** is the post-preprocessor token stream of a single `.cpp` file; phase 7 compiles each TU in isolation before phase 9 links them.
- **Scope** governs name lookup, **storage duration** governs object lifetime, and **linkage** governs whether declarations across scopes or TUs refer to the same entity.
- Namespace-scope `const` variables default to **internal linkage**; prefer `inline constexpr` in headers so every TU shares one object and address.
- Use **unnamed namespaces** rather than `static` when hiding types, templates, or groups of helpers inside a single `.cpp` file.
- Every odr-used external non-inline entity needs exactly one definition program-wide; inline functions, inline variables, classes, and templates require identical definitions in every TU (or else IFNDR).

## Concept Map Outline

- **Translation Units & Linkage:** Source files become isolated translation units whose symbols coordinate through linkage and the One Definition Rule.
  - **Translation Phases:** Nine ordered compilation phases turn source text and headers into linked object code.
    - **Preprocessing (Phase 4):** Textually splices included headers and expands macros to form one translation unit.
    - **Semantic Analysis (Phase 7):** Compiles one translation unit in isolation without inspecting neighboring source files.
    - **Linking (Phase 9):** Merges compiled translation units and resolves external symbol references across the program.
  - **Three Orthogonal Axes:** Every declared entity independently carries a scope, storage duration, and linkage.
    - **Scope:** Compile-time lookup rule determining where an unqualified identifier can be resolved.
    - **Storage Duration:** Lifetime rule specifying when an object's storage is allocated and destroyed.
    - **Linkage:** Identity rule deciding whether declarations in different scopes or TUs name the same entity.
  - **Linkage Kinds:** C++ partitions declarations into no linkage, internal, external, or module linkage.
    - **No Linkage:** Block-scope locals and static local variables are never shared by name across scopes.
    - **Internal Linkage:** Namespace-scope static, unnamed namespaces, and plain const globals stay private to one TU.
    - **External Linkage:** Non-static globals, classes, and inline entities resolve to the same symbol program-wide.
    - **Module Linkage:** Non-exported entities inside a module purview are shared across that module's units only.
  - **One Definition Rule:** Limits how many definitions an entity may have per translation unit and program-wide.
    - **Single Program Definition:** Each odr-used non-inline external entity must have exactly one definition in the program.
    - **Inline & Template Merging:** Classes, templates, and inline entities allow one identical definition per translation unit.
    - **IFNDR Mismatch:** Token or lookup mismatches across TUs make the program ill-formed with no diagnostic required.
  - **Language & ABI Linkage:** Controls calling conventions, name mangling, and TU-local exposure boundaries.
    - **extern "C" Blocks:** Selects C ABI linkage while braced variable declarations without extern still define storage.
    - **TU-Local Entities:** Internal-linkage entities cannot be exposed via external inline functions or module exports.

## Standardese Quiz Questions

### Question 1 [warmup] ([lex.phases])

How does the compiler handle a #include "config.hpp" directive before phase 7 semantic analysis begins?

A. It compiles config.hpp once into a cached symbol table shared across all .cpp files.
B. It defers resolving declarations in config.hpp until the linker merges object files in phase 9.
C. The preprocessor textually pastes config.hpp into the including file in phase 4 to form one translation unit.
D. It automatically assigns internal linkage to every function declared inside config.hpp.

**Answer (C):** The preprocessor textually pastes config.hpp into the including file in phase 4 to form one translation unit.

**Why:** Under [lex.phases], preprocessing in phase 4 textually inserts the contents of included headers and expands macros. Phase 7 parses the resulting single translation unit with no separate concept of a header file.

### Question 2 [warmup] ([basic.link], [namespace.unnamed])

You need a helper struct Buffer defined in two different .cpp files with different layouts and no ODR collision. Which declaration gives Buffer internal linkage?

A. namespace { struct Buffer { int len; }; }
B. static struct Buffer { int len; };
C. inline struct Buffer { int len; };
D. extern "C" struct Buffer { int len; };

**Answer (A):** namespace { struct Buffer { int len; }; }

**Why:** An unnamed namespace gives internal linkage to every declaration inside it, including class types and templates. The static specifier cannot be applied to a class definition itself.

### Question 3 [tricky] ([basic.link], [basic.def.odr])

Why does putting this header snippet into two translation units violate the One Definition Rule?

```cpp
const int kRetries = 4;
inline const int* retry_ptr() {
    return &kRetries;
}
```

A. A const variable cannot have its address taken at namespace scope.
B. Returning a pointer from an inline function makes it non-inline.
C. Taking &kRetries forces dynamic initialization across translation units.
D. kRetries has internal linkage by default, so retry_ptr() resolves to a different object in each TU (IFNDR).

**Answer (D):** kRetries has internal linkage by default, so retry_ptr() resolves to a different object in each TU (IFNDR).

**Why:** A namespace-scope const variable without extern or inline has internal linkage under [basic.link], giving each TU its own kRetries object. Because retry_ptr() has external linkage and its odr-used name kRetries resolves to different entities across TUs, the program violates [basic.def.odr] (IFNDR). Adding inline constexpr fixes this.

### Question 4 [tricky] ([dcl.link], [basic.def.odr])

What happens if a header included by two .cpp files contains `extern "C" { int shared_status; }`?

A. It compiles and links cleanly because extern suppresses allocating storage.
B. Linking fails with a duplicate definition error because braces restrict extern "C" to language linkage only.
C. shared_status automatically receives internal linkage in each translation unit.
D. It is ill-formed at compile time because variables cannot have C language linkage.

**Answer (B):** Linking fails with a duplicate definition error because braces restrict extern "C" to language linkage only.

**Why:** Inside a braced linkage-specification (`extern "C" { ... }`), extern specifies language linkage rather than external-declaration-only status ([dcl.link]). Therefore `int shared_status;` is a variable definition in every TU that includes the header.

### Question 5 [standardese] ([basic.link], [basic.stc.static], [dcl.inline])

What are the scope, storage duration, and linkage of `hits` in this inline function?

```cpp
inline int bump() {
    static int hits = 0;
    return ++hits;
}
```

A. Block scope, static storage duration, and no linkage (yet shared across TUs via bump's ODR identity).
B. Block scope, automatic storage duration, and external linkage.
C. Namespace scope, static storage duration, and internal linkage.
D. Block scope, static storage duration, and external linkage.

**Answer (A):** Block scope, static storage duration, and no linkage (yet shared across TUs via bump's ODR identity).

**Why:** A block-scope static variable has block scope, static storage duration, and no linkage ([basic.link]). However, [dcl.inline] requires that static local variables inside an inline function with external linkage refer to the same single object across all translation units.

### Question 6 [standardese] ([basic.link], [dcl.inline])

Under [basic.link], which namespace-scope declaration still has external linkage in C++17 and later?

A. const int port = 8080;
B. constexpr int port = 8080;
C. inline constexpr int port = 8080;
D. namespace { constexpr int port = 8080; }

**Answer (C):** inline constexpr int port = 8080;

**Why:** Both `const` and `constexpr` at namespace scope imply const and yield internal linkage by default unless declared `inline` or `extern` (outside an unnamed namespace). Marking a constexpr variable `inline` gives it external linkage and merges all TU definitions into one object.
