Module Declaration

A C++ module declaration establishes a translation unit as a module unit or a module partition, dictating its linkage, visibility, and reachability boundaries. Introduced in C++20, it replaces the traditional preprocessor-based inclusion model with a semantic, compiler-enforced boundary using the module and export keywords.

The module declaration must be the first declaration in a translation unit, optionally preceded by the global module fragment. Comments and preprocessor directives are resolved prior to the parsing of declarations and do not violate this ordering requirement.

Primary Module Interface Declaration

The primary module interface defines the public surface of a module. A module must have exactly one primary interface translation unit.

export module core.network;

export void connect(); // Visible to importers
void internal_setup(); // Hidden from importers

• The export module keywords designate this file as the primary interface.
• Module names consist of one or more identifiers separated by dots (e.g., core.network). The dots represent logical hierarchy, not physical file paths.

Module Implementation Declaration

A module implementation unit provides the definitions for declarations made in the module interface. It does not export anything and is not imported by consumers.

module core.network;

// Implicitly imports the primary interface of 'core.network'
void internal_setup() {
    // Implementation details
}

• The module keyword (without export) binds this translation unit to the named module.
• Declarations within this unit have module linkage by default, meaning they are visible across the module but hidden from outside translation units.

Module Partitions

A module can be divided into multiple translation units called partitions. A partition name is appended to the module name, separated by a colon (:).

Interface Partition Contributes to the public interface of the module. It must be explicitly exported by the primary module interface.

export module core.network:sockets;

export class Socket { /* ... */ };

Implementation Partition Organizes internal implementation details. It cannot be exported and is only visible to other units within the same module that explicitly import it.

module core.network:buffers;

class BufferManager { /* ... */ };

Global Module Fragment

The global module fragment allows a module unit to include legacy header files without attaching their contents to the module’s named scope or ownership.

module;

#include <vector> // Expands into declarations attached to the global scope
#include <string>

export module core.data;

export std::vector<std::string> process_data();

• Declared using the global module fragment introducer, a syntax construct consisting of the module keyword followed by a semicolon punctuator (module;).
• Can appear at the beginning of any module unit. This includes primary module interfaces, module implementations, module interface partitions, and module implementation partitions.
• It is designed to house preprocessor directives (like #include), which expand into standard C++ declarations that exist prior to the module declaration.

Private Module Fragment

The private module fragment allows a single-file module to hide implementation details from importers without requiring a separate implementation file.

export module math.engine;

export int calculate(int a, int b);

module :private; // Ends the exported interface

// Everything below is unreachable by importers
int calculate(int a, int b) {
    return a + b;
}

• Declared using module :private;.
• Can only be used in a primary module interface unit that does not have separate module implementation units or partitions.

Structural Constraints

1. Global Scope: A module declaration must appear at the global namespace scope. It cannot be nested inside a namespace, class, or function.
2. Singularity: A translation unit can contain at most one module declaration (excluding the module; global fragment and module :private; fragment).
3. Ordering: The module declaration must be the first declaration in the translation unit, except for declarations introduced within the global module fragment.
4. Attributes: The C++ grammar allows an optional attribute specifier sequence on a module declaration. Attributes cannot precede the module or export keywords; they must appear at the end of the declaration, immediately preceding the semicolon. However, the C++ standard strictly restricts standard attributes (such as [[deprecated]] or [[nodiscard]]) to specific entities, and module declarations are not among them. Applying a standard attribute to a module declaration renders the program ill-formed. This syntax exists solely to support implementation-defined (compiler-specific) attributes.

// Correct attribute placement for an implementation-defined attribute.
// Standard attributes like [[deprecated]] are ill-formed here.
export module core.network [[vendor::specific_attribute]];

Master C++ with Deep Grasping Methodology!

Learn More