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…
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``
152 Module maps
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 ``-fimplicit-module-maps``
178 …module map files named ``module.modulemap`` and similar. This option is implied by ``-fmodules``. …
187 …iate module variant. Use this for macros defined on the command line that don't affect how modules…
190 …een attempts to prune the module cache. Module cache pruning attempts to clear out old, unused mod…
193 …module cache must be unused (according to access time) before module pruning will remove it. The d…
195 ``-module-file-info <module file name>``
196 …mation about a given module file (with a ``.pcm`` extension), including the language and preproces…
199 Enable checking of module ``use`` declarations.
201 ``-fmodule-name=module-id``
202 Consider a source file as a part of the given module.
205 …Load the given module map file if a header from its directory or one of its subdirectories is load…
208 …module maps but not imported for symbols, so the error message can reference the module by name. …
214 Load the given precompiled module file.
216 Module Semantics
219 Modules are modeled as if each submodule were a separate translation unit, and a module import make…
223 …module with submodules. Entities within a submodule that has already been built are visible when b…
231 If any submodule of a module is imported into any part of a program, the entire top-level module is…
248 * ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
252 Module Map Language
257 The module map language is not currently guaranteed to be stable between major revisions of Clang.
259 The module map language describes the mapping from header files to the
261 a module, one must write a ``module.modulemap`` file for that library. The
262 ``module.modulemap`` file is placed alongside the header files themselves,
263 and is written in the module map language described below.
266 For compatibility with previous releases, if a module map file named
267 ``module.modulemap`` is not found, Clang will also search for a file named
268 ``module.map``. This behavior is deprecated and we plan to eventually
271 As an example, the module map file for the C standard library might look a bit like this:
275 module std [system] [extern_c] {
276 module assert {
282 module complex {
287 module ctype {
292 module errno {
298 module fenv {
306 Here, the top-level module ``std`` encompasses the whole C standard library. It has a number of sub…
310 Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, token…
318 ``extern`` ``module`` ``use``
320 Module map file
322 A module map file consists of a series of module declarations:
326 *module-map-file*:
327 *module-declaration**
329 Within a module map file, modules are referred to by a *module-id*, which uses periods to separate …
333 *module-id*:
336 Module declaration
338 A module declaration describes a module, including the headers that contribute to that module, its …
342 *module-declaration*:
343 …``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *…
344 ``extern`` ``module`` *module-id* *string-literal*
346 The *module-id* should consist of only a single *identifier*, which provides the name of the module…
348 …module that is nested within another module. The contents of explicit submodules are only made ava…
350 …module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on Mac OS…
355 Modules/module.modulemap Module map for the framework
361 …module is a system module. When a system module is rebuilt, all of the module's headers will be co…
363 …module contains C code that can be used from within C++. When such a module is built for use in C+…
369 *module-member*:
380 An extern module references a module defined by the *module-id* in a file given by the *string-lite…
384 …tion* specifies the requirements that an importing translation unit must satisfy to use the module.
397 …nslation unit shall not import the module. The optional ``!`` indicates that a feature is incompat…
429 **Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requ…
433 module std {
436 module vector {
441 module type_traits {
449 A header declaration specifies that a particular header is associated with the enclosing module.
458 …al`` specifies a header that contributes to the enclosing module. Specifically, when the module is…
466 about headers not covered by the umbrella header or the module map.
468 A header with the ``private`` specifier may not be included from outside the module itself.
470 A header with the ``textual`` specifier will not be compiled when the module is
472 directive. However, it is considered to be part of the module for the purpose
475 token sequence within the prebuilt module representation.
477 …module. It will not be included when the module is built, nor will it be considered to be part of …
483 module std [system] {
491 … specifies that all of the headers in the specified directory should be included within the module.
498 … directory. When the module is built, all of the header files in that directory (and its subdirect…
509 Submodule declarations describe modules that are nested within their enclosing module.
514 *module-declaration*
517 …tion* that is a *module-declaration* is a nested module. If the *module-declaration* has a ``frame…
519 … a set of submodules that correspond to any headers that are part of the module but are not explic…
524 …``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred…
529 …module containing an *inferred-submodule-declaration* shall have either an umbrella header or an u…
531 …y a *header-declaration*, a module declaration is implicitly generated from the *inferred-submodul…
541 …f the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
545 module MyLib {
547 explicit module * {
552 is equivalent to the (more verbose) module map:
556 module MyLib {
557 explicit module A {
562 explicit module B {
570 …specifies which imported modules will automatically be re-exported as part of a given module's API.
575 ``export`` *wildcard-module-id*
577 *wildcard-module-id*:
580 *identifier* '.' *wildcard-module-id*
582 …module or a set of modules that will be re-exported to any translation unit that imports the enclo…
588 module MyLib {
589 module Base {
593 module Derived {
603 module MyLib {
604 module Base {
608 module Derived {
618 ``#include`` directives are automatically mapped to module imports,
620 provided by the C preprocessor, e.g., importing a given module
628 A *use-declaration* specifies another module that the current top-level module
629 intends to use. When the option *-fmodules-decluse* is specified, a module can
635 ``use`` *module-id*
641 module A {
645 module B {
649 module C {
654 When compiling a source file that implements a module, use the option
655 ``-fmodule-name=module-id`` to indicate that the source file is logically part
656 of that module.
658 The compiler at present only applies restrictions to the module directly being built.
662 …y or framework against which a program should be linked if the enclosing module is imported in any…
682 …* specifies the set of configuration macros that have an effect on the API of the enclosing module.
692 …ro. The compiler is required to maintain different variants of the given module for differing defi…
694 …ion* shall only be present on a top-level module, i.e., a module that is not nested within an encl…
696 …e, meaning that no other macro definition is intended to have an effect on the API of that module.
702 completely when building the module. As an optimization, the
703 compiler could reduce the number of unique module variants by not
707 A translation unit shall not import the same module under different definitions of the configuratio…
721 module MyLogger {
733 ``conflict`` *module-id* ',' *string-literal*
735 …module-id* of the *conflict-declaration* specifies the module with which the enclosing module conf…
742 when a module conflict is discovered.
748 module Conflicts {
749 explicit module A {
754 module B {
774 Private Module Map Files
776 Module map files are typically named ``module.modulemap`` and live
778 the headers they describe. These module maps typically describe all of
787 express this with a single module map file in the library:
791 module Foo {
794 explicit module Private {
801 module map file could be customized based on whether
805 Private module map files, which are named ``module.private.modulemap``
807 augment the primary module map file with an additional submodule. For
808 example, we would split the module map file above into two module map
813 /* module.modulemap */
814 module Foo {
818 /* module.private.modulemap */
819 explicit module Foo.Private {
824 When a ``module.private.modulemap`` file is found alongside a
825 ``module.modulemap`` file, it is loaded after the ``module.modulemap``
826 file. In our example library, the ``module.private.modulemap`` file
833 … needs to introduce module maps for software libraries starting at the bottom of the stack. This t…
835 …module maps will be written using the `module map language`_, which provides the tools necessary t…
847 …Unfortunately, when modules compiles all of the C library headers together into a single module, o…
853 …ht order. With modules, the headers of a particular module will be parsed in isolation, so the mod…
856 …splitting it into separate headers, one per actual API) or simply ``exclude`` it in the module map.
864 **Detect unused module imports**
865 …ectives, it should be fairly simple to track whether a directly-imported module has ever been used…
868 … been included. Clang can detect such cases and auto-import the required module, but should provid…
871 … of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.
877 ``clang/lib/Headers/module.modulemap``
878 Module map for Clang's compiler-specific header files.
883 ``clang/include/clang/Basic/Module.h``
884 …The ``Module`` class in this header describes a module, and is used throughout the compiler to imp…
887 …ribes the full module map, consisting of all of the module map files that have been parsed, and pr…