Lines Matching +full:is +full:- +full:module
10 …is built using a number of software libraries, including libraries supplied by the platform, inter…
12 .. code-block:: c
16 The implementation is handled separately by linking against the appropriate library. For example, b…
18 Modules provide an alternative, simpler way to use software libraries that provides better compile-…
21 -------------------------------
22 The ``#include`` mechanism provided by the C preprocessor is a very poor way to access the API of a…
24 * **Compile-time scalability**: Each time a header is included, the
29 and *M* headers included in each translation unit, the compiler is
31 shared among multiple translation units. C++ is particularly bad,
42 library header: the result is a horrific cascade of failures in the
43 C++ Standard Library's implementation. More subtle real-world
58 barrier to entry for developers coming from non-C languages, are
62 * **Tool confusion**: In a C-based language, it is hard to build tools
67 Objective-C++, or one of the variants of these languages? What
73 ---------------
76 .. code-block:: c
78 import std.io; // pseudo-code; see below for syntax discussion
80 …module import behaves quite differently from the corresponding ``#include <stdio.h>``: when the co…
83 …-time scalability**: The ``std.io`` module is only compiled once, and importing the module into a …
85 …module is parsed as a standalone entity, so it has a consistent preprocessor environment. This com…
87 …module as a representation of that API. Because modules can only be built standalone, tools can re…
90 -----------------------------
91 …module or package system, and because of the variety of features provided by these languages it is…
93 …ld's code**: It is not realistic to require applications or software libraries to make drastic or …
97 …module will still conflict with a struct of the same name declared in a different module, just as …
99 …anguage. Maintaining a stable binary module format across architectures, compiler versions, and co…
103 …-line flag ``-fmodules``. This will make any modules-enabled software libraries available as modul…
105 Objective-C Import declaration
106 ------------------------------
107 Objective-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::
119 …ns are ignored, and one is free to import modules at any point within the translation unit, so lon…
121 At present, there is no C or C++ syntax for import declarations. Clang
126 -------------------
127 …-level feature of modules is the import operation, which provides access to the API of software li…
129 .. code-block:: c
133 …module ``std.io``. Even with specific ``import`` syntax in the language, this particular feature i…
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.
140 The usual behavior of ``#include_next`` is to search for the specified filename
143 Because files listed in module maps are not found through include paths, a
144 different strategy is used for ``#include_next`` directives in such files: the
145 list of include paths is searched for the specified header name, to find the
146 first include path that would refer to the current file. ``#include_next`` is
148 If this search finds a file named by a module map, the ``#include_next``
149 directive is translated into an import, just like for a ``#include``
152 Module maps
153 -----------
154 …is described by a *module map*, which describes how a collection of existing headers maps on to th…
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…
165 -----------------
166 …is automatically generated by the compiler on an as-needed basis. When a module is imported (e.g.,…
168 …is persisted in the *module cache*. Imports of a module will first query the module cache and, if …
170 …ere part of the module build. If any of those headers changes, or if any of the modules on which a…
172 Command-line parameters
173 -----------------------
174 ``-fmodules``
177 ``-fimplicit-module-maps``
178 …module map files named ``module.modulemap`` and similar. This option is implied by ``-fmodules``. …
180 ``-fmodules-cache-path=<directory>``
181 …Specify the path to the modules cache. If not provided, Clang will select a system-appropriate def…
183 ``-fno-autolink``
186 ``-fmodules-ignore-macro=macroname``
187 …iate module variant. Use this for macros defined on the command line that don't affect how modules…
189 ``-fmodules-prune-interval=seconds``
190 …module cache. Module cache pruning attempts to clear out old, unused module files so that the modu…
192 ``-fmodules-prune-after=seconds``
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…
198 ``-fmodules-decluse``
199 Enable checking of module ``use`` declarations.
201 ``-fmodule-name=module-id``
202 Consider a source file as a part of the given module.
204 ``-fmodule-map-file=<file>``
205 …Load the given module map file if a header from its directory or one of its subdirectories is load…
207 ``-fmodules-search-all``
208 …is not found, search modules referenced in the current module maps but not imported for symbols, s…
210 ``-fno-implicit-modules``
211 All modules used by the build must be specified with ``-fmodule-file``.
213 ``-fmodule-file=<file>``
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 …is currently only approximated when building a module with submodules. Entities within a submodule…
231 If any submodule of a module is imported into any part of a program, the entire top-level module is…
234 ------
236 …preprocessor assumes that the input text is a single linear buffer, but with modules this is not t…
238 * Each definition and undefinition of a macro is considered to be a distinct entity.
241 * A ``#define`` or ``#undef`` directive is *active* if it is visible and no visible directive overr…
242 * A set of macro directives is *consistent* if it consists of only ``#undef`` directives, or if all…
243 …o name is used and the set of active directives is not consistent, the program is ill-formed. Othe…
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:
273 .. parsed-literal::
275 module std [system] [extern_c] {
276 module assert {
278 header "bits/assert-decls.h"
282 module complex {
287 module ctype {
292 module errno {
298 module fenv {
306 …-level module ``std`` encompasses the whole C standard library. It has a number of submodules cont…
309 -----------------
310 Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, token…
312 .. parsed-literal::
318 ``extern`` ``module`` ``use``
320 Module map file
321 ---------------
322 A module map file consists of a series of module declarations:
324 .. parsed-literal::
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 …
331 .. parsed-literal::
333 *module-id*:
336 Module declaration
337 ------------------
338 A module declaration describes a module, including the headers that contribute to that module, its …
340 .. parsed-literal::
342 *module-declaration*:
343 …`explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *m…
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…
352 .. parsed-literal::
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+…
365 Modules can have a number of different kinds of members, each of which is described below:
367 .. parsed-literal::
369 *module-member*:
370 *requires-declaration*
371 *header-declaration*
372 *umbrella-dir-declaration*
373 *submodule-declaration*
374 *export-declaration*
375 *use-declaration*
376 *link-declaration*
377 *config-macros-declaration*
378 *conflict-declaration*
380 An extern module references a module defined by the *module-id* in a file given by the *string-lite…
384 A *requires-declaration* specifies the requirements that an importing translation unit must satisfy…
386 .. parsed-literal::
388 *requires-declaration*:
389 ``requires`` *feature-list*
391 *feature-list*:
397 …is a set of identifiers, defined below. If any of the features is not available in a given transla…
405 The "blocks" language feature is available.
408 C++ support is available.
411 C++11 support is available.
414 Objective-C support is available.
417 Objective-C Automatic Reference Counting (ARC) is available
420 OpenCL is available
423 Thread local storage is available.
426 A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available.
429 **Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requ…
431 .. parsed-literal::
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.
451 .. parsed-literal::
453 *header-declaration*:
454 ``private``:sub:`opt` ``textual``:sub:`opt` ``header`` *string-literal*
455 ``umbrella`` ``header`` *string-literal*
456 ``exclude`` ``header`` *string-literal*
458 …`` specifies a header that contributes to the enclosing module. Specifically, when the module is b…
460 …is called an umbrella header. An umbrella header includes all of the headers within its directory …
465 ``-Wincomplete-umbrella`` warning option to ask Clang to complain
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
471 built, and will be textually included if it is named by a ``#include``
472 directive. However, it is considered to be part of the module for the purpose
473 of checking *use-declaration*\s, and must still be a lexically-valid header
474 file. In the future, we intend to pre-tokenize such headers and include the
475 token sequence within the prebuilt module representation.
477 …is excluded from the module. It will not be included when the module is built, nor will it be cons…
479 **Example:** The C header ``assert.h`` is an excellent candidate for a textual header, because it i…
481 .. parsed-literal::
483 module std [system] {
487 A given header shall not be referenced by more than one *header-declaration*.
491 … specifies that all of the headers in the specified directory should be included within the module.
493 .. parsed-literal::
495 *umbrella-dir-declaration*:
496 ``umbrella`` *string-literal*
498 …-literal* refers to a directory. When the module is built, all of the header files in that directo…
500 An *umbrella-dir-declaration* shall not refer to the same directory as the location of an umbrella …
509 Submodule declarations describe modules that are nested within their enclosing module.
511 .. parsed-literal::
513 *submodule-declaration*:
514 *module-declaration*
515 *inferred-submodule-declaration*
517 …-declaration* that is a *module-declaration* is a nested module. If the *module-declaration* has a…
519 …-declaration* that is an *inferred-submodule-declaration* describes a set of submodules that corre…
521 .. parsed-literal::
523 *inferred-submodule-declaration*:
524 …xplicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred-su…
526 *inferred-submodule-member*:
529 …module containing an *inferred-submodule-declaration* shall have either an umbrella header or an u…
531 …y that is not named by a *header-declaration*, a module declaration is implicitly generated from t…
534 * Have the ``explicit`` specifier, if the *inferred-submodule-declaration* has the ``explicit`` spe…
536 *inferred-submodule-declaration* has the ``framework`` specifier
537 * Have the attributes specified by the \ *inferred-submodule-declaration*
538 * Contain a single *header-declaration* naming that header
539 …Contain a single *export-declaration* ``export *``, if the \ *inferred-submodule-declaration* cont…
541 …f the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
543 .. parsed-literal::
545 module MyLib {
547 explicit module * {
552 is equivalent to the (more verbose) module map:
554 .. parsed-literal::
556 module MyLib {
557 explicit module A {
562 explicit module B {
570 An *export-declaration* specifies which imported modules will automatically be re-exported as part …
572 .. parsed-literal::
574 *export-declaration*:
575 ``export`` *wildcard-module-id*
577 *wildcard-module-id*:
580 *identifier* '.' *wildcard-module-id*
582 …-declaration* names a module or a set of modules that will be re-exported to any translation unit …
586 .. parsed-literal::
588 module MyLib {
589 module Base {
593 module Derived {
599 Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard export to re-export …
601 .. parsed-literal::
603 module MyLib {
604 module Base {
608 module Derived {
616 The wildcard export syntax ``export *`` re-exports all of the
618 ``#include`` directives are automatically mapped to module imports,
619 ``export *`` provides the same transitive-inclusion behavior
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
632 .. parsed-literal::
634 *use-declaration*:
635 ``use`` *module-id*
637 **Example:** In the following example, use of A from C is not declared, so will trigger a warning.
639 .. parsed-literal::
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 A *link-declaration* specifies a library or framework against which a program should be linked if t…
664 .. parsed-literal::
666 *link-declaration*:
667 ``link`` ``framework``:sub:`opt` *string-literal*
669 …-literal* specifies the name of the library or framework against which the program should be linke…
671 A *link-declaration* with the ``framework`` specifies that the linker should link against the named…
675 Automatic linking with the ``link`` directive is not yet widely
677 format and the linker. The notion is similar to Microsoft Visual
682 The *config-macros-declaration* specifies the set of configuration macros that have an effect on th…
684 .. parsed-literal::
686 *config-macros-declaration*:
687 ``config_macros`` *attributes*:sub:`opt` *config-macro-list*:sub:`opt`
689 *config-macro-list*:
692 …r* in the *config-macro-list* specifies the name of a macro. The compiler is required to maintain …
694 A *config-macros-declaration* shall only be present on a top-level module, i.e., a module that is n…
696 …the *config-macros-declaration* is exhaustive, meaning that no other macro definition is intended …
702 completely when building the module. As an optimization, the
703 compiler could reduce the number of unique module variants by not
704 considering these non-configuration macros. This optimization is not
707 A translation unit shall not import the same module under different definitions of the configuratio…
715 warning (under the control of ``-Wconfig-macros``).
719 .. parsed-literal::
721 module MyLogger {
728 …-declaration* describes a case where the presence of two different modules in the same translation…
730 .. parsed-literal::
732 *conflict-declaration*:
733 ``conflict`` *module-id* ',' *string-literal*
735 …module-id* of the *conflict-declaration* specifies the module with which the enclosing module conf…
737 The *string-literal* provides a message to be provided as part of the compiler diagnostic when two …
741 Clang emits a warning (under the control of ``-Wmodule-conflict``)
742 when a module conflict is discovered.
746 .. parsed-literal::
748 module Conflicts {
749 explicit module A {
754 module B {
761 ----------
762 …mar to describe specific behavior of other declarations. The format of attributes is fairly simple.
764 .. parsed-literal::
774 Private Module Map Files
775 ------------------------
776 Module map files are typically named ``module.modulemap`` and live
778 the headers they describe. These module maps typically describe all of
782 is used to distinguish between the "public" and "private" APIs of a
787 express this with a single module map file in the library:
789 .. parsed-literal::
791 module Foo {
794 explicit module Private {
801 module map file could be customized based on whether
802 ``Foo_Private.h`` is available or not, but doing so requires custom
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
811 .. code-block:: c
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
827 would be available when ``Foo_Private.h`` is available, making it
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…
837 **Macro-guarded copy-and-pasted definitions**
838 …nd are almost trivial to write. Hence, it is fairly common to see a definition such as the followi…
840 .. parsed-literal::
847 …module, only the first actual type definition of ``size_t`` will be visible, and then only in the …
850 …-modules world unless someone happens to include both headers in one translation unit. Since the f…
853 …ht order. With modules, the headers of a particular module will be parsed in isolation, so the mod…
856 …is defined before that header is included, and also vend ``wchar_t`` only when the macro ``__need_…
858 …-tools-extra`` repository contains a ``modularize`` tool that parses a set of given headers and at…
862 Modules support is under active development, and there are many opportunities remaining to improve …
864 **Detect unused module imports**
865 …a directly-imported module has ever been used. By doing so, Clang can emit ``unused import`` or ``…
867 **Fix-Its for missing imports**
868 …en included. Clang can detect such cases and auto-import the required module, but should provide a…
871 …is both extremely important (for deployment) and extremely crude. It needs better UI, better detec…
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…
890 …format used for precompiled headers and modules. The actual implementation is in the ``clangSerial…
892 …g against the libraries of modules requires specific linker support, which is not widely available.
894 .. [#] There are certain anti-patterns that occur in headers, particularly system headers, that cau…
896 … second instance is actually a new thread within the current process, not a separate process. Howe…
898 …is actually dependent on the command-line options provided to the compiler, including the language…