Inline namespaces, anonymous namespaces: Foundations

Before you can appreciate the parent topic, you must be fluent in a small chain of ideas. We build them one link at a time, each earning the next. Nothing below assumes you already know C++ jargon — we even define the build-pipeline words as we hit them.

0. The build pipeline — three helpers that turn text into a program

Why the topic needs it: "internal linkage", "translation unit", and "mangled symbol" are all defined in terms of these stages. Naming the stages first keeps the promise of assuming no jargon.

1. A "name" versus a "symbol" — two different things

Why the topic needs it: the parent talks about both "names leaking" (a source idea) and "mangled symbols" (a linker idea). Keeping the two levels separate stops you from conflating them.

2. Translation unit — the "one file" boundary

Figure — Inline namespaces, anonymous namespaces

Why the topic needs it: the anonymous namespace's whole promise — "private to this file" — is meaningless unless you know exactly what "this file" is. The boundary is the translation unit, not the raw .cpp on disk.

See Translation units and the One Definition Rule for the full story.

3. Linkage — "how far a name is allowed to travel"

Why the topic needs it:

An anonymous namespace gives internal linkage — it builds that dashed wall.
An inline namespace deliberately keeps names on the external side but re-labels them, which we'll see in step 8.

More depth: Internal vs external linkage.

4. The One Definition Rule (ODR) — why clashes are fatal

Worked example Concrete clash

// file_a.cpp
int compute() { return 1; }   // external
// file_b.cpp
int compute() { return 2; }   // external — SAME tag!

Link error: multiple definition of compute. The anonymous namespace is the cure — it demotes both to internal so the tags become file-private.

Why the topic needs it: the ODR is the enemy the anonymous namespace defeats. If ODR didn't exist, we wouldn't need file-private names. See Translation units and the One Definition Rule.

5. Namespaces — the folder that groups names

namespace lib {
    void process();      // full name is  lib::process
}
lib::process();          // reach in with  ::

Why the topic needs it: inline and anonymous namespaces are special folders. You cannot understand a special folder until you know a plain one. Start at Namespaces (basics).

6. `static` — the old tool anonymous namespaces replaced

Why the topic needs it: the parent note pitches the anonymous namespace as the modern replacement for static. You must know what static did — and its limit (no types) — to see why the replacement is better. Full detail: static keyword (storage & linkage).

7. The anonymous (unnamed) namespace — defined

Definition Anonymous namespace

A namespace written with no name at all. Every name declared inside it gets internal linkage (step 3) — it becomes private to the translation unit. Syntax:

namespace {              // note: no name after the keyword
    int secret = 42;     // file-private variable
    int helper() { ... } // file-private function
    struct Cache { };    // file-private TYPE — static can't do this
}

Conceptually the compiler invents a unique hidden name per TU and adds an implicit using, so no two files can ever share these names.

Why the topic needs it: this is one of the two stars of the parent topic. Everything above (linkage, ODR, static) exists to make this definition land.

8. The inline namespace — defined

Definition Inline namespace

A namespace written with the keyword inline in front. Its members stay in their own folder but also appear in the enclosing folder unqualified, as if declared one level up — for ordinary lookup, for ADL, and for template specialization. Syntax:

namespace lib {
    inline namespace v2 { void process(); }  // the default version
    namespace v1        { void process(); }  // old, opt-in only
}
lib::process();        // resolves to lib::v2::process — v2 leaked up
lib::v1::process();    // still reachable by full name

Why the topic needs it: this is the second star of the parent topic — the mechanism behind API versioning. Its members are still externally linked (step 3), which is why the next two steps matter.

9. Name mangling — where the version gets "baked in"

Why the topic needs it: the parent's key claim — "the inline name is part of the mangled symbol, so mismatched versions won't silently mix" — is invisible unless you know mangling exists. See Name mangling and the ABI.

10. Argument-Dependent Lookup (ADL) — how `draw(w)` finds `draw`

Why the topic needs it: Example 3 in the parent ("ADL sees through inline") is pure ADL. Deep dive: Argument-Dependent Lookup (ADL).

11. API versioning — the problem inline namespaces solve

Why the topic needs it: this is the entire motivation for inline namespaces. Strategy context: API versioning strategies.

How the foundations feed the topic

The map below reads top to bottom: the plain ideas at the top (a name, a namespace, a translation unit) feed the middle-layer rules (linkage, the ODR, mangling), which in turn feed the two headline features (anonymous and inline namespaces) that make up the parent topic. Follow any arrow as "is needed to understand".

Alt-text (in case the diagram does not render): "Name" splits into "Symbol", "Namespace folder", and "Translation unit". "Translation unit" leads to "Linkage", which leads to the "One Definition Rule"; "static keyword" also leads to "Linkage". "Namespace folder" plus "Linkage" plus "ODR" feed "Anonymous namespace". "Namespace folder", "Name mangling" (fed by "Symbol"), "ADL", and "API versioning" all feed "Inline namespace". Both "Anonymous namespace" and "Inline namespace" feed the final node, "Inline and anonymous namespaces".

Equipment checklist

Self-test: can you answer each before opening the parent note?

The three build-pipeline stages, in order, are ::: preprocessor (pastes headers/macros), then compiler (source → object file), then linker (object files → one program).
A "name" in C++ is ::: a source-level label (identifier) you type to refer to a variable, function, or type.
A "symbol" is ::: the linker-level decorated string produced from a shared name — read by the linker, not by you.
A translation unit is ::: one .cpp file after the preprocessor pastes in all its #includes — the chunk the compiler processes independently.
The three kinds of linkage are ::: no linkage (block-scope names/parameters), internal linkage (private to a TU), external linkage (shareable across TUs).
The One Definition Rule says ::: an externally-linked thing may be defined once, EXCEPT inline functions/variables, templates, and class definitions, which may repeat identically (one per TU).
The :: operator means ::: "inside" — scope resolution, reaching a name within a namespace (folder).
static on a global gives ::: internal linkage, but it cannot be applied to a type/struct.
An anonymous namespace is ::: a nameless namespace { } whose members get internal linkage — file-private, and it works for types too.
An inline namespace is ::: a inline namespace { } whose members also appear in the enclosing namespace unqualified — the versioning/default mechanism.
Name mangling is ::: the compiler encoding a name's namespace and argument types into the actual linker symbol.
ADL is ::: unqualified-call lookup that also searches the namespaces of the argument types.
API versioning is ::: shipping a new interface while old callers keep working, with a chosen default version.

Once every reveal comes to you instantly, go read the parent topic.