The module map language describes the mapping from header files to the logical structure of modules. To enable support for using a library as a module, one must write a module.modulemap file for that library. The module.modulemap file is placed alongside the header files themselves, and is written in the module map language described below.
As an example, the module map file for the C standard library might look a bit like this:
Here, the top-level module std encompasses the whole C standard library. It has a number of submodules containing different parts of the standard library: complex for complex numbers, ctype for character types, etc. Each submodule lists one of more headers that provide the contents for that submodule. Finally, the export * command specifies that anything included by that submodule will be automatically re-exported.
Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, tokens, string literals, /* */ and // comments. The module map language has the following reserved words; all other C identifiers are valid identifiers.
Module map file¶config_macrosexport_asprivateconflictframeworkrequiresexcludeheadertextualexplicitlinkumbrellaexternmoduleuseexport
A module map file consists of a series of module declarations:
module-map-file: module-declaration*
Within a module map file, modules are referred to by a module-id, which uses periods to separate each part of a moduleâs name:
module-id:
identifier ('.' identifier)*Module declaration¶
A module declaration describes a module, including the headers that contribute to that module, its submodules, and other aspects of the module.
module-declaration:explicitoptframeworkoptmodulemodule-id attributesopt '{' module-member* '}'externmodulemodule-id string-literal
The module-id should consist of only a single identifier, which provides the name of the module being defined. Each module shall have a single definition.
The explicit qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module.
The framework qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on macOS and iOS) is contained entirely in directory Name.framework, where Name is the name of the framework (and, therefore, the name of the module). That directory has the following layout:
Name.framework/ Modules/module.modulemap Module map for the framework Headers/ Subdirectory containing framework headers PrivateHeaders/ Subdirectory containing framework private headers Frameworks/ Subdirectory containing embedded frameworks Resources/ Subdirectory containing additional resources Name Symbolic link to the shared library for the framework
The system attribute specifies that the module is a system module. When a system module is rebuilt, all of the moduleâs headers will be considered system headers, which suppresses warnings. This is equivalent to placing #pragma GCC system_header in each of the moduleâs headers. The form of attributes is described in the section Attributes, below.
The extern_c attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the moduleâs headers will be treated as if they were contained within an implicit extern "C" block. An import for a module with this attribute can appear within an extern "C" block. No other restrictions are lifted, however: the module currently cannot be imported within an extern "C" block in a namespace.
The no_undeclared_includes attribute specifies that the module can only reach non-modular headers and headers from used modules. Since some headers could be present in more than one search path and map to different modules in each path, this mechanism helps clang to find the right header, i.e., prefer the one for the current module or in a submodule instead of the first usual match in the search paths.
Modules can have a number of different kinds of members, each of which is described below:
module-member: requires-declaration header-declaration umbrella-dir-declaration submodule-declaration export-declaration export-as-declaration use-declaration link-declaration config-macros-declaration conflict-declaration
An extern module references a module defined by the module-id in a file given by the string-literal. The file can be referenced either by an absolute path or by a path relative to the current map file.
Requires declaration¶A requires-declaration specifies the requirements that an importing translation unit must satisfy to use the module.
requires-declaration:requiresfeature-list feature-list: feature (',' feature)* feature:!opt identifier
The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects, platforms, environments and target specific features. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. When building a module for use by a compilation, submodules requiring unavailable features are ignored. The optional ! indicates that a feature is incompatible with the module.
The following features are defined:
The target supports AltiVec.
The âblocksâ language feature is available.
Support for the coroutines TS is available.
C++ support is available.
C++11 support is available.
C++14 support is available.
C++17 support is available.
C99 support is available.
C11 support is available.
C17 support is available.
A freestanding environment is available.
GNU inline ASM is available.
Objective-C support is available.
Objective-C Automatic Reference Counting (ARC) is available
OpenCL is available
Thread local storage is available.
A specific target feature (e.g., sse4, avx, neon) is available.
A os/platform variant (e.g. freebsd, win32, windows, linux, ios, macos, iossimulator) is available.
A environment variant (e.g. gnu, gnueabi, android, msvc) is available.
Example: The std module can be extended to also include C++ and C++11 headers using a requires-declaration:
module std {
// C standard library...
module vector {
requires cplusplus
header "vector"
}
module type_traits {
requires cplusplus11
header "type_traits"
}
}
Umbrella directory declaration¶
An umbrella directory declaration specifies that all of the headers in the specified directory should be included within the module.
umbrella-dir-declaration:
umbrella string-literal
The string-literal refers to a directory. When the module is built, all of the header files in that directory (and its subdirectories) are included in the module.
An umbrella-dir-declaration shall not refer to the same directory as the location of an umbrella header-declaration. In other words, only a single kind of umbrella can be specified for a given directory.
Note
Umbrella directories are useful for libraries that have a large number of headers but do not have an umbrella header.
Submodule declaration¶Submodule declarations describe modules that are nested within their enclosing module.
submodule-declaration: module-declaration inferred-submodule-declaration
A submodule-declaration that is a module-declaration is a nested module. If the module-declaration has a framework specifier, the enclosing module shall have a framework specifier; the submoduleâs contents shall be contained within the subdirectory Frameworks/SubName.framework, where SubName is the name of the submodule.
A submodule-declaration that is an inferred-submodule-declaration describes a set of submodules that correspond to any headers that are part of the module but are not explicitly described by a header-declaration.
inferred-submodule-declaration:explicitoptframeworkoptmodule'*' attributesopt '{' inferred-submodule-member* '}' inferred-submodule-member:export'*'
A module containing an inferred-submodule-declaration shall have either an umbrella header or an umbrella directory. The headers to which the inferred-submodule-declaration applies are exactly those headers included by the umbrella header (transitively) or included in the module because they reside within the umbrella directory (or its subdirectories).
For each header included by the umbrella header or in the umbrella directory that is not named by a header-declaration, a module declaration is implicitly generated from the inferred-submodule-declaration. The module will:
Have the same name as the header (without the file extension)
Have the explicit specifier, if the inferred-submodule-declaration has the explicit specifier
Have the framework specifier, if the inferred-submodule-declaration has the framework specifier
Have the attributes specified by the inferred-submodule-declaration
Contain a single header-declaration naming that header
Contain a single export-declaration export *, if the inferred-submodule-declaration contains the inferred-submodule-member export *
Example: If the subdirectory âMyLibâ contains the headers A.h and B.h, then the following module map:
module MyLib {
umbrella "MyLib"
explicit module * {
export *
}
}
is equivalent to the (more verbose) module map:
module MyLib {
explicit module A {
header "A.h"
export *
}
explicit module B {
header "B.h"
export *
}
}
Export declaration¶
An export-declaration specifies which imported modules will automatically be re-exported as part of a given moduleâs API.
export-declaration:
export wildcard-module-id
wildcard-module-id:
identifier
'*'
identifier '.' wildcard-module-id
The export-declaration names a module or a set of modules that will be re-exported to any translation unit that imports the enclosing module. Each imported module that matches the wildcard-module-id up to, but not including, the first * will be re-exported.
Example: In the following example, importing MyLib.Derived also provides the API for MyLib.Base:
module MyLib {
module Base {
header "Base.h"
}
module Derived {
header "Derived.h"
export Base
}
}
Note that, if Derived.h includes Base.h, one can simply use a wildcard export to re-export everything Derived.h includes:
module MyLib {
module Base {
header "Base.h"
}
module Derived {
header "Derived.h"
export *
}
}
Note
The wildcard export syntax export * re-exports all of the modules that were imported in the actual header file. Because #include directives are automatically mapped to module imports, export * provides the same transitive-inclusion behavior provided by the C preprocessor, e.g., importing a given module implicitly imports all of the modules on which it depends. Therefore, liberal use of export * provides excellent backward compatibility for programs that rely on transitive inclusion (i.e., all of them).
An export-as-declaration specifies that the current module will have its interface re-exported by the named module.
export-as-declaration:
export_as identifier
The export-as-declaration names the module that the current module will be re-exported through. Only top-level modules can be re-exported, and any given module may only be re-exported through a single module.
Example: In the following example, the module MyFrameworkCore will be re-exported via the module MyFramework:
module MyFrameworkCore {
export_as MyFramework
}
Use declaration¶
A use-declaration specifies another module that the current top-level module intends to use. When the option -fmodules-decluse is specified, a module can only use other modules that are explicitly specified in this way.
use-declaration:
use module-id
Example: In the following example, use of A from C is not declared, so will trigger a warning.
module A {
header "a.h"
}
module B {
header "b.h"
}
module C {
header "c.h"
use B
}
When compiling a source file that implements a module, use the option -fmodule-name=module-id to indicate that the source file is logically part of that module.
The compiler at present only applies restrictions to the module directly being built.
Link declaration¶A link-declaration specifies a library or framework against which a program should be linked if the enclosing module is imported in any translation unit in that program.
link-declaration:linkframeworkopt string-literal
The string-literal specifies the name of the library or framework against which the program should be linked. For example, specifying âclangBasicâ would instruct the linker to link with -lclangBasic for a Unix-style linker.
A link-declaration with the framework specifies that the linker should link against the named framework, e.g., with -framework MyFramework.
Note
Automatic linking with the link directive is not yet widely implemented, because it requires support from both the object file format and the linker. The notion is similar to Microsoft Visual Studioâs #pragma comment(lib...).
The config-macros-declaration specifies the set of configuration macros that have an effect on the API of the enclosing module.
config-macros-declaration:
config_macros attributesopt config-macro-listopt
config-macro-list:
identifier (',' identifier)*
Each identifier in the config-macro-list specifies the name of a macro. The compiler is required to maintain different variants of the given module for differing definitions of any of the named macros.
A config-macros-declaration shall only be present on a top-level module, i.e., a module that is not nested within an enclosing module.
The exhaustive attribute specifies that the list of macros in the config-macros-declaration is exhaustive, meaning that no other macro definition is intended to have an effect on the API of that module.
Note
The exhaustive attribute implies that any macro definitions for macros not listed as configuration macros should be ignored completely when building the module. As an optimization, the compiler could reduce the number of unique module variants by not considering these non-configuration macros. This optimization is not yet implemented in Clang.
A translation unit shall not import the same module under different definitions of the configuration macros.
Note
Clang implements a weak form of this requirement: the definitions used for configuration macros are fixed based on the definitions provided by the command line. If an import occurs and the definition of any configuration macro has changed, the compiler will produce a warning (under the control of -Wconfig-macros).
Example: A logging library might provide different API (e.g., in the form of different definitions for a logging macro) based on the NDEBUG macro setting:
module MyLogger {
umbrella header "MyLogger.h"
config_macros [exhaustive] NDEBUG
}
Conflict declarations¶
A conflict-declaration describes a case where the presence of two different modules in the same translation unit is likely to cause a problem. For example, two modules may provide similar-but-incompatible functionality.
conflict-declaration:
conflict module-id ',' string-literal
The module-id of the conflict-declaration specifies the module with which the enclosing module conflicts. The specified module shall not have been imported in the translation unit when the enclosing module is imported.
The string-literal provides a message to be provided as part of the compiler diagnostic when two modules conflict.
Note
Clang emits a warning (under the control of -Wmodule-conflict) when a module conflict is discovered.
Example:
module Conflicts {
explicit module A {
header "conflict_a.h"
conflict B, "we just don't like B"
}
module B {
header "conflict_b.h"
}
}
Attributes¶
Attributes are used in a number of places in the grammar to describe specific behavior of other declarations. The format of attributes is fairly simple.
attributes: attribute attributesopt attribute: '[' identifier ']'
Any identifier can be used as an attribute, and each declaration specifies what attributes can be applied to it.
Private Module Map Files¶Module map files are typically named module.modulemap and live either alongside the headers they describe or in a parent directory of the headers they describe. These module maps typically describe all of the API for the library.
However, in some cases, the presence or absence of particular headers is used to distinguish between the âpublicâ and âprivateâ APIs of a particular library. For example, a library may contain the headers Foo.h and Foo_Private.h, providing public and private APIs, respectively. Additionally, Foo_Private.h may only be available on some versions of library, and absent in others. One cannot easily express this with a single module map file in the library:
module Foo {
header "Foo.h"
...
}
module Foo_Private {
header "Foo_Private.h"
...
}
because the header Foo_Private.h wonât always be available. The module map file could be customized based on whether Foo_Private.h is available or not, but doing so requires custom build machinery.
Private module map files, which are named module.private.modulemap (or, for backward compatibility, module_private.map), allow one to augment the primary module map file with an additional modules. For example, we would split the module map file above into two module map files:
/* module.modulemap */
module Foo {
header "Foo.h"
}
/* module.private.modulemap */
module Foo_Private {
header "Foo_Private.h"
}
When a module.private.modulemap file is found alongside a module.modulemap file, it is loaded after the module.modulemap file. In our example library, the module.private.modulemap file would be available when Foo_Private.h is available, making it easier to split a libraryâs public and private APIs along header boundaries.
When writing a private module as part of a framework, itâs recommended that:
Headers for this module are present in the PrivateHeaders framework subdirectory.
The private module is defined as a top level module with the name of the public framework prefixed, like Foo_Private above. Clang has extra logic to work with this naming, using FooPrivate or Foo.Private (submodule) trigger warnings and might not work as expected.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4