.CPP File Format – File structure

File names and extensions

The standard says nothing about file names. It speaks of source files and headers only, and a header need not be a file at all [cpp.include]. The extensions below are conventions that compilers and build tools have adopted.

Compilers also produce binary forms of module interfaces, such as Clang’s .pcm, GCC’s .gcm and MSVC’s .ifc. These are private to each compiler. See Namespaces and modules.

Translation units

A source file, together with every header and source file it includes, minus any lines skipped by conditional inclusion, is a translation unit [lex.separate]. Each translation unit is compiled alone. A linker then joins the results.

translation-unit:
    [declaration-seq]
    [global-module-fragment] module-declaration [declaration-seq] [private-module-fragment]

The first form is an ordinary file. The second is a module unit (C++20). In both cases, what remains after preprocessing is a series of declarations. Statements appear only inside function bodies.

// greet.hpp: the declarations that other files share
#ifndef GREET_HPP
#define GREET_HPP

#include <string>

std::string greet(const std::string& name);

#endif

// greet.cpp: one definition, in one translation unit
#include "greet.hpp"

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

// main.cpp: a second translation unit that uses it
#include <iostream>
#include "greet.hpp"

int main()
{
    std::cout << greet("world") << '\n';
}

Phases of translation

The standard defines translation as nine phases, applied in order [lex.phases]. A compiler may merge them, as long as the result is the same.

Consequences of this order:

• Because splicing (phase 2) comes before comments are removed (phase 3), a // comment ending in a backslash continues onto the next line.
• Because comments become spaces before directives run, a comment can appear inside a directive.
• Because concatenation (phase 6) comes after macro expansion, a macro can expand to a string that joins its neighbours: "a" MACRO "c".
• In a raw string literal the changes made by phases 1 and 2 are undone, so a backslash at the end of a line stays in the text [lex.pptoken].

Source encoding

How a file’s bytes map to characters is implementation-defined, with one guarantee: since C++23, every compiler must accept UTF-8 source [lex.phases]. Compilers differ in their default.

• A UTF-8 byte order mark at the start of a file is removed in phase 2.
• The basic character set [lex.charset] is the Latin letters, the digits, the space and the control characters for tab, vertical tab, form feed and new-line, and the punctuation _ { } [ ] # ( ) < > % : ; . ? * + - / ^ & | ~ ! = , \ " '.
• Any other character can be written as a universal character name: é, \U0001F600, and since C++23 \u{E9} and \N{LATIN SMALL LETTER E WITH ACUTE}. See Lexical structure.
• A physical line may end in LF, CRLF or anything else the compiler maps to a new-line. Since C++23 white space between a final backslash and the line ending is ignored too.
• C++ keeps the source encoding and the literal encoding apart. The first is how the file is read; the second is what a string literal holds in the program.

Headers

A header is text pasted into a translation unit by #include. Since it is read once per translation unit that includes it, it normally holds only what may be repeated across units.

#ifndef LIBRARY_WIDGET_HPP
#define LIBRARY_WIDGET_HPP

class Widget { /* ... */ };

#endif

Linkage

Linkage decides whether a name in one scope can refer to the same entity as a name in another [basic.link].

So const int size = 10; in a header gives each translation unit its own variable, which is safe. int size = 10; in a header breaks the one-definition rule as soon as two translation units include it. inline int size = 10; (C++17) is one variable shared by all.

The one-definition rule

The one-definition rule, or ODR, limits how many definitions an entity may have [basic.def.odr].

• Within one translation unit, a variable, function, class, enumeration or template may have only one definition. Breaking this is a compile-time error.
• Across the whole program, a non-inline function or variable that is odr-used must have exactly one definition. Breaking this usually gives a link error, but no diagnostic is required.
• A class, enumeration, inline function, inline variable, template or default template argument may be defined in several translation units, as long as every definition is the same.

“The same” is strict. The definitions must be the same sequence of tokens, and each name in them must refer to the same entity. If they differ, the program is ill-formed with no diagnostic required, so it may compile, link and misbehave. This is why a macro that changes the content of a header between translation units is dangerous.

A variable is odr-used when its address or a reference to it is needed, or when its value is read and it cannot be replaced by a constant at compile time. A function is odr-used when it is called or its address is taken, in an expression that is potentially evaluated. Operands of sizeof, decltype, noexcept and most uses of typeid are not evaluated, so they do not odr-use anything.

Program start-up

A hosted program starts at the global function main [basic.start.main]. A freestanding one starts wherever the implementation says.

int main() { }
int main(int argc, char* argv[]) { }

• main may not be called by the program, overloaded, or declared static, inline, constexpr or consteval. Its address may not be taken.
• Falling off the end of main is the same as return 0;. This holds for no other function.
• argv[argc] is a null pointer.

Variables with static storage duration are initialised before main: first by constant or zero initialisation [basic.start.static], then, for anything else, by dynamic initialisation [basic.start.dynamic]. Within one translation unit, dynamic initialisation follows the order of definition for most variables. Between translation units the order is not specified, so one global’s initialiser should not rely on a global in another file. constinit (C++20) makes a variable’s constant initialisation a checked requirement; see Declarations. Destruction runs in the reverse order [basic.start.term].