Lines Matching +refs:parsed +refs:module +refs:requires
80 …module import behaves quite differently from the corresponding ``#include <stdio.h>``: when the co…
83 …module is only compiled once, and importing the module into a translation unit is a constant-time …
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 …
109 .. parsed-literal::
113 …module (which would contain, e.g., the entire C or C++ standard library) and make its API availabl…
115 .. parsed-literal::
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…
233 module in an implicit build. This includes things such as header search paths
241 Modules are modeled as if each submodule were a separate translation unit, and a module import make…
245 …module with submodules. Entities within a submodule that has already been built are visible when b…
253 If any submodule of a module is imported into any part of a program, the entire top-level module is…
270 * ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
279 The module map language is not currently guaranteed to be stable between major revisions of Clang.
281 The module map language describes the mapping from header files to the
283 a module, one must write a ``module.modulemap`` file for that library. The
284 ``module.modulemap`` file is placed alongside the header files themselves,
285 and is written in the module map language described below.
288 For compatibility with previous releases, if a module map file named
289 ``module.modulemap`` is not found, Clang will also search for a file named
290 ``module.map``. This behavior is deprecated and we plan to eventually
293 As an example, the module map file for the C standard library might look a bit like this:
295 .. parsed-literal::
297 module std [system] [extern_c] {
298 module assert {
304 module complex {
309 module ctype {
314 module errno {
320 module fenv {
328 Here, the top-level module ``std`` encompasses the whole C standard library. It has a number of sub…
332 …identifiers, tokens, string literals, ``/* */`` and ``//`` comments. The module map language has t…
334 .. parsed-literal::
337 ``conflict`` ``framework`` ``requires``
340 ``extern`` ``module`` ``use``
345 A module map file consists of a series of module declarations:
347 .. parsed-literal::
349 *module-map-file*:
350 *module-declaration**
352 Within a module map file, modules are referred to by a *module-id*, which uses periods to separate …
354 .. parsed-literal::
356 *module-id*:
361 A module declaration describes a module, including the headers that contribute to that module, its …
363 .. parsed-literal::
365 *module-declaration*:
366 …``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *…
367 ``extern`` ``module`` *module-id* *string-literal*
369 The *module-id* should consist of only a single *identifier*, which provides the name of the module…
371 …module that is nested within another module. The contents of explicit submodules are only made ava…
373 …module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on macOS …
375 .. parsed-literal::
378 Modules/module.modulemap Module map for the framework
385 …module is a system module. When a system module is rebuilt, all of the module's headers will be co…
387 …module contains C code that can be used from within C++. When such a module is built for use in C+…
389 …module can only reach non-modular headers and headers from used modules. Since some headers could …
393 .. parsed-literal::
395 *module-member*:
396 *requires-declaration*
407 An extern module references a module defined by the *module-id* in a file given by the *string-lite…
411 A *requires-declaration* specifies the requirements that an importing translation unit must satisfy…
413 .. parsed-literal::
415 *requires-declaration*:
416 ``requires`` *feature-list*
424 …module. When building a module for use by a compilation, submodules requiring unavailable features…
485 **Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requ…
487 .. parsed-literal::
489 module std {
492 module vector {
493 requires cplusplus
497 module type_traits {
498 requires cplusplus11
505 A header declaration specifies that a particular header is associated with the enclosing module.
507 .. parsed-literal::
521 …er that contributes to the enclosing module. Specifically, when the module is built, the named hea…
529 about headers not covered by the umbrella header or the module map.
531 A header with the ``private`` specifier may not be included from outside the module itself.
533 A header with the ``textual`` specifier will not be compiled when the module is
535 directive. However, it is considered to be part of the module for the purpose
538 token sequence within the prebuilt module representation.
540 …module. It will not be included when the module is built, nor will it be considered to be part of …
544 .. parsed-literal::
546 module std [system] {
560 ``stat`` every header referenced by a module map. It is recommended that
561 *header-attr*\s only be used in machine-generated module maps, to avoid
566 … specifies that all of the headers in the specified directory should be included within the module.
568 .. parsed-literal::
573 … directory. When the module is built, all of the header files in that directory (and its subdirect…
584 Submodule declarations describe modules that are nested within their enclosing module.
586 .. parsed-literal::
589 *module-declaration*
592 …tion* that is a *module-declaration* is a nested module. If the *module-declaration* has a ``frame…
594 … a set of submodules that correspond to any headers that are part of the module but are not explic…
596 .. parsed-literal::
599 …``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred…
604 …module containing an *inferred-submodule-declaration* shall have either an umbrella header or an u…
606 …y a *header-declaration*, a module declaration is implicitly generated from the *inferred-submodul…
616 …f the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
618 .. parsed-literal::
620 module MyLib {
622 explicit module * {
627 is equivalent to the (more verbose) module map:
629 .. parsed-literal::
631 module MyLib {
632 explicit module A {
637 explicit module B {
645 …specifies which imported modules will automatically be re-exported as part of a given module's API.
647 .. parsed-literal::
650 ``export`` *wildcard-module-id*
652 *wildcard-module-id*:
655 *identifier* '.' *wildcard-module-id*
657 …module or a set of modules that will be re-exported to any translation unit that imports the enclo…
661 .. parsed-literal::
663 module MyLib {
664 module Base {
668 module Derived {
676 .. parsed-literal::
678 module MyLib {
679 module Base {
683 module Derived {
693 ``#include`` directives are automatically mapped to module imports,
695 provided by the C preprocessor, e.g., importing a given module
703 An *export-as-declaration* specifies that the current module will have
704 its interface re-exported by the named module.
706 .. parsed-literal::
711 The *export-as-declaration* names the module that the current
712 module will be re-exported through. Only top-level modules
713 can be re-exported, and any given module may only be re-exported
714 through a single module.
716 **Example:** In the following example, the module ``MyFrameworkCore``
717 will be re-exported via the module ``MyFramework``:
719 .. parsed-literal::
721 module MyFrameworkCore {
727 A *use-declaration* specifies another module that the current top-level module
728 intends to use. When the option *-fmodules-decluse* is specified, a module can
731 .. parsed-literal::
734 ``use`` *module-id*
738 .. parsed-literal::
740 module A {
744 module B {
748 module C {
753 When compiling a source file that implements a module, use the option
754 ``-fmodule-name=module-id`` to indicate that the source file is logically part
755 of that module.
757 The compiler at present only applies restrictions to the module directly being built.
761 …y or framework against which a program should be linked if the enclosing module is imported in any…
763 .. parsed-literal::
775 implemented, because it requires support from both the object file
781 …* specifies the set of configuration macros that have an effect on the API of the enclosing module.
783 .. parsed-literal::
791 …ro. The compiler is required to maintain different variants of the given module for differing defi…
793 …ion* shall only be present on a top-level module, i.e., a module that is not nested within an encl…
795 …e, meaning that no other macro definition is intended to have an effect on the API of that module.
801 completely when building the module. As an optimization, the
802 compiler could reduce the number of unique module variants by not
806 A translation unit shall not import the same module under different definitions of the configuratio…
818 .. parsed-literal::
820 module MyLogger {
829 .. parsed-literal::
832 ``conflict`` *module-id* ',' *string-literal*
834 …module-id* of the *conflict-declaration* specifies the module with which the enclosing module conf…
841 when a module conflict is discovered.
845 .. parsed-literal::
847 module Conflicts {
848 explicit module A {
853 module B {
863 .. parsed-literal::
875 Module map files are typically named ``module.modulemap`` and live
877 the headers they describe. These module maps typically describe all of
886 express this with a single module map file in the library:
888 .. parsed-literal::
890 module Foo {
895 module Foo_Private {
902 module map file could be customized based on whether
903 ``Foo_Private.h`` is available or not, but doing so requires custom
906 Private module map files, which are named ``module.private.modulemap``
908 augment the primary module map file with an additional modules. For
909 example, we would split the module map file above into two module map
914 /* module.modulemap */
915 module Foo {
919 /* module.private.modulemap */
920 module Foo_Private {
925 When a ``module.private.modulemap`` file is found alongside a
926 ``module.modulemap`` file, it is loaded after the ``module.modulemap``
927 file. In our example library, the ``module.private.modulemap`` file
932 When writing a private module as part of a *framework*, it's recommended that:
934 * Headers for this module are present in the ``PrivateHeaders`` framework
936 * The private module is defined as a *top level module* with the name of the
943 … needs to introduce module maps for software libraries starting at the bottom of the stack. This t…
945 …module maps will be written using the `module map language`_, which provides the tools necessary t…
950 .. parsed-literal::
957 …module, only the first actual type definition of ``size_t`` will be visible, and then only in the …
960 …the fix is often simply "don't do that", such problems persist. Modules requires that the conflict…
963 …ht order. With modules, the headers of a particular module will be parsed in isolation, so the mod…
966 …splitting it into separate headers, one per actual API) or simply ``exclude`` it in the module map.
974 **Detect unused module imports**
975 …ectives, it should be fairly simple to track whether a directly-imported module has ever been used…
978 … been included. Clang can detect such cases and auto-import the required module, but should provid…
981 … of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.
987 ``clang/lib/Headers/module.modulemap``
994 …The ``Module`` class in this header describes a module, and is used throughout the compiler to imp…
997 …ribes the full module map, consisting of all of the module map files that have been parsed, and pr…
1002 .. [#] Automatic linking against the libraries of modules requires specific linker support, which i…
1008 .. [#] The preprocessing context in which the modules are parsed is actually dependent on the comma…