Lines Matching full:module
50 ``Clang module map modules`` or ``Clang c++ modules``.
52 Module and module unit
55 A module consists of one or more module units. A module unit is a special
56 translation unit. Every module unit must have a module declaration. The syntax
57 of the module declaration is:
61 [export] module module_name[:partition_name];
67 In this document, module units are classified into:
69 * Primary module interface unit.
71 * Module implementation unit.
73 * Module interface partition unit.
75 * Internal module partition unit.
77 A primary module interface unit is a module unit whose module declaration is
78 ``export module module_name;``. The ``module_name`` here denotes the name of the
79 module. A module should have one and only one primary module interface unit.
81 A module implementation unit is a module unit whose module declaration is
82 ``module module_name;``. A module could have multiple module implementation
85 A module interface partition unit is a module unit whose module declaration is
86 ``export module module_name:partition_name;``. The ``partition_name`` should be
87 unique within any given module.
89 An internal module partition unit is a module unit whose module declaration
90 is ``module module_name:partition_name;``. The ``partition_name`` should be
91 unique within any given module.
95 * A ``module interface unit`` refers to either a ``primary module interface unit``
96 or a ``module interface partition unit``.
98 * An ``importable module unit`` refers to either a ``module interface unit``
99 or a ``internal module partition unit``.
101 * A ``module partition unit`` refers to either a ``module interface partition unit``
102 or a ``internal module partition unit``.
104 Built Module Interface file
107 A ``Built Module Interface file`` stands for the precompiled result of an importable module unit.
110 Global module fragment
113 In a module unit, the section from ``module;`` to the module declaration is called the global modul…
127 module;
129 export module Hello;
146 $ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out
150 In this example, we make and use a simple module ``Hello`` which contains only a
151 primary module interface unit ``Hello.cppm``.
153 Then let's see a little bit more complex "hello world" example which uses the 4 kinds of module uni…
158 export module M;
164 export module M:interface_part;
168 module;
171 module M:impl_part;
180 module;
182 module M;
199 # Precompiling the module
201 $ clang++ -std=c++20 impl_part.cppm --precompile -fprebuilt-module-path=. -o M-impl_part.pcm
202 $ clang++ -std=c++20 M.cppm --precompile -fprebuilt-module-path=. -o M.pcm
206 $ clang++ -std=c++20 User.cpp -fprebuilt-module-path=. -c -o User.o
208 # Compiling the module and linking it together
226 We can generate a BMI for an importable module unit by either ``--precompile``
243 to higher parallelism. As an example, if there are two module units A and B, and B depends on A, the
251 The file name of an ``importable module unit`` should end with ``.cppm``
252 (or ``.ccm``, ``.cxxm``, ``.c++m``). The file name of a ``module implementation unit``
256 The file name of the BMI of a ``primary module interface unit`` should be ``module_name.pcm``.
257 The file name of BMIs of ``module partition unit`` should be ``module_name-partition_name.pcm``.
259 If the file names use different extensions, Clang may fail to build the module.
260 For example, if the filename of an ``importable module unit`` ends with ``.cpp`` instead of ``.cppm…
261 then we can't generate a BMI for the ``importable module unit`` by ``--precompile`` option
263 If we want the filename of an ``importable module unit`` ends with other suffixes instead of ``.cpp…
264 we could put ``-x c++-module`` in front of the file. For example,
269 module;
271 export module Hello;
283 Now the filename of the ``module interface`` ends with ``.cpp`` instead of ``.cppm``,
288 $ clang++ -std=c++20 -x c++-module Hello.cpp --precompile -o Hello.pcm
289 $ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out
293 Module name requirement
296 [module.unit]p1 says:
300 All module-names either beginning with an identifier consisting of std followed by zero
302 be specified in a module-declaration; no diagnostic is required. If any identifier in a reserved
303 module-name is a reserved identifier, the module name is reserved for use by C++ implementations;
316 If you still want to use the reserved module names for any reason, currently you can add a special …
317 in the front of the module declaration like:
322 export module std;
334 * (1) ``-fprebuilt-module-path=<path/to/direcotry>``.
336 * (3) ``-fmodule-file=<module-name>=<path/to/BMI>``.
338 The option ``-fprebuilt-module-path`` tells the compiler the path where to search for dependent BMI…
341 * (1) When we import module M. The compiler would look up M.pcm in the directories specified
342 by ``-fprebuilt-module-path``.
343 * (2) When we import partition module unit M:P. The compiler would look up M-P.pcm in the
344 directories specified by ``-fprebuilt-module-path``.
347 The option ``-fmodule-file=<module-name>=<path/to/BMI>`` tells the compiler to load the specified B…
348 for the module specified by ``<module-name>`` when necessary. The main difference is that
350 ``-fmodule-file=<module-name>=<path/to/BMI>`` will only load the BMI lazily, which is similar
351 with ``-fprebuilt-module-path``.
353 In case all ``-fprebuilt-module-path=<path/to/direcotry>``, ``-fmodule-file=<path/to/BMI>`` and
354 ``-fmodule-file=<module-name>=<path/to/BMI>`` exist, the ``-fmodule-file=<path/to/BMI>`` option
355 takes highest precedence and ``-fmodule-file=<module-name>=<path/to/BMI>`` will take the second
358 When we compile a ``module implementation unit``, we must specify the BMI of the corresponding
359 ``primary module interface unit``.
360 Since the language specification says a module implementation unit implicitly imports
361 the primary module interface unit.
363 [module.unit]p8
365 A module-declaration that contains neither an export-keyword nor a module-partition implicitly
366 imports the primary module interface unit of the module as if by a module-import-declaration.
368 All of the 3 options ``-fprebuilt-module-path=<path/to/direcotry>``, ``-fmodule-file=<path/to/BMI>``
369 and ``-fmodule-file=<module-name>=<path/to/BMI>`` may occur multiple times.
378 ``-fprebuilt-module-path`` is more convenient and ``-fmodule-file`` is faster since
381 Remember that module units still have an object counterpart to the BMI
384 It is easy to forget to compile BMIs at first since we may envision module interfaces like headers.
386 Module units are translation units. We need to compile them to object files
398 And the compilation process for module units are like:
407 As the diagrams show, we need to compile the BMI from module units to object files and link the obj…
410 If we want to create a module library, we can't just ship the BMIs in an archive.
423 The language option of module units and their non-module-unit users should be consistent.
429 export module M;
437 $ clang++ -std=c++2b Use.cpp -fprebuilt-module-path=.
447 $ clang++ -std=c++20 -O3 Use.cpp -fprebuilt-module-path=.
449 $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
459 $ clang++ -std=c++20 -O3 -DNDEBUG Use.cpp -fprebuilt-module-path=.
473 export module M;
526 Also the compiler will record the path to the header files included in the global module fragment a…
538 module;
540 export module foo;
549 Then it is problematic if we remove ``foo.h`` before import `foo` module.
570 The declarations in a module unit which are not in the global module fragment have new linkage name…
576 export module M;
589 The result would be ``NS::foo@M()``, which reads as ``NS::foo()`` in module ``M``.
591 The ABI implies that we can't declare something in a module unit and define it in a non-module unit…
619 Currently, when we call deduction guides in global module fragment,
622 So if we're using deduction guide from global module fragment, we probably need to write:
644 Don't emit macros about module declaration
654 MODULE
660 So this file could be triggered like a module unit or a non-module unit depending on the definition
665 A simple suggestion would be "Don't play macro tricks with module declarations".
669 In consistent filename suffix requirement for importable module units
672 Currently, clang requires the file name of an ``importable module unit`` should end with ``.cppm``
757 With the existing implementation ``-fprebuilt-module-path`` cannot be used for header units
762 the -fmodule-file or by the use of a module-mapper that understands how to map the header name to t…
782 Currently, Clang would do this translation for the ``#include`` in the global module fragment.
788 module;
790 export module M;
799 module;
801 export module M;
825 module "iostream" {
838 $ clang++ -std=c++20 main.cpp -fimplicit-modules -fimplicit-module-maps
841 `module map <https://github.com/llvm/llvm-project/blob/main/libcxx/include/module.modulemap.in>`_
847 wrapping multiple headers together as a big module.
851 Another reason is that there are proposals to introduce module mappers to the C++ standard
853 … to reuse Clang's modulemap, we may get in trouble once we need to introduce another module mapper.
868 But if there are ``n`` module interfaces and ``m`` source files, the complexity of the compilation …
897 Here we can see that the source file (could be a non-module unit or a module unit) would get proces…
931 of imported module units so that it can perform IPO (InterProcedural Optimization, primarily inlini…
933 the imported module units.
940 Overall, at ``O0`` the implementations of functions defined in a module will not impact module user…