Lines Matching full:module
80 …module import behaves quite differently from the corresponding ``#include <stdio.h>``: when the co…
83 …``std.io`` module is only compiled once, and importing the module into a translation unit is a con…
85 * **Fragility**: Each module is parsed as a standalone entity, so it has a consistent preprocessor …
87 …module as a representation of that API. Because modules can only be built standalone, tools can re…
91 Many programming languages have a module or package system, and because of the variety of features …
97 … Thus, a struct declared in one module will still conflict with a struct of the same name declared…
99 … expose the full complexity of the language. Maintaining a stable binary module format across arch…
112 …bjective-C provides syntax for importing a module via an *@import declaration*, which imports the …
118 …module (which would contain, e.g., the entire C or C++ standard library) and make its API availabl…
132 …s automatically translate ``#include`` directives into the corresponding module import. For exampl…
138 will be automatically mapped to an import of the module ``std.io``. Even with specific ``import`` s…
142 …module with a definition of some entity (say, a ``struct Point``) and then parsing a header contai…
144 While building a module, ``#include_next`` is also supported, with one caveat.
148 Because files listed in module maps are not found through include paths, a
153 If this search finds a file named by a module map, the ``#include_next``
157 Module maps
159 …module map*, which describes how a collection of existing headers maps on to the (logical) structu…
161 Module maps are specified as separate files (each named ``module.modulemap``) alongside the headers…
165 …module maps for the underlying C standard library and the libraries and headers on which it depend…
167 …module maps without modules to check the integrity of the use of header files. To do this, use the…
171 …module is imported (e.g., by an ``#include`` of one of the module's headers), the compiler will sp…
173 …module cache*. Imports of a module will first query the module cache and, if a binary representati…
175 …ere part of the module build. If any of those headers changes, or if any of the modules on which a…
182 ``-fbuiltin-module-map``
183 …Load the Clang builtins module map file. (Equivalent to ``-fmodule-map-file=<resource dir>/include…
185 ``-fimplicit-module-maps``
186 …module map files named ``module.modulemap`` and similar. This option is implied by ``-fmodules``. …
195 …iate module variant. Use this for macros defined on the command line that don't affect how modules…
198 …een attempts to prune the module cache. Module cache pruning attempts to clear out old, unused mod…
201 …module cache must be unused (according to access time) before module pruning will remove it. The d…
203 ``-module-file-info <module file name>``
204 …mation about a given module file (with a ``.pcm`` extension), including the language and preproces…
207 Enable checking of module ``use`` declarations.
209 ``-fmodule-name=module-id``
210 Consider a source file as a part of the given module.
213 …Load the given module map file if a header from its directory or one of its subdirectories is load…
216 …module maps but not imported for symbols, so the error message can reference the module by name. …
222 Specify the mapping of module names to precompiled module files. If the
223 name is omitted, then the module file is loaded whether actually required
225 prebuilt module search mechanism (in addition to ``-fprebuilt-module-path``)
226 and the module is only loaded if required. Note that in this case the
227 specified file also overrides this module's paths that might be embedded
228 in other precompiled module files.
230 ``-fprebuilt-module-path=<directory>``
231 …l look for modules in this directory for a given top-level module name. We don't need a module map…
234 Enable prebuilt implicit modules. If a prebuilt module is not found in the
235 prebuilt modules paths (specified via ``-fprebuilt-module-path``), we will
236 look for a matching implicit module in the prebuilt modules paths.
243 module in an implicit build. This includes things such as header search paths
279 /* module.modulemap */
280 module A {
283 module B {
289 …module-map-file=`` or ``-fimplicit-module-maps`` options explicitly. When using the clang driver, …
296 clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A
297 …clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fmodule-file…
298 …clang -cc1 -emit-obj use.c -fmodules -fmodule-map-file=module.modulemap -fmodule-file=A=prebuilt/A…
300 …o use the ``-fprebuilt-module-path`` option. Let's also use ``-fimplicit-module-maps`` instead of …
305 clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A
306 …clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fprebuilt-mo…
307 clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt
309 …le in one command is to generate implicit modules while using the ``-fdisable-module-hash`` option.
314 …lang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable…
323 …clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -DENAB…
329 … prebuilt modules. We can do so using a manual module mapping, or pointing to a different prebuilt…
334 …lang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable…
335 …ang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt_a -fdisabl…
336 clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt
337 …clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt_a -DEN…
340 …module versions manually, we can build implicit modules in a given cache path (using ``-fmodules-c…
345 clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt
346 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt…
352 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
353 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
355 …for configurations that were not prebuilt. When using the clang driver a module cache path is impl…
359 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
360 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
361 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
363 …iants of modules can be prepared and reused. The options configuring the module cache are independ…
365 Module Semantics
368 Modules are modeled as if each submodule were a separate translation unit, and a module import make…
372 …module with submodules. Entities within a submodule that has already been built are visible when b…
380 If any submodule of a module is imported into any part of a program, the entire top-level module is…
397 * ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
401 Module Map Language
406 The module map language is not currently guaranteed to be stable between major revisions of Clang.
408 The module map language describes the mapping from header files to the
410 a module, one must write a ``module.modulemap`` file for that library. The
411 ``module.modulemap`` file is placed alongside the header files themselves,
412 and is written in the module map language described below.
415 For compatibility with previous releases, if a module map file named
416 ``module.modulemap`` is not found, Clang will also search for a file named
417 ``module.map``. This behavior is deprecated and we plan to eventually
420 As an example, the module map file for the C standard library might look a bit like this:
424 module std [system] [extern_c] {
425 module assert {
431 module complex {
436 module ctype {
441 module errno {
447 module fenv {
455 Here, the top-level module ``std`` encompasses the whole C standard library. It has a number of sub…
459 Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, token…
467 ``extern`` ``module`` ``use``
470 Module map file
472 A module map file consists of a series of module declarations:
476 *module-map-file*:
477 *module-declaration**
479 Within a module map file, modules are referred to by a *module-id*, which uses periods to separate …
483 *module-id*:
486 Module declaration
488 A module declaration describes a module, including the headers that contribute to that module, its …
492 *module-declaration*:
493 …``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *…
494 ``extern`` ``module`` *module-id* *string-literal*
496 The *module-id* should consist of only a single *identifier*, which provides the name of the module…
498 …module that is nested within another module. The contents of explicit submodules are only made ava…
500 …module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on macOS …
505 Modules/module.modulemap Module map for the framework
512 …module is a system module. When a system module is rebuilt, all of the module's headers will be co…
514 …module contains C code that can be used from within C++. When such a module is built for use in C+…
516 …module can only reach non-modular headers and headers from used modules. Since some headers could …
522 *module-member*:
534 An extern module references a module defined by the *module-id* in a file given by the *string-lite…
538 …tion* specifies the requirements that an importing translation unit must satisfy to use the module.
551 …module. When building a module for use by a compilation, submodules requiring unavailable features…
612 **Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requ…
616 module std {
619 module vector {
624 module type_traits {
632 A header declaration specifies that a particular header is associated with the enclosing module.
648 …al`` specifies a header that contributes to the enclosing module. Specifically, when the module is…
656 about headers not covered by the umbrella header or the module map.
658 A header with the ``private`` specifier may not be included from outside the module itself.
660 A header with the ``textual`` specifier will not be compiled when the module is
662 directive. However, it is considered to be part of the module for the purpose
665 token sequence within the prebuilt module representation.
667 …module. It will not be included when the module is built, nor will it be considered to be part of …
673 module std [system] {
687 ``stat`` every header referenced by a module map. It is recommended that
688 *header-attr*\s only be used in machine-generated module maps, to avoid
693 … specifies that all of the headers in the specified directory should be included within the module.
700 … directory. When the module is built, all of the header files in that directory (and its subdirect…
711 Submodule declarations describe modules that are nested within their enclosing module.
716 *module-declaration*
719 …tion* that is a *module-declaration* is a nested module. If the *module-declaration* has a ``frame…
721 … a set of submodules that correspond to any headers that are part of the module but are not explic…
726 …``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred…
731 …module containing an *inferred-submodule-declaration* shall have either an umbrella header or an u…
733 …y a *header-declaration*, a module declaration is implicitly generated from the *inferred-submodul…
743 …f the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
747 module MyLib {
749 explicit module * {
754 is equivalent to the (more verbose) module map:
758 module MyLib {
759 explicit module A {
764 explicit module B {
772 …specifies which imported modules will automatically be re-exported as part of a given module's API.
777 ``export`` *wildcard-module-id*
779 *wildcard-module-id*:
782 *identifier* '.' *wildcard-module-id*
784 …module or a set of modules that will be re-exported to any translation unit that imports the enclo…
790 module MyLib {
791 module Base {
795 module Derived {
805 module MyLib {
806 module Base {
810 module Derived {
820 ``#include`` directives are automatically mapped to module imports,
822 provided by the C preprocessor, e.g., importing a given module
830 An *export-as-declaration* specifies that the current module will have
831 its interface re-exported by the named module.
838 The *export-as-declaration* names the module that the current
839 module will be re-exported through. Only top-level modules
840 can be re-exported, and any given module may only be re-exported
841 through a single module.
843 **Example:** In the following example, the module ``MyFrameworkCore``
844 will be re-exported via the module ``MyFramework``:
848 module MyFrameworkCore {
854 A *use-declaration* specifies another module that the current top-level module
855 intends to use. When the option *-fmodules-decluse* is specified, a module can
861 ``use`` *module-id*
867 module A {
871 module B {
875 module C {
880 When compiling a source file that implements a module, use the option
881 ``-fmodule-name=module-id`` to indicate that the source file is logically part
882 of that module.
884 The compiler at present only applies restrictions to the module directly being built.
888 …y or framework against which a program should be linked if the enclosing module is imported in any…
908 …* specifies the set of configuration macros that have an effect on the API of the enclosing module.
918 …ro. The compiler is required to maintain different variants of the given module for differing defi…
920 …ion* shall only be present on a top-level module, i.e., a module that is not nested within an encl…
922 …ve, meaning that no other macro definition is intended to have an effect on the API of that module.
928 completely when building the module. As an optimization, the
929 compiler could reduce the number of unique module variants by not
933 A translation unit shall not import the same module under different definitions of the configuratio…
947 module MyLogger {
959 ``conflict`` *module-id* ',' *string-literal*
961 …module-id* of the *conflict-declaration* specifies the module with which the enclosing module conf…
968 when a module conflict is discovered.
974 module Conflicts {
975 explicit module A {
980 module B {
1000 Private Module Map Files
1002 Module map files are typically named ``module.modulemap`` and live
1004 the headers they describe. These module maps typically describe all of
1013 express this with a single module map file in the library:
1017 module Foo {
1022 module Foo_Private {
1029 module map file could be customized based on whether
1033 Private module map files, which are named ``module.private.modulemap``
1035 augment the primary module map file with an additional modules. For
1036 example, we would split the module map file above into two module map
1041 /* module.modulemap */
1042 module Foo {
1046 /* module.private.modulemap */
1047 module Foo_Private {
1052 When a ``module.private.modulemap`` file is found alongside a
1053 ``module.modulemap`` file, it is loaded after the ``module.modulemap``
1054 file. In our example library, the ``module.private.modulemap`` file
1059 When writing a private module as part of a *framework*, it's recommended that:
1061 * Headers for this module are present in the ``PrivateHeaders`` framework
1063 * The private module is defined as a *top level module* with the name of the
1070 … needs to introduce module maps for software libraries starting at the bottom of the stack. This t…
1072 …module maps will be written using the `module map language`_, which provides the tools necessary t…
1084 …Unfortunately, when modules compiles all of the C library headers together into a single module, o…
1090 …ht order. With modules, the headers of a particular module will be parsed in isolation, so the mod…
1093 …splitting it into separate headers, one per actual API) or simply ``exclude`` it in the module map.
1101 **Detect unused module imports**
1102 …ectives, it should be fairly simple to track whether a directly-imported module has ever been used…
1105 … been included. Clang can detect such cases and auto-import the required module, but should provid…
1108 … of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.
1114 ``clang/lib/Headers/module.modulemap``
1115 Module map for Clang's compiler-specific header files.
1120 ``clang/include/clang/Basic/Module.h``
1121 …The ``Module`` class in this header describes a module, and is used throughout the compiler to imp…
1124 …ribes the full module map, consisting of all of the module map files that have been parsed, and pr…