Lines Matching +full:- +full:- +full:fix +full:- +full:imports +full:- +full:only
10 …braries built as part of the software itself to provide structure, and third-party libraries. For …
12 .. code-block:: c
16 …ately by linking against the appropriate library. For example, by passing ``-lSomeLib`` to the lin…
18 Modules provide an alternative, simpler way to use software libraries that provides better compile-…
21 -------------------------------
24 * **Compile-time scalability**: Each time a header is included, 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
69 API, and what declarations are present only because they had to be
73 ---------------
74 …ore efficient semantic model. From the user's perspective, the code looks only slightly different,…
76 .. code-block:: c
78 import std.io; // pseudo-code; see below for syntax discussion
83 …-time scalability**: The ``std.io`` module is only compiled once, and importing the module into a …
85 …ry can not affect how another software library is compiled, eliminating include-order dependencies.
87 …and present a module as a representation of that API. Because modules can only be built standalone…
90 -----------------------------
91 …t modules do *not* do. In particular, all of the following are considered out-of-scope for modules:
93 …ic to require applications or software libraries to make drastic or non-backward-compatible change…
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 …imports the entire contents of the ``std`` module (which would contain, e.g., the entire C or C++ …
115 .. parsed-literal::
123 `Includes as imports`_ to see how modules get imported today.
125 Includes as imports
126 -------------------
127 The primary user-level feature of modules is the import operation, which provides access to the API…
129 .. code-block:: c
133 …-enabled libraries) without any changes to the application itself. Thus, users can easily use modu…
137 … ``import``, the compiler can guarantee that it always sees just the already-parsed definition fro…
153 -----------
154 …ames to (sub)modules allows the automatic translation of ``#include`` directives to module imports.
162 …r files. To do this, use the ``-fimplicit-module-maps`` option instead of the ``-fmodules`` option…
165 -----------------
166 The binary representation of modules is automatically generated by the compiler on an as-needed bas…
168 …Imports of a module will first query the module cache and, if a binary representation of the requi…
172 Command-line parameters
173 -----------------------
174 ``-fmodules``
177 ``-fimplicit-module-maps``
178 …-fmodules``. If this is disabled with ``-fno-implicit-module-maps``, module map files will only be…
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``
189 ``-fmodules-prune-interval=seconds``
192 ``-fmodules-prune-after=seconds``
195 ``-module-file-info <module file name>``
198 ``-fmodules-decluse``
201 ``-fmodule-name=module-id``
204 ``-fmodule-map-file=<file>``
207 ``-fmodules-search-all``
210 ``-fno-implicit-modules``
211 All modules used by the build must be specified with ``-fmodule-file``.
213 ``-fmodule-file=<file>``
223 …This behavior is currently only approximated when building a module with submodules. Entities with…
229 Clang currently only performs minimal checking for violations of the One Definition Rule.
231 If any submodule of a module is imported into any part of a program, the entire top-level module is…
234 ------
242 * A set of macro directives is *consistent* if it consists of only ``#undef`` directives, or if all…
243 * If a macro name is used and the set of active directives is not consistent, the program is ill-fo…
248 * ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
250 The ``#undef`` overrides the ``#define``, and a source file that imports both modules *in any order…
273 .. parsed-literal::
278 header "bits/assert-decls.h"
306 …-level module ``std`` encompasses the whole C standard library. It has a number of submodules cont…
309 -----------------
312 .. parsed-literal::
321 ---------------
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*:
337 ------------------
340 .. parsed-literal::
342 *module-declaration*:
343 …t``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *module-me…
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 …only be applied to a submodule, i.e., a module that is nested within another module. The contents …
350 …`` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style fr…
352 .. parsed-literal::
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 The requirements clause allows specific modules or submodules to specify that they are only accessi…
414 Objective-C support is available.
417 Objective-C Automatic Reference Counting (ARC) is available
429 …`std`` module can be extended to also include C++ and C++11 headers using a *requires-declaration*:
431 .. parsed-literal::
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*
460 …t ``header`` declarations for every library header. A given directory can only contain a single um…
465 ``-Wincomplete-umbrella`` warning option to ask Clang to complain
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
481 .. parsed-literal::
487 A given header shall not be referenced by more than one *header-declaration*.
493 .. parsed-literal::
495 *umbrella-dir-declaration*:
496 ``umbrella`` *string-literal*
498 The *string-literal* refers to a directory. When the module is built, all of the header files in th…
500 An *umbrella-dir-declaration* shall not refer to the same directory as the location of an umbrella …
511 .. parsed-literal::
513 *submodule-declaration*:
514 *module-declaration*
515 *inferred-submodule-declaration*
517 A *submodule-declaration* that is a *module-declaration* is a nested module. If the *module-declara…
519 …-declaration* that is an *inferred-submodule-declaration* describes a set of submodules that corre…
521 .. parsed-literal::
523 *inferred-submodule-declaration*:
524 … ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred-submodule-member** '}'
526 *inferred-submodule-member*:
529 … *inferred-submodule-declaration* shall have either an umbrella header or an umbrella directory. T…
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…
543 .. parsed-literal::
554 .. parsed-literal::
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::
599 Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard export to re-export …
601 .. parsed-literal::
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
621 implicitly imports all of the modules on which it depends.
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
630 only use other modules that are explicitly specified in this way.
632 .. parsed-literal::
634 *use-declaration*:
635 ``use`` *module-id*
639 .. parsed-literal::
655 ``-fmodule-name=module-id`` to indicate that the source file is logically part
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…
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 Each *identifier* in the *config-macro-list* specifies the name of a macro. The compiler is require…
694 A *config-macros-declaration* shall only be present on a top-level module, i.e., a module that is n…
696 The ``exhaustive`` attribute specifies that the list of macros in the *config-macros-declaration* i…
704 considering these non-configuration macros. This optimization is not
715 warning (under the control of ``-Wconfig-macros``).
719 .. parsed-literal::
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 The *module-id* of the *conflict-declaration* specifies the module with which the enclosing module …
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``)
746 .. parsed-literal::
761 ----------
764 .. parsed-literal::
775 ------------------------
785 respectively. Additionally, ``Foo_Private.h`` may only be available on
789 .. parsed-literal::
811 .. code-block:: c
835 …m headers themselves may require some modification, if they exhibit any anti-patterns that break m…
837 **Macro-guarded copy-and-pasted definitions**
838 … Hence, it is fairly common to see a definition such as the following copy-and-pasted throughout t…
840 .. parsed-literal::
847 …only the first actual type definition of ``size_t`` will be visible, and then only in the submodul…
850 …to cause problems in a pre-modules world unless someone happens to include both headers in one tra…
853 … actually depend on. As with the problem of conflicting definitions, this only affects unlucky use…
856 …only some of which are made available with a given include. For example, the header may vend ``siz…
858 …-tools-extra`` repository contains a ``modularize`` tool that parses a set of given headers and at…
864 **Detect unused module imports**
865 …-imported module has ever been used. By doing so, Clang can emit ``unused import`` or ``unused #in…
867 **Fix-Its for missing imports**
868 …only to get a compiler error about "unknown type" or "no function named" because the corresponding…
878 Module map for Clang's compiler-specific header files.
894 .. [#] There are certain anti-patterns that occur in headers, particularly system headers, that cau…
898 …and-line options provided to the compiler, including the language dialect and any ``-D`` options. …