Lines Matching refs: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…
107 …bjective-C provides syntax for importing a module via an *@import declaration*, which imports the …
113 …module (which would contain, e.g., the entire C or C++ standard library) and make its API availabl…
127 …s automatically translate ``#include`` directives into the corresponding module import. For exampl…
133 will be automatically mapped to an import of the module ``std.io``. Even with specific ``import`` s…
137 …module with a definition of some entity (say, a ``struct Point``) and then parsing a header contai…
139 While building a module, ``#include_next`` is also supported, with one caveat.
143 Because files listed in module maps are not found through include paths, a
148 If this search finds a file named by a module map, the ``#include_next``
154 …module map*, which describes how a collection of existing headers maps on to the (logical) structu…
156 Module maps are specified as separate files (each named ``module.modulemap``) alongside the headers…
160 …module maps for the underlying C standard library and the libraries and headers on which it depend…
162 …module maps without modules to check the integrity of the use of header files. To do this, use the…
166 …module is imported (e.g., by an ``#include`` of one of the module's headers), the compiler will sp…
168 …module cache*. Imports of a module will first query the module cache and, if a binary representati…
170 …ere part of the module build. If any of those headers changes, or if any of the modules on which a…
177 ``-fbuiltin-module-map``
178 …Load the Clang builtins module map file. (Equivalent to ``-fmodule-map-file=<resource dir>/include…
180 ``-fimplicit-module-maps``
181 …module map files named ``module.modulemap`` and similar. This option is implied by ``-fmodules``. …
190 …iate module variant. Use this for macros defined on the command line that don't affect how modules…
193 …een attempts to prune the module cache. Module cache pruning attempts to clear out old, unused mod…
196 …module cache must be unused (according to access time) before module pruning will remove it. The d…
198 ``-module-file-info <module file name>``
199 …mation about a given module file (with a ``.pcm`` extension), including the language and preproces…
202 Enable checking of module ``use`` declarations.
204 ``-fmodule-name=module-id``
205 Consider a source file as a part of the given module.
208 …Load the given module map file if a header from its directory or one of its subdirectories is load…
211 …module maps but not imported for symbols, so the error message can reference the module by name. …
217 Specify the mapping of module names to precompiled module files. If the
218 name is omitted, then the module file is loaded whether actually required
220 prebuilt module search mechanism (in addition to ``-fprebuilt-module-path``)
221 and the module is only loaded if required. Note that in this case the
222 specified file also overrides this module's paths that might be embedded
223 in other precompiled module files.
225 ``-fprebuilt-module-path=<directory>``
226 …l look for modules in this directory for a given top-level module name. We don't need a module map…
229 Enable prebuilt implicit modules. If a prebuilt module is not found in the
230 prebuilt modules paths (specified via ``-fprebuilt-module-path``), we will
231 look for a matching implicit module in the prebuilt modules paths.
238 module in an implicit build. This includes things such as header search paths
274 /* module.modulemap */
275 module A {
278 module B {
284 …module-map-file=`` or ``-fimplicit-module-maps`` options explicitly. When using the clang driver, …
291 clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A
292 …clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fmodule-file…
293 …clang -cc1 -emit-obj use.c -fmodules -fmodule-map-file=module.modulemap -fmodule-file=A=prebuilt/A…
295 …o use the ``-fprebuilt-module-path`` option. Let's also use ``-fimplicit-module-maps`` instead of …
300 clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A
301 …clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fprebuilt-mo…
302 clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt
304 …le in one command is to generate implicit modules while using the ``-fdisable-module-hash`` option.
309 …lang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable…
318 …clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -DENAB…
324 … prebuilt modules. We can do so using a manual module mapping, or pointing to a different prebuilt…
329 …lang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable…
330 …ang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt_a -fdisabl…
331 clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt
332 …clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt_a -DEN…
335 …module versions manually, we can build implicit modules in a given cache path (using ``-fmodules-c…
340 clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt
341 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt…
347 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
348 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
350 …for configurations that were not prebuilt. When using the clang driver a module cache path is impl…
354 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
355 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
356 …clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebui…
358 …iants of modules can be prepared and reused. The options configuring the module cache are independ…
363 Modules are modeled as if each submodule were a separate translation unit, and a module import make…
367 …module with submodules. Entities within a submodule that has already been built are visible when b…
375 If any submodule of a module is imported into any part of a program, the entire top-level module is…
392 * ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
401 The module map language is not currently guaranteed to be stable between major revisions of Clang.
403 The module map language describes the mapping from header files to the
405 a module, one must write a ``module.modulemap`` file for that library. The
406 ``module.modulemap`` file is placed alongside the header files themselves,
407 and is written in the module map language described below.
410 For compatibility with previous releases, if a module map file named
411 ``module.modulemap`` is not found, Clang will also search for a file named
412 ``module.map``. This behavior is deprecated and we plan to eventually
415 As an example, the module map file for the C standard library might look a bit like this:
419 module std [system] [extern_c] {
420 module assert {
426 module complex {
431 module ctype {
436 module errno {
442 module fenv {
450 Here, the top-level module ``std`` encompasses the whole C standard library. It has a number of sub…
454 …identifiers, tokens, string literals, ``/* */`` and ``//`` comments. The module map language has t…
462 ``extern`` ``module`` ``use``
467 A module map file consists of a series of module declarations:
471 *module-map-file*:
472 *module-declaration**
474 Within a module map file, modules are referred to by a *module-id*, which uses periods to separate …
478 *module-id*:
483 A module declaration describes a module, including the headers that contribute to that module, its …
487 *module-declaration*:
488 …``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *…
489 ``extern`` ``module`` *module-id* *string-literal*
491 The *module-id* should consist of only a single *identifier*, which provides the name of the module…
493 …module that is nested within another module. The contents of explicit submodules are only made ava…
495 …module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on macOS …
500 Modules/module.modulemap Module map for the framework
507 …module is a system module. When a system module is rebuilt, all of the module's headers will be co…
509 …module contains C code that can be used from within C++. When such a module is built for use in C+…
511 …module can only reach non-modular headers and headers from used modules. Since some headers could …
517 *module-member*:
529 An extern module references a module defined by the *module-id* in a file given by the *string-lite…
533 …tion* specifies the requirements that an importing translation unit must satisfy to use the module.
546 …module. When building a module for use by a compilation, submodules requiring unavailable features…
607 **Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requ…
611 module std {
614 module vector {
619 module type_traits {
627 A header declaration specifies that a particular header is associated with the enclosing module.
643 …al`` specifies a header that contributes to the enclosing module. Specifically, when the module is…
651 about headers not covered by the umbrella header or the module map.
653 A header with the ``private`` specifier may not be included from outside the module itself.
655 A header with the ``textual`` specifier will not be compiled when the module is
657 directive. However, it is considered to be part of the module for the purpose
660 token sequence within the prebuilt module representation.
662 …module. It will not be included when the module is built, nor will it be considered to be part of …
668 module std [system] {
682 ``stat`` every header referenced by a module map. It is recommended that
683 *header-attr*\s only be used in machine-generated module maps, to avoid
688 … specifies that all of the headers in the specified directory should be included within the module.
695 … directory. When the module is built, all of the header files in that directory (and its subdirect…
706 Submodule declarations describe modules that are nested within their enclosing module.
711 *module-declaration*
714 …tion* that is a *module-declaration* is a nested module. If the *module-declaration* has a ``frame…
716 … a set of submodules that correspond to any headers that are part of the module but are not explic…
721 …``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred…
726 …module containing an *inferred-submodule-declaration* shall have either an umbrella header or an u…
728 …y a *header-declaration*, a module declaration is implicitly generated from the *inferred-submodul…
738 …f the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
742 module MyLib {
744 explicit module * {
749 is equivalent to the (more verbose) module map:
753 module MyLib {
754 explicit module A {
759 explicit module B {
767 …specifies which imported modules will automatically be re-exported as part of a given module's API.
772 ``export`` *wildcard-module-id*
774 *wildcard-module-id*:
777 *identifier* '.' *wildcard-module-id*
779 …module or a set of modules that will be re-exported to any translation unit that imports the enclo…
785 module MyLib {
786 module Base {
790 module Derived {
800 module MyLib {
801 module Base {
805 module Derived {
815 ``#include`` directives are automatically mapped to module imports,
817 provided by the C preprocessor, e.g., importing a given module
825 An *export-as-declaration* specifies that the current module will have
826 its interface re-exported by the named module.
833 The *export-as-declaration* names the module that the current
834 module will be re-exported through. Only top-level modules
835 can be re-exported, and any given module may only be re-exported
836 through a single module.
838 **Example:** In the following example, the module ``MyFrameworkCore``
839 will be re-exported via the module ``MyFramework``:
843 module MyFrameworkCore {
849 A *use-declaration* specifies another module that the current top-level module
850 intends to use. When the option *-fmodules-decluse* is specified, a module can
856 ``use`` *module-id*
862 module A {
866 module B {
870 module C {
875 When compiling a source file that implements a module, use the option
876 ``-fmodule-name=module-id`` to indicate that the source file is logically part
877 of that module.
879 The compiler at present only applies restrictions to the module directly being built.
883 …y or framework against which a program should be linked if the enclosing module is imported in any…
903 …* specifies the set of configuration macros that have an effect on the API of the enclosing module.
913 …ro. The compiler is required to maintain different variants of the given module for differing defi…
915 …ion* shall only be present on a top-level module, i.e., a module that is not nested within an encl…
917 …e, meaning that no other macro definition is intended to have an effect on the API of that module.
923 completely when building the module. As an optimization, the
924 compiler could reduce the number of unique module variants by not
928 A translation unit shall not import the same module under different definitions of the configuratio…
942 module MyLogger {
954 ``conflict`` *module-id* ',' *string-literal*
956 …module-id* of the *conflict-declaration* specifies the module with which the enclosing module conf…
963 when a module conflict is discovered.
969 module Conflicts {
970 explicit module A {
975 module B {
997 Module map files are typically named ``module.modulemap`` and live
999 the headers they describe. These module maps typically describe all of
1008 express this with a single module map file in the library:
1012 module Foo {
1017 module Foo_Private {
1024 module map file could be customized based on whether
1028 Private module map files, which are named ``module.private.modulemap``
1030 augment the primary module map file with an additional modules. For
1031 example, we would split the module map file above into two module map
1036 /* module.modulemap */
1037 module Foo {
1041 /* module.private.modulemap */
1042 module Foo_Private {
1047 When a ``module.private.modulemap`` file is found alongside a
1048 ``module.modulemap`` file, it is loaded after the ``module.modulemap``
1049 file. In our example library, the ``module.private.modulemap`` file
1054 When writing a private module as part of a *framework*, it's recommended that:
1056 * Headers for this module are present in the ``PrivateHeaders`` framework
1058 * The private module is defined as a *top level module* with the name of the
1065 … needs to introduce module maps for software libraries starting at the bottom of the stack. This t…
1067 …module maps will be written using the `module map language`_, which provides the tools necessary t…
1079 …Unfortunately, when modules compiles all of the C library headers together into a single module, o…
1085 …ht order. With modules, the headers of a particular module will be parsed in isolation, so the mod…
1088 …splitting it into separate headers, one per actual API) or simply ``exclude`` it in the module map.
1096 **Detect unused module imports**
1097 …ectives, it should be fairly simple to track whether a directly-imported module has ever been used…
1100 … been included. Clang can detect such cases and auto-import the required module, but should provid…
1103 … of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.
1109 ``clang/lib/Headers/module.modulemap``
1116 …The ``Module`` class in this header describes a module, and is used throughout the compiler to imp…
1119 …ribes the full module map, consisting of all of the module map files that have been parsed, and pr…