.CPP File Format – Namespaces and modules

Argument-dependent lookup

For an unqualified call, argument-dependent lookup (ADL) adds functions from namespaces related to the arguments’ types [basic.lookup.argdep].

ADL does not happen if ordinary lookup finds a class member, a block-scope function declaration that is not a using-declaration, or a name that is not a function or function template.

namespace geo {
    struct Point { int x, y; };
    Point operator+(Point a, Point b);
    void print(Point p);
}

geo::Point p{1, 2}, q{3, 4};
auto r = p + q;     // geo::operator+ found by ADL
print(r);           // geo::print found by ADL

using std::swap;    // the customary idiom
swap(p, q);         // calls a swap in geo if there is one, otherwise std::swap

A friend function defined only inside a class can be found only by ADL. Such a hidden friend does not add to the overload set of ordinary lookup.

Kinds of module unit

// greet.cppm
module;                         // global module fragment: for #include only
#include <cstdio>

export module greet;            // primary module interface unit

import <string>;

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

export namespace lib {
    int version();
}

// greet.cpp
module greet;                   // an implementation unit

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

// main.cpp
import greet;

int main() { return lib::version(); }

export

export makes a declaration part of the module’s interface [module.interface]. It may be used on a single declaration, on a namespace, or on a block. It can appear only in a module interface unit, and cannot be used on anything with internal linkage. A name that is not exported has module linkage: it is visible to the module’s other units but not to importers.

export int add(int a, int b);
export class Widget { };
export { void one(); void two(); }
export namespace api { void three(); }
export import other;            // re-exports another module

import

An import declaration [module.import] appears only at global namespace scope. In a module unit, every import must come before all other declarations, directly after the module declaration.

An import does not bring in macros from a named module. Importing a module does not bring names into scope by itself: exported names are just visible to lookup, in their own namespaces.

Module fragments

• Global module fragment. module; at the start of the file, before the module declaration. It may contain only preprocessing directives, and is how legacy #includes reach a module unit [module.global.frag].
• Private module fragment. module :private; at the end of a primary interface unit. Its content is not reachable from importers, so it cannot affect them. A unit with a private fragment must be the only unit of its module [module.private.frag].

Visibility and reachability

A visible declaration can be found by name. A reachable declaration is one whose semantic properties, such as the definition of a class, are available [module.reach]. An exported function can return a type that is not exported. The caller then cannot name the type but can use it through auto.

Header units

import <header>; or import "header"; imports a header compiled as a header unit [module.import]. Unlike a named module, a header unit exports its macros. Unlike #include, it does not see the macros of the file that imports it. Which headers can be imported this way is implementation-defined, apart from the standard C++ library headers [headers].

Module file forms

The standard does not define a file extension for modules. Compilers have settled on these conventions:

A compiled interface is a binary file private to one compiler, and generally to its version and options. It is not a distribution format. A module interface must be built before any translation unit that imports it, so a build system has to scan sources for their import dependencies first.