mirror of
https://github.com/llvm/llvm-project.git
synced 2025-04-25 09:06:06 +00:00
411196b9bb
According to our previous consensus in https://clang.llvm.org/docs/StandardCPlusPlusModules.html#reduced-bmi, the reduced BMI will be the default and recommend users to use the new option. The `-fexperimental-modules-reduced-bmi ` option is introduced in https://github.com/llvm/llvm-project/pull/85050 in Mar13 and released in 19.x. And now we are in 20's release cycle. Also I rarely receive issue reports about reduced BMI. No matter it is due to the quality of reduced BMI is really good or no one uses it. This patch literally did the second point in https://clang.llvm.org/docs/StandardCPlusPlusModules.html#reduced-bmi
2075 lines
69 KiB
ReStructuredText
2075 lines
69 KiB
ReStructuredText
====================
|
|
Standard C++ Modules
|
|
====================
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
Introduction
|
|
============
|
|
|
|
The term ``module`` is ambiguous, as it is used to mean multiple things in
|
|
Clang. For Clang users, a module may refer to an ``Objective-C Module``,
|
|
`Clang Module <Modules.html>`_ (also called a ``Clang Header Module``) or a
|
|
``C++20 Module`` (or a ``Standard C++ Module``). The implementation of all
|
|
these kinds of modules in Clang shares a lot of code, but from the perspective
|
|
of users their semantics and command line interfaces are very different. This
|
|
document is an introduction to the use of C++20 modules in Clang. In the
|
|
remainder of this document, the term ``module`` will refer to Standard C++20
|
|
modules and the term ``Clang module`` will refer to the Clang Modules
|
|
extension.
|
|
|
|
In terms of the C++ Standard, modules consist of two components: "Named
|
|
Modules" or "Header Units". This document covers both.
|
|
|
|
Standard C++ Named modules
|
|
==========================
|
|
|
|
In order to better understand the compiler's behavior, it is helpful to
|
|
understand some terms and definitions for readers who are not familiar with the
|
|
C++ feature. This document is not a tutorial on C++; it only introduces
|
|
necessary concepts to better understand use of modules in a project.
|
|
|
|
Background and terminology
|
|
--------------------------
|
|
|
|
Module and module unit
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A module consists of one or more module units. A module unit is a special kind
|
|
of translation unit. A module unit should almost always start with a module
|
|
declaration. The syntax of the module declaration is:
|
|
|
|
.. code-block:: c++
|
|
|
|
[export] module module_name[:partition_name];
|
|
|
|
Terms enclosed in ``[]`` are optional. ``module_name`` and ``partition_name``
|
|
follow the rules for a C++ identifier, except that they may contain one or more
|
|
period (``.``) characters. Note that a ``.`` in the name has no semantic
|
|
meaning and does not imply any hierarchy.
|
|
|
|
In this document, module units are classified as:
|
|
|
|
* Primary module interface unit
|
|
* Module implementation unit
|
|
* Module partition interface unit
|
|
* Internal module partition unit
|
|
|
|
A primary module interface unit is a module unit whose module declaration is
|
|
``export module module_name;`` where ``module_name`` denotes the name of the
|
|
module. A module should have one and only one primary module interface unit.
|
|
|
|
A module implementation unit is a module unit whose module declaration is
|
|
``module module_name;``. Multiple module implementation units can be declared
|
|
in the same module.
|
|
|
|
A module partition interface unit is a module unit whose module declaration is
|
|
``export module module_name:partition_name;``. The ``partition_name`` should be
|
|
unique within any given module.
|
|
|
|
An internal module partition unit is a module unit whose module
|
|
declaration is ``module module_name:partition_name;``. The ``partition_name``
|
|
should be unique within any given module.
|
|
|
|
In this document, we use the following terms:
|
|
|
|
* A ``module interface unit`` refers to either a ``primary module interface unit``
|
|
or a ``module partition interface unit``.
|
|
|
|
* An ``importable module unit`` refers to either a ``module interface unit`` or
|
|
an ``internal module partition unit``.
|
|
|
|
* A ``module partition unit`` refers to either a ``module partition interface unit``
|
|
or an ``internal module partition unit``.
|
|
|
|
Built Module Interface
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A ``Built Module Interface`` (or ``BMI``) is the precompiled result of an
|
|
importable module unit.
|
|
|
|
Global module fragment
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The ``global module fragment`` (or ``GMF``) is the code between the ``module;``
|
|
and the module declaration within a module unit.
|
|
|
|
|
|
How to build projects using modules
|
|
-----------------------------------
|
|
|
|
Quick Start
|
|
~~~~~~~~~~~
|
|
|
|
Let's see a "hello world" example that uses modules.
|
|
|
|
.. code-block:: c++
|
|
|
|
// Hello.cppm
|
|
module;
|
|
#include <iostream>
|
|
export module Hello;
|
|
export void hello() {
|
|
std::cout << "Hello World!\n";
|
|
}
|
|
|
|
// use.cpp
|
|
import Hello;
|
|
int main() {
|
|
hello();
|
|
return 0;
|
|
}
|
|
|
|
Then, on the command line, invoke Clang like:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 Hello.cppm --precompile -o Hello.pcm
|
|
$ clang++ -std=c++20 use.cpp -fmodule-file=Hello=Hello.pcm Hello.pcm -o Hello.out
|
|
$ ./Hello.out
|
|
Hello World!
|
|
|
|
In this example, we make and use a simple module ``Hello`` which contains only a
|
|
primary module interface unit named ``Hello.cppm``.
|
|
|
|
A more complex "hello world" example which uses the 4 kinds of module units is:
|
|
|
|
.. code-block:: c++
|
|
|
|
// M.cppm
|
|
export module M;
|
|
export import :interface_part;
|
|
import :impl_part;
|
|
export void Hello();
|
|
|
|
// interface_part.cppm
|
|
export module M:interface_part;
|
|
export void World();
|
|
|
|
// impl_part.cppm
|
|
module;
|
|
#include <iostream>
|
|
#include <string>
|
|
module M:impl_part;
|
|
import :interface_part;
|
|
|
|
std::string W = "World.";
|
|
void World() {
|
|
std::cout << W << std::endl;
|
|
}
|
|
|
|
// Impl.cpp
|
|
module;
|
|
#include <iostream>
|
|
module M;
|
|
void Hello() {
|
|
std::cout << "Hello ";
|
|
}
|
|
|
|
// User.cpp
|
|
import M;
|
|
int main() {
|
|
Hello();
|
|
World();
|
|
return 0;
|
|
}
|
|
|
|
Then, back on the command line, invoke Clang with:
|
|
|
|
.. code-block:: console
|
|
|
|
# Precompiling the module
|
|
$ clang++ -std=c++20 interface_part.cppm --precompile -o M-interface_part.pcm
|
|
$ clang++ -std=c++20 impl_part.cppm --precompile -fprebuilt-module-path=. -o M-impl_part.pcm
|
|
$ clang++ -std=c++20 M.cppm --precompile -fprebuilt-module-path=. -o M.pcm
|
|
$ clang++ -std=c++20 Impl.cpp -fprebuilt-module-path=. -c -o Impl.o
|
|
|
|
# Compiling the user
|
|
$ clang++ -std=c++20 User.cpp -fprebuilt-module-path=. -c -o User.o
|
|
|
|
# Compiling the module and linking it together
|
|
$ clang++ -std=c++20 M-interface_part.pcm -fprebuilt-module-path=. -c -o M-interface_part.o
|
|
$ clang++ -std=c++20 M-impl_part.pcm -fprebuilt-module-path=. -c -o M-impl_part.o
|
|
$ clang++ -std=c++20 M.pcm -fprebuilt-module-path=. -c -o M.o
|
|
$ clang++ User.o M-interface_part.o M-impl_part.o M.o Impl.o -o a.out
|
|
|
|
We explain the options in the following sections.
|
|
|
|
How to enable standard C++ modules
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Standard C++ modules are enabled automatically when the language standard mode
|
|
is ``-std=c++20`` or newer.
|
|
|
|
How to produce a BMI
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To generate a BMI for an importable module unit, use either the ``--precompile``
|
|
or ``-fmodule-output`` command line options.
|
|
|
|
The ``--precompile`` option generates the BMI as the output of the compilation
|
|
with the output path specified using the ``-o`` option.
|
|
|
|
The ``-fmodule-output`` option generates the BMI as a by-product of the
|
|
compilation. If ``-fmodule-output=`` is specified, the BMI will be emitted to
|
|
the specified location. If ``-fmodule-output`` and ``-c`` are specified, the
|
|
BMI will be emitted in the directory of the output file with the name of the
|
|
input file with the extension ``.pcm``. Otherwise, the BMI will be emitted in
|
|
the working directory with the name of the input file with the extension
|
|
``.pcm``.
|
|
|
|
Generating BMIs with ``--precompile`` is referred to as two-phase compilation
|
|
because it takes two steps to compile a source file to an object file.
|
|
Generating BMIs with ``-fmodule-output`` is called one-phase compilation. The
|
|
one-phase compilation model is simpler for build systems to implement while the
|
|
two-phase compilation has the potential to compile faster due to higher
|
|
parallelism. As an example, if there are two module units ``A`` and ``B``, and
|
|
``B`` depends on ``A``, the one-phase compilation model needs to compile them
|
|
serially, whereas the two-phase compilation model is able to be compiled as
|
|
soon as ``A.pcm`` is available, and thus can be compiled simultaneously as the
|
|
``A.pcm`` to ``A.o`` compilation step.
|
|
|
|
File name requirements
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
By convention, ``importable module unit`` files should use ``.cppm`` (or
|
|
``.ccm``, ``.cxxm``, or ``.c++m``) as a file extension.
|
|
``Module implementation unit`` files should use ``.cpp`` (or ``.cc``, ``.cxx``,
|
|
or ``.c++``) as a file extension.
|
|
|
|
A BMI should use ``.pcm`` as a file extension. The file name of the BMI for a
|
|
``primary module interface unit`` should be ``module_name.pcm``. The file name
|
|
of a BMI for a ``module partition unit`` should be
|
|
``module_name-partition_name.pcm``.
|
|
|
|
Clang may fail to build the module if different extensions are used. For
|
|
example, if the filename of an ``importable module unit`` ends with ``.cpp``
|
|
instead of ``.cppm``, then Clang cannot generate a BMI for the
|
|
``importable module unit`` with the ``--precompile`` option because the
|
|
``--precompile`` option would only run the preprocessor (``-E``). If using a
|
|
different extension than the conventional one for an ``importable module unit``
|
|
you can specify ``-x c++-module`` before the file. For example,
|
|
|
|
.. code-block:: c++
|
|
|
|
// Hello.cpp
|
|
module;
|
|
#include <iostream>
|
|
export module Hello;
|
|
export void hello() {
|
|
std::cout << "Hello World!\n";
|
|
}
|
|
|
|
// use.cpp
|
|
import Hello;
|
|
int main() {
|
|
hello();
|
|
return 0;
|
|
}
|
|
|
|
In this example, the extension used by the ``module interface`` is ``.cpp``
|
|
instead of ``.cppm``, so it cannot be compiled like the previous example, but
|
|
it can be compiled with:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 -x c++-module Hello.cpp --precompile -o Hello.pcm
|
|
$ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out
|
|
$ ./Hello.out
|
|
Hello World!
|
|
|
|
Module name requirements
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
..
|
|
|
|
[module.unit]p1:
|
|
|
|
All module-names either beginning with an identifier consisting of std followed by zero
|
|
or more digits or containing a reserved identifier ([lex.name]) are reserved and shall not
|
|
be specified in a module-declaration; no diagnostic is required. If any identifier in a reserved
|
|
module-name is a reserved identifier, the module name is reserved for use by C++ implementations;
|
|
otherwise it is reserved for future standardization.
|
|
|
|
Therefore, none of the following names are valid by default:
|
|
|
|
.. code-block:: text
|
|
|
|
std
|
|
std1
|
|
std.foo
|
|
__test
|
|
// and so on ...
|
|
|
|
Using a reserved module name is strongly discouraged, but
|
|
``-Wno-reserved-module-identifier`` can be used to suppress the warning.
|
|
|
|
Specifying dependent BMIs
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
There are 3 ways to specify a dependent BMI:
|
|
|
|
1. ``-fprebuilt-module-path=<path/to/directory>``.
|
|
2. ``-fmodule-file=<path/to/BMI>`` (Deprecated).
|
|
3. ``-fmodule-file=<module-name>=<path/to/BMI>``.
|
|
|
|
The ``-fprebuilt-module-path`` option specifies the path to search for
|
|
dependent BMIs. Multiple paths may be specified, similar to using ``-I`` to
|
|
specify a search path for header files. When importing a module ``M``, the
|
|
compiler looks for ``M.pcm`` in the directories specified by
|
|
``-fprebuilt-module-path``. Similarly, when importing a partition module unit
|
|
``M:P``, the compiler looks for ``M-P.pcm`` in the directories specified by
|
|
``-fprebuilt-module-path``.
|
|
|
|
The ``-fmodule-file=<path/to/BMI>`` option causes the compiler to load the
|
|
specified BMI directly. The ``-fmodule-file=<module-name>=<path/to/BMI>``
|
|
option causes the compiler to load the specified BMI for the module specified
|
|
by ``<module-name>`` when necessary. The main difference is that
|
|
``-fmodule-file=<path/to/BMI>`` will load the BMI eagerly, whereas
|
|
``-fmodule-file=<module-name>=<path/to/BMI>`` will only load the BMI lazily,
|
|
as will ``-fprebuilt-module-path``. The ``-fmodule-file=<path/to/BMI>`` option
|
|
for named modules is deprecated and will be removed in a future version of
|
|
Clang.
|
|
|
|
When these options are specified in the same invocation of the compiler, the
|
|
``-fmodule-file=<path/to/BMI>`` option takes precedence over
|
|
``-fmodule-file=<module-name>=<path/to/BMI>``, which takes precedence over
|
|
``-fprebuilt-module-path=<path/to/directory>``.
|
|
|
|
Note: all dependant BMIs must be specified explicitly, either directly or
|
|
indirectly dependent BMIs explicitly. See
|
|
https://github.com/llvm/llvm-project/issues/62707 for details.
|
|
|
|
When compiling a ``module implementation unit``, the BMI of the corresponding
|
|
``primary module interface unit`` must be specified because a module
|
|
implementation unit implicitly imports the primary module interface unit.
|
|
|
|
[module.unit]p8
|
|
|
|
A module-declaration that contains neither an export-keyword nor a module-partition implicitly
|
|
imports the primary module interface unit of the module as if by a module-import-declaration.
|
|
|
|
The ``-fprebuilt-module-path=<path/to/directory>``, ``-fmodule-file=<path/to/BMI>``,
|
|
and ``-fmodule-file=<module-name>=<path/to/BMI>`` options may be specified
|
|
multiple times. For example, the command line to compile ``M.cppm`` in
|
|
the previous example could be rewritten as:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 M.cppm --precompile -fmodule-file=M:interface_part=M-interface_part.pcm -fmodule-file=M:impl_part=M-impl_part.pcm -o M.pcm
|
|
|
|
When there are multiple ``-fmodule-file=<module-name>=`` options for the same
|
|
``<module-name>``, the last ``-fmodule-file=<module-name>=`` overrides the
|
|
previous ``-fmodule-file=<module-name>=`` option.
|
|
|
|
Remember that module units still have an object counterpart to the BMI
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
While module interfaces resemble traditional header files, they still require
|
|
compilation. Module units are translation units, and need to be compiled to
|
|
object files, which then need to be linked together as the following examples
|
|
show.
|
|
|
|
For example, the traditional compilation processes for headers are like:
|
|
|
|
.. code-block:: text
|
|
|
|
src1.cpp -+> clang++ src1.cpp --> src1.o ---,
|
|
hdr1.h --' +-> clang++ src1.o src2.o -> executable
|
|
hdr2.h --, |
|
|
src2.cpp -+> clang++ src2.cpp --> src2.o ---'
|
|
|
|
And the compilation process for module units are like:
|
|
|
|
.. code-block:: text
|
|
|
|
src1.cpp ----------------------------------------+> clang++ src1.cpp -------> src1.o -,
|
|
(header unit) hdr1.h -> clang++ hdr1.h ... -> hdr1.pcm --' +-> clang++ src1.o mod1.o src2.o -> executable
|
|
mod1.cppm -> clang++ mod1.cppm ... -> mod1.pcm --,--> clang++ mod1.pcm ... -> mod1.o -+
|
|
src2.cpp ----------------------------------------+> clang++ src2.cpp -------> src2.o -'
|
|
|
|
As the diagrams show, we need to compile the BMI from module units to object
|
|
files and then link the object files. (However, this cannot be done for the BMI
|
|
from header units. See the section on :ref:`header units <header-units>` for
|
|
more details.
|
|
|
|
BMIs cannot be shipped in an archive to create a module library. Instead, the
|
|
BMIs(``*.pcm``) are compiled into object files(``*.o``) and those object files
|
|
are added to the archive instead.
|
|
|
|
clang-cl
|
|
~~~~~~~~
|
|
|
|
``clang-cl`` supports the same options as ``clang++`` for modules as detailed above;
|
|
there is no need to prefix these options with ``/clang:``. Note that ``cl.exe``
|
|
`options to emit/consume IFC files <https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/>` are *not* supported.
|
|
The resultant precompiled modules are also not compatible for use with ``cl.exe``.
|
|
|
|
We recommend that build system authors use the above-mentioned ``clang++`` options with ``clang-cl`` to build modules.
|
|
|
|
Consistency Requirements
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Modules can be viewed as a kind of cache to speed up compilation. Thus, like
|
|
other caching techniques, it is important to maintain cache consistency which
|
|
is why Clang does very strict checking for consistency.
|
|
|
|
Options consistency
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
Compiler options related to the language dialect for a module unit and its
|
|
non-module-unit uses need to be consistent. Consider the following example:
|
|
|
|
.. code-block:: c++
|
|
|
|
// M.cppm
|
|
export module M;
|
|
|
|
// Use.cpp
|
|
import M;
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
|
|
$ clang++ -std=c++23 Use.cpp -fprebuilt-module-path=.
|
|
|
|
Clang rejects the example due to the inconsistent language standard modes. Not
|
|
all compiler options are language dialect options, though. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
|
|
# Inconsistent optimization level.
|
|
$ clang++ -std=c++20 -O3 Use.cpp -fprebuilt-module-path=.
|
|
# Inconsistent debugging level.
|
|
$ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
|
|
|
|
Although the optimization and debugging levels are inconsistent, these
|
|
compilations are accepted because the compiler options do not impact the
|
|
language dialect.
|
|
|
|
Note that the compiler **currently** doesn't reject inconsistent macro
|
|
definitions (this may change in the future). For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
|
|
# Inconsistent optimization level.
|
|
$ clang++ -std=c++20 -O3 -DNDEBUG Use.cpp -fprebuilt-module-path=.
|
|
|
|
Currently, Clang accepts the above example, though it may produce surprising
|
|
results if the debugging code depends on consistent use of ``NDEBUG`` in other
|
|
translation units.
|
|
|
|
Source Files Consistency
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Clang may open the input files\ :sup:`1`` of a BMI during the compilation. This implies that
|
|
when Clang consumes a BMI, all the input files need to be present in the original path
|
|
and with the original contents.
|
|
|
|
To overcome these requirements and simplify cases like distributed builds and sandboxed
|
|
builds, users can use the ``-fmodules-embed-all-files`` flag to embed all input files
|
|
into the BMI so that Clang does not need to open the corresponding file on disk.
|
|
|
|
When the ``-fmodules-embed-all-files`` flag are enabled, Clang explicitly emits the source
|
|
code into the BMI file, the contents of the BMI file contain a sufficiently verbose
|
|
representation to reproduce the original source file.
|
|
|
|
:sup:`1`` Input files: The source files which took part in the compilation of the BMI.
|
|
For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
// M.cppm
|
|
module;
|
|
#include "foo.h"
|
|
export module M;
|
|
|
|
// foo.h
|
|
#pragma once
|
|
#include "bar.h"
|
|
|
|
The ``M.cppm``, ``foo.h`` and ``bar.h`` are input files for the BMI of ``M.cppm``.
|
|
|
|
Object definition consistency
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The C++ language requires that declarations of the same entity in different
|
|
translation units have the same definition, which is known as the One
|
|
Definition Rule (ODR). Without modules, the compiler cannot perform strong ODR
|
|
violation checking because it only sees one translation unit at a time. With
|
|
the use of modules, the compiler can perform checks for ODR violations across
|
|
translation units.
|
|
|
|
However, the current ODR checking mechanisms are not perfect. There are a
|
|
significant number of false positive ODR violation diagnostics, where the
|
|
compiler incorrectly diagnoses two identical declarations as having different
|
|
definitions. Further, true positive ODR violations are not always reported.
|
|
|
|
To give a better user experience, improve compilation performance, and for
|
|
consistency with MSVC, ODR checking of declarations in the global module
|
|
fragment is disabled by default. These checks can be enabled by specifying
|
|
``-Xclang -fno-skip-odr-check-in-gmf`` when compiling. If the check is enabled
|
|
and you encounter incorrect or missing diagnostics, please report them via the
|
|
`community issue tracker <https://github.com/llvm/llvm-project/issues/>`_.
|
|
|
|
Privacy Issue
|
|
-------------
|
|
|
|
BMIs are not and should not be treated as an information hiding mechanism.
|
|
They should always be assumed to contain all the information that was used to
|
|
create them, in a recoverable form.
|
|
|
|
ABI Impacts
|
|
-----------
|
|
|
|
This section describes the new ABI changes brought by modules. Only changes to
|
|
the Itanium C++ ABI are covered.
|
|
|
|
Name Mangling
|
|
~~~~~~~~~~~~~
|
|
|
|
The declarations in a module unit which are not in the global module fragment
|
|
have new linkage names.
|
|
|
|
For example,
|
|
|
|
.. code-block:: c++
|
|
|
|
export module M;
|
|
namespace NS {
|
|
export int foo();
|
|
}
|
|
|
|
The linkage name of ``NS::foo()`` is ``_ZN2NSW1M3fooEv``. This couldn't be
|
|
demangled by previous versions of the debugger or demangler. As of LLVM 15.x,
|
|
``llvm-cxxfilt`` can be used to demangle this:
|
|
|
|
.. code-block:: console
|
|
|
|
$ llvm-cxxfilt _ZN2NSW1M3fooEv
|
|
NS::foo@M()
|
|
|
|
The result should be read as ``NS::foo()`` in module ``M``.
|
|
|
|
The ABI implies that something cannot be declared in a module unit and defined
|
|
in a non-module unit (or vice-versa), as this would result in linking errors.
|
|
|
|
Despite this, it is possible to implement declarations with a compatible ABI in
|
|
a module unit by using a language linkage specifier because the declarations in
|
|
the language linkage specifier are attached to the global module fragment. For
|
|
example:
|
|
|
|
.. code-block:: c++
|
|
|
|
export module M;
|
|
namespace NS {
|
|
export extern "C++" int foo();
|
|
}
|
|
|
|
Now the linkage name of ``NS::foo()`` will be ``_ZN2NS3fooEv``.
|
|
|
|
Module Initializers
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
All importable module units are required to emit an initializer function to
|
|
handle the dynamic initialization of non-inline variables in the module unit.
|
|
The importable module unit has to emit the initializer even if there is no
|
|
dynamic initialization; otherwise, the importer may call a nonexistent
|
|
function. The initializer function emits calls to imported modules first
|
|
followed by calls to all to of the dynamic initializers in the current module
|
|
unit.
|
|
|
|
Translation units that explicitly or implicitly import a named module must call
|
|
the initializer functions of the imported named module within the sequence of
|
|
the dynamic initializers in the translation unit. Initializations of entities
|
|
at namespace scope are appearance-ordered. This (recursively) extends to
|
|
imported modules at the point of appearance of the import declaration.
|
|
|
|
If the imported module is known to be empty, the call to its initializer may be
|
|
omitted. Additionally, if the imported module is known to have already been
|
|
imported, the call to its initializer may be omitted.
|
|
|
|
Reduced BMI
|
|
-----------
|
|
|
|
To support the two-phase compilation model, Clang puts everything needed to
|
|
produce an object into the BMI. However, other consumers of the BMI generally
|
|
don't need that information. This makes the BMI larger and may introduce
|
|
unnecessary dependencies for the BMI. To mitigate the problem, Clang has a
|
|
compiler option to reduce the information contained in the BMI. These two
|
|
formats are known as Full BMI and Reduced BMI, respectively.
|
|
|
|
Users can use the ``-fmodules-reduced-bmi`` option to produce a
|
|
Reduced BMI.
|
|
|
|
For the one-phase compilation model (CMake implements this model), with
|
|
``-fmodules-reduced-bmi``, the generated BMI will be a Reduced
|
|
BMI automatically. (The output path of the BMI is specified by
|
|
``-fmodule-output=`` as usual with the one-phase compilation model).
|
|
|
|
It is also possible to produce a Reduced BMI with the two-phase compilation
|
|
model. When ``-fmodules-reduced-bmi``, ``--precompile``, and
|
|
``-fmodule-output=`` are specified, the generated BMI specified by ``-o`` will
|
|
be a full BMI and the BMI specified by ``-fmodule-output=`` will be a Reduced
|
|
BMI. The dependency graph in this case would look like:
|
|
|
|
.. code-block:: none
|
|
|
|
module-unit.cppm --> module-unit.full.pcm -> module-unit.o
|
|
|
|
|
-> module-unit.reduced.pcm -> consumer1.cpp
|
|
-> consumer2.cpp
|
|
-> ...
|
|
-> consumer_n.cpp
|
|
|
|
Clang does not emit diagnostics when ``-fmodules-reduced-bmi`` is
|
|
used with a non-module unit. This design permits users of the one-phase
|
|
compilation model to try using reduced BMIs without needing to modify the build
|
|
system. The two-phase compilation module requires build system support.
|
|
|
|
In a Reduced BMI, Clang does not emit unreachable entities from the global
|
|
module fragment, or definitions of non-inline functions and non-inline
|
|
variables. This may not be a transparent change.
|
|
|
|
Consider the following example:
|
|
|
|
.. code-block:: c++
|
|
|
|
// foo.h
|
|
namespace N {
|
|
struct X {};
|
|
int d();
|
|
int e();
|
|
inline int f(X, int = d()) { return e(); }
|
|
int g(X);
|
|
int h(X);
|
|
}
|
|
|
|
// M.cppm
|
|
module;
|
|
#include "foo.h"
|
|
export module M;
|
|
template<typename T> int use_f() {
|
|
N::X x; // N::X, N, and :: are decl-reachable from use_f
|
|
return f(x, 123); // N::f is decl-reachable from use_f,
|
|
// N::e is indirectly decl-reachable from use_f
|
|
// because it is decl-reachable from N::f, and
|
|
// N::d is decl-reachable from use_f
|
|
// because it is decl-reachable from N::f
|
|
// even though it is not used in this call
|
|
}
|
|
template<typename T> int use_g() {
|
|
N::X x; // N::X, N, and :: are decl-reachable from use_g
|
|
return g((T(), x)); // N::g is not decl-reachable from use_g
|
|
}
|
|
template<typename T> int use_h() {
|
|
N::X x; // N::X, N, and :: are decl-reachable from use_h
|
|
return h((T(), x)); // N::h is not decl-reachable from use_h, but
|
|
// N::h is decl-reachable from use_h<int>
|
|
}
|
|
int k = use_h<int>();
|
|
// use_h<int> is decl-reachable from k, so
|
|
// N::h is decl-reachable from k
|
|
|
|
// M-impl.cpp
|
|
module M;
|
|
int a = use_f<int>(); // OK
|
|
int b = use_g<int>(); // error: no viable function for call to g;
|
|
// g is not decl-reachable from purview of
|
|
// module M's interface, so is discarded
|
|
int c = use_h<int>(); // OK
|
|
|
|
In the above example, the function definition of ``N::g`` is elided from the
|
|
Reduced BMI of ``M.cppm``. Then the use of ``use_g<int>`` in ``M-impl.cpp``
|
|
fails to instantiate. For such issues, users can add references to ``N::g`` in
|
|
the `module purview <https://eel.is/c++draft/module.unit#5>`_ of ``M.cppm`` to
|
|
ensure it is reachable, e.g. ``using N::g;``.
|
|
|
|
Support for Reduced BMIs is still experimental, but it may become the default
|
|
in the future. The expected roadmap for Reduced BMIs as of Clang 19.x is:
|
|
|
|
1. ``-fexperimental-modules-reduced-bmi`` was introduced in v19.x
|
|
2. For v20.x, ``-fmodules-reduced-bmi`` is introduced as an equivalent non-experimental
|
|
option. It is expected to stay opt-in for 1~2 releases, though the period depends
|
|
on user feedback and may be extended.
|
|
3. Finally, ``-fmodules-reduced-bmi`` will be the default. When that time
|
|
comes, the term BMI will refer to the Reduced BMI and the Full BMI will only
|
|
be meaningful to build systems which elect to support two-phase compilation.
|
|
|
|
Experimental Non-Cascading Changes
|
|
----------------------------------
|
|
|
|
This section is primarily for build system vendors. For end compiler users,
|
|
if you don't want to read it all, this is helpful to reduce recompilations.
|
|
We encourage build system vendors and end users try this out and bring feedback.
|
|
|
|
Before Clang 19, a change in BMI of any (transitive) dependency would cause the
|
|
outputs of the BMI to change. Starting with Clang 19, changes to non-direct
|
|
dependencies should not directly affect the output BMI, unless they affect the
|
|
results of the compilations. We expect that there are many more opportunities
|
|
for this optimization than we currently have realized and would appreaciate
|
|
feedback about missed optimization opportunities. For example,
|
|
|
|
.. code-block:: c++
|
|
|
|
// m-partA.cppm
|
|
export module m:partA;
|
|
|
|
// m-partB.cppm
|
|
export module m:partB;
|
|
export int getB() { return 44; }
|
|
|
|
// m.cppm
|
|
export module m;
|
|
export import :partA;
|
|
export import :partB;
|
|
|
|
// useBOnly.cppm
|
|
export module useBOnly;
|
|
import m;
|
|
export int B() {
|
|
return getB();
|
|
}
|
|
|
|
// Use.cc
|
|
import useBOnly;
|
|
int get() {
|
|
return B();
|
|
}
|
|
|
|
To compile the project (for brevity, some commands are omitted.):
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
|
|
$ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
|
|
$ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
|
|
$ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
|
|
$ md5sum useBOnly.pcm
|
|
07656bf4a6908626795729295f9608da useBOnly.pcm
|
|
|
|
If the interface of ``m-partA.cppm`` is changed to:
|
|
|
|
.. code-block:: c++
|
|
|
|
// m-partA.v1.cppm
|
|
export module m:partA;
|
|
export int getA() { return 43; }
|
|
|
|
and the BMI for ``useBOnly`` is recompiled as in:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
|
|
$ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
|
|
$ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
|
|
$ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
|
|
$ md5sum useBOnly.pcm
|
|
07656bf4a6908626795729295f9608da useBOnly.pcm
|
|
|
|
then the contents of ``useBOnly.pcm`` remain unchanged.
|
|
Consequently, if the build system only bases recompilation decisions on directly imported modules,
|
|
it becomes possible to skip the recompilation of ``Use.cc``.
|
|
It should be fine because the altered interfaces do not affect ``Use.cc`` in any way;
|
|
the changes do not cascade.
|
|
|
|
When ``Clang`` generates a BMI, it records the hash values of all potentially contributory BMIs
|
|
for the BMI being produced. This ensures that build systems are not required to consider
|
|
transitively imported modules when deciding whether to recompile.
|
|
|
|
What is considered to be a potential contributory BMIs is currently unspecified.
|
|
However, it is a severe bug for a BMI to remain unchanged following an observable change
|
|
that affects its consumers.
|
|
|
|
Build systems may utilize this optimization by doing an update-if-changed operation to the BMI
|
|
that is consumed from the BMI that is output by the compiler.
|
|
|
|
We encourage build systems to add an experimental mode that
|
|
reuses the cached BMI when **direct** dependencies did not change,
|
|
even if **transitive** dependencies did change.
|
|
|
|
Given there are potential compiler bugs, we recommend that build systems
|
|
support this feature as a configurable option so that users
|
|
can go back to the transitive change mode safely at any time.
|
|
|
|
Interactions with Reduced BMI
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
With reduced BMI, non-cascading changes can be more powerful. For example,
|
|
|
|
.. code-block:: c++
|
|
|
|
// A.cppm
|
|
export module A;
|
|
export int a() { return 44; }
|
|
|
|
// B.cppm
|
|
export module B;
|
|
import A;
|
|
export int b() { return a(); }
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm -fmodules-reduced-bmi -o A.o
|
|
$ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
|
|
$ md5sum B.pcm
|
|
6c2bd452ca32ab418bf35cd141b060b9 B.pcm
|
|
|
|
And let's change the implementation for ``A.cppm`` into:
|
|
|
|
.. code-block:: c++
|
|
|
|
export module A;
|
|
int a_impl() { return 99; }
|
|
export int a() { return a_impl(); }
|
|
|
|
and recompile the example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm -fmodules-reduced-bmi -o A.o
|
|
$ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
|
|
$ md5sum B.pcm
|
|
6c2bd452ca32ab418bf35cd141b060b9 B.pcm
|
|
|
|
We should find the contents of ``B.pcm`` remains the same. In this case, the build system is
|
|
allowed to skip recompilations of TUs which solely and directly depend on module ``B``.
|
|
|
|
This only happens with a reduced BMI. With reduced BMIs, we won't record the function body
|
|
of ``int b()`` in the BMI for ``B`` so that the module ``A`` doesn't contribute to the BMI of ``B``
|
|
and we have less dependencies.
|
|
|
|
Performance Tips
|
|
----------------
|
|
|
|
Reduce duplications
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
While it is valid to have duplicated declarations in the global module fragments
|
|
of different module units, it is not free for Clang to deal with the duplicated
|
|
declarations. A translation unit will compile more slowly if there is a lot of
|
|
duplicated declarations between the translation unit and modules it imports.
|
|
For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
// M-partA.cppm
|
|
module;
|
|
#include "big.header.h"
|
|
export module M:partA;
|
|
...
|
|
|
|
// M-partB.cppm
|
|
module;
|
|
#include "big.header.h"
|
|
export module M:partB;
|
|
...
|
|
|
|
// other partitions
|
|
...
|
|
|
|
// M-partZ.cppm
|
|
module;
|
|
#include "big.header.h"
|
|
export module M:partZ;
|
|
...
|
|
|
|
// M.cppm
|
|
export module M;
|
|
export import :partA;
|
|
export import :partB;
|
|
...
|
|
export import :partZ;
|
|
|
|
// use.cpp
|
|
import M;
|
|
... // use declarations from module M.
|
|
|
|
When ``big.header.h`` is big enough and there are a lot of partitions, the
|
|
compilation of ``use.cpp`` may be significantly slower than the following
|
|
approach:
|
|
|
|
.. code-block:: c++
|
|
|
|
module;
|
|
#include "big.header.h"
|
|
export module m:big.header.wrapper;
|
|
export ... // export the needed declarations
|
|
|
|
// M-partA.cppm
|
|
export module M:partA;
|
|
import :big.header.wrapper;
|
|
...
|
|
|
|
// M-partB.cppm
|
|
export module M:partB;
|
|
import :big.header.wrapper;
|
|
...
|
|
|
|
// other partitions
|
|
...
|
|
|
|
// M-partZ.cppm
|
|
export module M:partZ;
|
|
import :big.header.wrapper;
|
|
...
|
|
|
|
// M.cppm
|
|
export module M;
|
|
export import :partA;
|
|
export import :partB;
|
|
...
|
|
export import :partZ;
|
|
|
|
// use.cpp
|
|
import M;
|
|
... // use declarations from module M.
|
|
|
|
Reducing the duplication from textual includes is what improves compile-time
|
|
performance.
|
|
|
|
To help users to identify such issues, we add a warning ``-Wdecls-in-multiple-modules``.
|
|
This warning is disabled by default and it needs to be explicitly enabled or by ``-Weverything``.
|
|
|
|
Transitioning to modules
|
|
------------------------
|
|
|
|
It is best for new code and libraries to use modules from the start if
|
|
possible. However, it may be a breaking change for existing code or libraries
|
|
to switch to modules. As a result, many existing libraries need to provide
|
|
both headers and module interfaces for a while to not break existing users.
|
|
|
|
This section suggests some suggestions on how to ease the transition process
|
|
for existing libraries. **Note that this information is only intended as
|
|
guidance, rather than as requirements to use modules in Clang.** It presumes
|
|
the project is starting with no module-based dependencies.
|
|
|
|
ABI non-breaking styles
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
export-using style
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: c++
|
|
|
|
module;
|
|
#include "header_1.h"
|
|
#include "header_2.h"
|
|
...
|
|
#include "header_n.h"
|
|
export module your_library;
|
|
export namespace your_namespace {
|
|
using decl_1;
|
|
using decl_2;
|
|
...
|
|
using decl_n;
|
|
}
|
|
|
|
This example shows how to include all the headers containing declarations which
|
|
need to be exported, and uses `using` declarations in an `export` block to
|
|
produce the module interface.
|
|
|
|
export extern-C++ style
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: c++
|
|
|
|
module;
|
|
#include "third_party/A/headers.h"
|
|
#include "third_party/B/headers.h"
|
|
...
|
|
#include "third_party/Z/headers.h"
|
|
export module your_library;
|
|
#define IN_MODULE_INTERFACE
|
|
extern "C++" {
|
|
#include "header_1.h"
|
|
#include "header_2.h"
|
|
...
|
|
#include "header_n.h"
|
|
}
|
|
|
|
Headers (from ``header_1.h`` to ``header_n.h``) need to define the macro:
|
|
|
|
.. code-block:: c++
|
|
|
|
#ifdef IN_MODULE_INTERFACE
|
|
#define EXPORT export
|
|
#else
|
|
#define EXPORT
|
|
#endif
|
|
|
|
and put ``EXPORT`` on the declarations you want to export.
|
|
|
|
Also, it is recommended to refactor headers to include third-party headers
|
|
conditionally:
|
|
|
|
.. code-block:: c++
|
|
|
|
#ifndef IN_MODULE_INTERFACE
|
|
#include "third_party/A/headers.h"
|
|
#endif
|
|
|
|
#include "header_x.h"
|
|
|
|
...
|
|
|
|
This can be helpful because it gives better diagnostic messages if the module
|
|
interface unit is not properly updated when modifying code.
|
|
|
|
This approach works because the declarations with language linkage are attached
|
|
to the global module. Thus, the ABI of the modular form of the library does not
|
|
change.
|
|
|
|
While this style is more involved than the export-using style, it makes it
|
|
easier to further refactor the library to other styles.
|
|
|
|
ABI breaking style
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
The term ``ABI breaking`` may sound like a bad approach. However, this style
|
|
forces consumers of the library use it in a consistent way. e.g., either always
|
|
include headers for the library or always import modules. The style prevents
|
|
the ability to mix includes and imports for the library.
|
|
|
|
The pattern for ABI breaking style is similar to the export extern-C++ style.
|
|
|
|
.. code-block:: c++
|
|
|
|
module;
|
|
#include "third_party/A/headers.h"
|
|
#include "third_party/B/headers.h"
|
|
...
|
|
#include "third_party/Z/headers.h"
|
|
export module your_library;
|
|
#define IN_MODULE_INTERFACE
|
|
#include "header_1.h"
|
|
#include "header_2.h"
|
|
...
|
|
#include "header_n.h"
|
|
|
|
#if the number of .cpp files in your project are small
|
|
module :private;
|
|
#include "source_1.cpp"
|
|
#include "source_2.cpp"
|
|
...
|
|
#include "source_n.cpp"
|
|
#else // the number of .cpp files in your project are a lot
|
|
// Using all the declarations from third-party libraries which are
|
|
// used in the .cpp files.
|
|
namespace third_party_namespace {
|
|
using third_party_decl_used_in_cpp_1;
|
|
using third_party_decl_used_in_cpp_2;
|
|
...
|
|
using third_party_decl_used_in_cpp_n;
|
|
}
|
|
#endif
|
|
|
|
(And add `EXPORT` and conditional include to the headers as suggested in the
|
|
export extern-C++ style section.)
|
|
|
|
The ABI with modules is different and thus we need to compile the source files
|
|
into the new ABI. This is done by an additional part of the interface unit:
|
|
|
|
.. code-block:: c++
|
|
|
|
#if the number of .cpp files in your project are small
|
|
module :private;
|
|
#include "source_1.cpp"
|
|
#include "source_2.cpp"
|
|
...
|
|
#include "source_n.cpp"
|
|
#else // the number of .cpp files in your project are a lot
|
|
// Using all the declarations from third-party libraries which are
|
|
// used in the .cpp files.
|
|
namespace third_party_namespace {
|
|
using third_party_decl_used_in_cpp_1;
|
|
using third_party_decl_used_in_cpp_2;
|
|
...
|
|
using third_party_decl_used_in_cpp_n;
|
|
}
|
|
#endif
|
|
|
|
If the number of source files is small, everything can be put in the private
|
|
module fragment directly (it is recommended to add conditional includes to the
|
|
source files as well). However, compile time performance will be bad if there
|
|
are a lot of source files to compile.
|
|
|
|
**Note that the private module fragment can only be in the primary module
|
|
interface unit and the primary module interface unit containing the private
|
|
module fragment should be the only module unit of the corresponding module.**
|
|
|
|
In this case, source files (.cpp files) must be converted to module
|
|
implementation units:
|
|
|
|
.. code-block:: c++
|
|
|
|
#ifndef IN_MODULE_INTERFACE
|
|
// List all the includes here.
|
|
#include "third_party/A/headers.h"
|
|
...
|
|
#include "header.h"
|
|
#endif
|
|
|
|
module your_library;
|
|
|
|
// Following off should be unchanged.
|
|
...
|
|
|
|
The module implementation unit will import the primary module implicitly. Do
|
|
not include any headers in the module implementation units as it avoids
|
|
duplicated declarations between translation units. This is why non-exported
|
|
using declarations should be added from third-party libraries in the primary
|
|
module interface unit.
|
|
|
|
If the library is provided as ``libyour_library.so``, a modular library (e.g.,
|
|
``libyour_library_modules.so``) may also need to be provided for ABI
|
|
compatibility.
|
|
|
|
What if there are headers only included by the source files
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The above practice may be problematic if there are headers only included by the
|
|
source files. When using a private module fragment, this issue may be solved by
|
|
including those headers in the private module fragment. While it is OK to solve
|
|
it by including the implementation headers in the module purview when using
|
|
implementation module units, it may be suboptimal because the primary module
|
|
interface units now contain entities that do not belong to the interface.
|
|
|
|
This can potentially be improved by introducing a module partition
|
|
implementation unit. An internal module partition unit is an importable
|
|
module unit which is internal to the module itself.
|
|
|
|
Providing a header to skip parsing redundant headers
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Many redeclarations shared between translation units causes Clang to have
|
|
slower compile-time performance. Further, there are known issues with
|
|
`include after import <https://github.com/llvm/llvm-project/issues/61465>`_.
|
|
Even when that issue is resolved, users may still get slower compilation speed
|
|
and larger BMIs. For these reasons, it is recommended to not include headers
|
|
after importing the corresponding module. However, it is not always easy if the
|
|
library is included by other dependencies, as in:
|
|
|
|
.. code-block:: c++
|
|
|
|
#include "third_party/A.h" // #include "your_library/a_header.h"
|
|
import your_library;
|
|
|
|
or
|
|
|
|
.. code-block:: c++
|
|
|
|
import your_library;
|
|
#include "third_party/A.h" // #include "your_library/a_header.h"
|
|
|
|
For such cases, it is best if the library providing both module and header
|
|
interfaces also provides a header which skips parsing so that the library can
|
|
be imported with the following approach that skips redundant redeclarations:
|
|
|
|
.. code-block:: c++
|
|
|
|
import your_library;
|
|
#include "your_library_imported.h"
|
|
#include "third_party/A.h" // #include "your_library/a_header.h" but got skipped
|
|
|
|
The implementation of ``your_library_imported.h`` can be a set of controlling
|
|
macros or an overall controlling macro if using `#pragma once`. Then headers
|
|
can be refactored to:
|
|
|
|
.. code-block:: c++
|
|
|
|
#pragma once
|
|
#ifndef YOUR_LIBRARY_IMPORTED
|
|
...
|
|
#endif
|
|
|
|
If the modules imported by the library provide such headers, remember to add
|
|
them to ``your_library_imported.h`` too.
|
|
|
|
Importing modules
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
When there are dependent libraries providing modules, they should be imported
|
|
in your module as well. Many existing libraries will fall into this category
|
|
once the ``std`` module is more widely available.
|
|
|
|
All dependent libraries providing modules
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Of course, most of the complexity disappears if all the dependent libraries
|
|
provide modules.
|
|
|
|
Headers need to be converted to include third-party headers conditionally. Then,
|
|
for the export-using style:
|
|
|
|
.. code-block:: c++
|
|
|
|
module;
|
|
import modules_from_third_party;
|
|
#define IN_MODULE_INTERFACE
|
|
#include "header_1.h"
|
|
#include "header_2.h"
|
|
...
|
|
#include "header_n.h"
|
|
export module your_library;
|
|
export namespace your_namespace {
|
|
using decl_1;
|
|
using decl_2;
|
|
...
|
|
using decl_n;
|
|
}
|
|
|
|
or, for the export extern-C++ style:
|
|
|
|
.. code-block:: c++
|
|
|
|
export module your_library;
|
|
import modules_from_third_party;
|
|
#define IN_MODULE_INTERFACE
|
|
extern "C++" {
|
|
#include "header_1.h"
|
|
#include "header_2.h"
|
|
...
|
|
#include "header_n.h"
|
|
}
|
|
|
|
or, for the ABI-breaking style,
|
|
|
|
.. code-block:: c++
|
|
|
|
export module your_library;
|
|
import modules_from_third_party;
|
|
#define IN_MODULE_INTERFACE
|
|
#include "header_1.h"
|
|
#include "header_2.h"
|
|
...
|
|
#include "header_n.h"
|
|
|
|
#if the number of .cpp files in your project are small
|
|
module :private;
|
|
#include "source_1.cpp"
|
|
#include "source_2.cpp"
|
|
...
|
|
#include "source_n.cpp"
|
|
#endif
|
|
|
|
Non-exported ``using`` declarations are unnecessary if using implementation
|
|
module units. Instead, third-party modules can be imported directly in
|
|
implementation module units.
|
|
|
|
Partial dependent libraries providing modules
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
If the library has to mix the use of ``include`` and ``import`` in its module,
|
|
the primary goal is still the removal of duplicated declarations in translation
|
|
units as much as possible. If the imported modules provide headers to skip
|
|
parsing their headers, those should be included after the import. If the
|
|
imported modules don't provide such a header, one can be made manually for
|
|
improved compile time performance.
|
|
|
|
Reachability of internal partition units
|
|
----------------------------------------
|
|
|
|
The internal partition units are sometimes called implementation partition units in other documentation.
|
|
However, the name may be confusing since implementation partition units are not implementation
|
|
units.
|
|
|
|
According to `[module.reach]p1 <https://eel.is/c++draft/module.reach#1>`_ and
|
|
`[module.reach]p2 <https://eel.is/c++draft/module.reach#2>`_ (from N4986):
|
|
|
|
A translation unit U is necessarily reachable from a point P if U is a module
|
|
interface unit on which the translation unit containing P has an interface
|
|
dependency, or the translation unit containing P imports U, in either case
|
|
prior to P.
|
|
|
|
All translation units that are necessarily reachable are reachable. Additional
|
|
translation units on which the point within the program has an interface
|
|
dependency may be considered reachable, but it is unspecified which are and
|
|
under what circumstances.
|
|
|
|
For example,
|
|
|
|
.. code-block:: c++
|
|
|
|
// a.cpp
|
|
import B;
|
|
int main()
|
|
{
|
|
g<void>();
|
|
}
|
|
|
|
// b.cppm
|
|
export module B;
|
|
import :C;
|
|
export template <typename T> inline void g() noexcept
|
|
{
|
|
return f<T>();
|
|
}
|
|
|
|
// c.cppm
|
|
module B:C;
|
|
template<typename> inline void f() noexcept {}
|
|
|
|
The internal partition unit ``c.cppm`` is not necessarily reachable by
|
|
``a.cpp`` because ``c.cppm`` is not a module interface unit and ``a.cpp``
|
|
doesn't import ``c.cppm``. This leaves it up to the compiler to decide if
|
|
``c.cppm`` is reachable by ``a.cpp`` or not. Clang's behavior is that
|
|
indirectly imported internal partition units are not reachable.
|
|
|
|
The suggested approach for using an internal partition unit in Clang is
|
|
to only import them in the implementation unit.
|
|
|
|
Known Issues
|
|
------------
|
|
|
|
The following describes issues in the current implementation of modules. Please
|
|
see
|
|
`the issues list for modules <https://github.com/llvm/llvm-project/labels/clang%3Amodules>`_
|
|
for a list of issues or to file a new issue if you don't find an existing one.
|
|
When creating a new issue for standard C++ modules, please start the title with
|
|
``[C++20] [Modules]`` (or ``[C++23] [Modules]``, etc) and add the label
|
|
``clang:modules`` if possible.
|
|
|
|
A high-level overview of support for standards features, including modules, can
|
|
be found on the `C++ Feature Status <https://clang.llvm.org/cxx_status.html>`_
|
|
page.
|
|
|
|
Including headers after import is not well-supported
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The following example is accepted:
|
|
|
|
.. code-block:: c++
|
|
|
|
#include <iostream>
|
|
import foo; // assume module 'foo' contain the declarations from `<iostream>`
|
|
|
|
int main(int argc, char *argv[])
|
|
{
|
|
std::cout << "Test\n";
|
|
return 0;
|
|
}
|
|
|
|
but if the order of ``#include <iostream>`` and ``import foo;`` is reversed,
|
|
then the code is currently rejected:
|
|
|
|
.. code-block:: c++
|
|
|
|
import foo; // assume module 'foo' contain the declarations from `<iostream>`
|
|
#include <iostream>
|
|
|
|
int main(int argc, char *argv[])
|
|
{
|
|
std::cout << "Test\n";
|
|
return 0;
|
|
}
|
|
|
|
Both of the above examples should be accepted.
|
|
|
|
This is a limitation of the implementation. In the first example, the compiler
|
|
will see and parse ``<iostream>`` first then it will see the ``import``. In
|
|
this case, ODR checking and declaration merging will happen in the
|
|
deserializer. In the second example, the compiler will see the ``import`` first
|
|
and the ``#include`` second which results in ODR checking and declarations
|
|
merging happening in the semantic analyzer. This is due to a divergence in the
|
|
implementation path. This is tracked by
|
|
`#61465 <https://github.com/llvm/llvm-project/issues/61465>`_.
|
|
|
|
Ignored ``preferred_name`` Attribute
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When Clang writes BMIs, it will ignore the ``preferred_name`` attribute on
|
|
declarations which use it. Thus, the preferred name will not be displayed in
|
|
the debugger as expected. This is tracked by
|
|
`#56490 <https://github.com/llvm/llvm-project/issues/56490>`_.
|
|
|
|
Don't emit macros about module declaration
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This is covered by `P1857R3 <https://wg21.link/P1857R3>`_. It is mentioned here
|
|
because we want users to be aware that we don't yet implement it.
|
|
|
|
A direct approach to write code that can be compiled by both modules and
|
|
non-module builds may look like:
|
|
|
|
.. code-block:: c++
|
|
|
|
MODULE
|
|
IMPORT header_name
|
|
EXPORT_MODULE MODULE_NAME;
|
|
IMPORT header_name
|
|
EXPORT ...
|
|
|
|
The intent of this is that this file can be compiled like a module unit or a
|
|
non-module unit depending on the definition of some macros. However, this usage
|
|
is forbidden by P1857R3 which is not yet implemented in Clang. This means that
|
|
is possible to write invalid modules which will no longer be accepted once
|
|
P1857R3 is implemented. This is tracked by
|
|
`#54047 <https://github.com/llvm/llvm-project/issues/54047>`_.
|
|
|
|
Until then, it is recommended not to mix macros with module declarations.
|
|
|
|
|
|
In consistent filename suffix requirement for importable module units
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Currently, Clang requires the file name of an ``importable module unit`` to
|
|
have ``.cppm`` (or ``.ccm``, ``.cxxm``, ``.c++m``) as the file extension.
|
|
However, the behavior is inconsistent with other compilers. This is tracked by
|
|
`#57416 <https://github.com/llvm/llvm-project/issues/57416>`_.
|
|
|
|
Incorrect ODR violation diagnostics
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
ODR violations are a common issue when using modules. Clang sometimes produces
|
|
false-positive diagnostics or fails to produce true-positive diagnostics of the
|
|
One Definition Rule. One often-reported example is:
|
|
|
|
.. code-block:: c++
|
|
|
|
// part.cc
|
|
module;
|
|
typedef long T;
|
|
namespace ns {
|
|
inline void fun() {
|
|
(void)(T)0;
|
|
}
|
|
}
|
|
export module repro:part;
|
|
|
|
// repro.cc
|
|
module;
|
|
typedef long T;
|
|
namespace ns {
|
|
using ::T;
|
|
}
|
|
namespace ns {
|
|
inline void fun() {
|
|
(void)(T)0;
|
|
}
|
|
}
|
|
export module repro;
|
|
export import :part;
|
|
|
|
Currently the compiler incorrectly diagnoses the inconsistent definition of
|
|
``fun()`` in two module units. Because both definitions of ``fun()`` have the
|
|
same spelling and ``T`` refers to the same type entity, there is no ODR
|
|
violation. This is tracked by
|
|
`#78850 <https://github.com/llvm/llvm-project/issues/78850>`_.
|
|
|
|
Using TU-local entity in other units
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Module units are translation units, so the entities which should be local to
|
|
the module unit itself should never be used by other units.
|
|
|
|
The C++ standard defines the concept of ``TU-local`` and ``exposure`` in
|
|
`basic.link/p14 <https://eel.is/c++draft/basic.link#14>`_,
|
|
`basic.link/p15 <https://eel.is/c++draft/basic.link#15>`_,
|
|
`basic.link/p16 <https://eel.is/c++draft/basic.link#16>`_,
|
|
`basic.link/p17 <https://eel.is/c++draft/basic.link#17>`_, and
|
|
`basic.link/p18 <https://eel.is/c++draft/basic.link#18>`_.
|
|
|
|
However, Clang doesn't formally support these two concepts. This results in
|
|
unclear or confusing diagnostic messages. Further, Clang may import
|
|
``TU-local`` entities to other units without any diagnostics. This is tracked
|
|
by `#78173 <https://github.com/llvm/llvm-project/issues/78173>`_.
|
|
|
|
.. _header-units:
|
|
|
|
Header Units
|
|
============
|
|
|
|
How to build projects using header units
|
|
----------------------------------------
|
|
|
|
.. warning::
|
|
|
|
The support for header units, including related command line options, is
|
|
experimental. There are still many unanswered question about how tools
|
|
should interact with header units. The details described here may change in
|
|
the future.
|
|
|
|
Quick Start
|
|
~~~~~~~~~~~
|
|
|
|
The following example:
|
|
|
|
.. code-block:: c++
|
|
|
|
import <iostream>;
|
|
int main() {
|
|
std::cout << "Hello World.\n";
|
|
}
|
|
|
|
could be compiled with:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
|
|
$ clang++ -std=c++20 -fmodule-file=iostream.pcm main.cpp
|
|
|
|
How to produce BMIs
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Similar to named modules, ``--precompile`` can be used to produce a BMI.
|
|
However, that requires specifying that the input file is a header by using
|
|
``-xc++-system-header`` or ``-xc++-user-header``.
|
|
|
|
The ``-fmodule-header={user,system}`` option can also be used to produce a BMI
|
|
for header units which have a file extension like `.h` or `.hh`. The argument to
|
|
``-fmodule-header`` specifies either the user search path or the system search
|
|
path. The default value for ``-fmodule-header`` is ``user``. For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
// foo.h
|
|
#include <iostream>
|
|
void Hello() {
|
|
std::cout << "Hello World.\n";
|
|
}
|
|
|
|
// use.cpp
|
|
import "foo.h";
|
|
int main() {
|
|
Hello();
|
|
}
|
|
|
|
could be compiled with:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 -fmodule-header foo.h -o foo.pcm
|
|
$ clang++ -std=c++20 -fmodule-file=foo.pcm use.cpp
|
|
|
|
For headers which do not have a file extension, ``-xc++-header`` (or
|
|
``-xc++-system-header``, ``-xc++-user-header``) must be used to specify the
|
|
file as a header. For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
// use.cpp
|
|
import "foo.h";
|
|
int main() {
|
|
Hello();
|
|
}
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 -fmodule-header=system -xc++-header iostream -o iostream.pcm
|
|
$ clang++ -std=c++20 -fmodule-file=iostream.pcm use.cpp
|
|
|
|
How to specify dependent BMIs
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
``-fmodule-file`` can be used to specify a dependent BMI (or multiple times for
|
|
more than one dependent BMI).
|
|
|
|
With the existing implementation, ``-fprebuilt-module-path`` cannot be used for
|
|
header units (because they are nominally anonymous). For header units, use
|
|
``-fmodule-file`` to include the relevant PCM file for each header unit.
|
|
|
|
This is expect to be solved in a future version of Clang either by the compiler
|
|
finding and specifying ``-fmodule-file`` automatically, or by the use of a
|
|
module-mapper that understands how to map the header name to their PCMs.
|
|
|
|
Compiling a header unit to an object file
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A header unit cannot be compiled to an object file due to the semantics of
|
|
header units. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
|
|
# This is not allowed!
|
|
$ clang++ iostream.pcm -c -o iostream.o
|
|
|
|
Include translation
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
The C++ standard allows vendors to convert ``#include header-name`` to
|
|
``import header-name;`` when possible. Currently, Clang does this translation
|
|
for the ``#include`` in the global module fragment. For example, the following
|
|
example:
|
|
|
|
.. code-block:: c++
|
|
|
|
module;
|
|
import <iostream>;
|
|
export module M;
|
|
export void Hello() {
|
|
std::cout << "Hello.\n";
|
|
}
|
|
|
|
is the same as this example:
|
|
|
|
.. code-block:: c++
|
|
|
|
module;
|
|
#include <iostream>
|
|
export module M;
|
|
export void Hello() {
|
|
std::cout << "Hello.\n";
|
|
}
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
|
|
$ clang++ -std=c++20 -fmodule-file=iostream.pcm --precompile M.cppm -o M.cpp
|
|
|
|
In the latter example, Clang can find the BMI for ``<iostream>`` and so it
|
|
tries to replace the ``#include <iostream>`` with ``import <iostream>;``
|
|
automatically.
|
|
|
|
|
|
Differences between Clang modules and header units
|
|
--------------------------------------------------
|
|
|
|
Header units have similar semantics to Clang modules. The semantics of both are
|
|
like headers. Therefore, header units can be mimicked by Clang modules as in
|
|
the following example:
|
|
|
|
.. code-block:: c++
|
|
|
|
module "iostream" {
|
|
export *
|
|
header "/path/to/libstdcxx/iostream"
|
|
}
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 -fimplicit-modules -fmodule-map-file=.modulemap main.cpp
|
|
|
|
This example is simplified when using libc++:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 main.cpp -fimplicit-modules -fimplicit-module-maps
|
|
|
|
because libc++ already supplies a
|
|
`module map <https://github.com/llvm/llvm-project/blob/main/libcxx/include/module.modulemap.in>`_.
|
|
|
|
This raises the question: why are header units not implemented through Clang
|
|
modules?
|
|
|
|
This is primarily because Clang modules have more hierarchical semantics when
|
|
wrapping multiple headers together as one module, which is not supported by
|
|
Standard C++ Header units. We want to avoid the impression that these
|
|
additional semantics get interpreted as Standard C++ behavior.
|
|
|
|
Another reason is that there are proposals to introduce module mappers to the
|
|
C++ standard (for example, https://wg21.link/p1184r2). Reusing Clang's
|
|
``modulemap`` may be more difficult if we need to introduce another module
|
|
mapper.
|
|
|
|
Discovering Dependencies
|
|
========================
|
|
|
|
Without use of modules, all the translation units in a project can be compiled
|
|
in parallel. However, the presence of module units requires compiling the
|
|
translation units in a topological order.
|
|
|
|
The ``clang-scan-deps`` tool can extract dependency information and produce a
|
|
JSON file conforming to the specification described in
|
|
`P1689 <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html>`_.
|
|
Only named modules are supported currently.
|
|
|
|
A compilation database is needed when using ``clang-scan-deps``. See
|
|
`JSON Compilation Database Format Specification <JSONCompilationDatabase.html>`_
|
|
for more information about compilation databases. Note that the ``output``
|
|
JSON attribute is necessary for ``clang-scan-deps`` to scan using the P1689
|
|
format. For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
//--- M.cppm
|
|
export module M;
|
|
export import :interface_part;
|
|
import :impl_part;
|
|
export int Hello();
|
|
|
|
//--- interface_part.cppm
|
|
export module M:interface_part;
|
|
export void World();
|
|
|
|
//--- Impl.cpp
|
|
module;
|
|
#include <iostream>
|
|
module M;
|
|
void Hello() {
|
|
std::cout << "Hello ";
|
|
}
|
|
|
|
//--- impl_part.cppm
|
|
module;
|
|
#include <string>
|
|
#include <iostream>
|
|
module M:impl_part;
|
|
import :interface_part;
|
|
|
|
std::string W = "World.";
|
|
void World() {
|
|
std::cout << W << std::endl;
|
|
}
|
|
|
|
//--- User.cpp
|
|
import M;
|
|
import third_party_module;
|
|
int main() {
|
|
Hello();
|
|
World();
|
|
return 0;
|
|
}
|
|
|
|
And here is the compilation database:
|
|
|
|
.. code-block:: text
|
|
|
|
[
|
|
{
|
|
"directory": ".",
|
|
"command": "<path-to-compiler-executable>/clang++ -std=c++20 M.cppm -c -o M.o",
|
|
"file": "M.cppm",
|
|
"output": "M.o"
|
|
},
|
|
{
|
|
"directory": ".",
|
|
"command": "<path-to-compiler-executable>/clang++ -std=c++20 Impl.cpp -c -o Impl.o",
|
|
"file": "Impl.cpp",
|
|
"output": "Impl.o"
|
|
},
|
|
{
|
|
"directory": ".",
|
|
"command": "<path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o",
|
|
"file": "impl_part.cppm",
|
|
"output": "impl_part.o"
|
|
},
|
|
{
|
|
"directory": ".",
|
|
"command": "<path-to-compiler-executable>/clang++ -std=c++20 interface_part.cppm -c -o interface_part.o",
|
|
"file": "interface_part.cppm",
|
|
"output": "interface_part.o"
|
|
},
|
|
{
|
|
"directory": ".",
|
|
"command": "<path-to-compiler-executable>/clang++ -std=c++20 User.cpp -c -o User.o",
|
|
"file": "User.cpp",
|
|
"output": "User.o"
|
|
}
|
|
]
|
|
|
|
To get the dependency information in P1689 format, use:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang-scan-deps -format=p1689 -compilation-database P1689.json
|
|
|
|
to get:
|
|
|
|
.. code-block:: text
|
|
|
|
{
|
|
"revision": 0,
|
|
"rules": [
|
|
{
|
|
"primary-output": "Impl.o",
|
|
"requires": [
|
|
{
|
|
"logical-name": "M",
|
|
"source-path": "M.cppm"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"primary-output": "M.o",
|
|
"provides": [
|
|
{
|
|
"is-interface": true,
|
|
"logical-name": "M",
|
|
"source-path": "M.cppm"
|
|
}
|
|
],
|
|
"requires": [
|
|
{
|
|
"logical-name": "M:interface_part",
|
|
"source-path": "interface_part.cppm"
|
|
},
|
|
{
|
|
"logical-name": "M:impl_part",
|
|
"source-path": "impl_part.cppm"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"primary-output": "User.o",
|
|
"requires": [
|
|
{
|
|
"logical-name": "M",
|
|
"source-path": "M.cppm"
|
|
},
|
|
{
|
|
"logical-name": "third_party_module"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"primary-output": "impl_part.o",
|
|
"provides": [
|
|
{
|
|
"is-interface": false,
|
|
"logical-name": "M:impl_part",
|
|
"source-path": "impl_part.cppm"
|
|
}
|
|
],
|
|
"requires": [
|
|
{
|
|
"logical-name": "M:interface_part",
|
|
"source-path": "interface_part.cppm"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"primary-output": "interface_part.o",
|
|
"provides": [
|
|
{
|
|
"is-interface": true,
|
|
"logical-name": "M:interface_part",
|
|
"source-path": "interface_part.cppm"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"version": 1
|
|
}
|
|
|
|
See the P1689 paper for the meaning of the fields.
|
|
|
|
Getting dependency information per file with finer-grained control (such as
|
|
scanning generated source files) is possible. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o
|
|
|
|
will produce:
|
|
|
|
.. code-block:: text
|
|
|
|
{
|
|
"revision": 0,
|
|
"rules": [
|
|
{
|
|
"primary-output": "impl_part.o",
|
|
"provides": [
|
|
{
|
|
"is-interface": false,
|
|
"logical-name": "M:impl_part",
|
|
"source-path": "impl_part.cppm"
|
|
}
|
|
],
|
|
"requires": [
|
|
{
|
|
"logical-name": "M:interface_part"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"version": 1
|
|
}
|
|
|
|
Individual command line options can be specified after ``--``.
|
|
``clang-scan-deps`` will extract the necessary information from the specified
|
|
options. Note that the path to the compiler executable needs to be specified
|
|
explicitly instead of using ``clang++`` directly.
|
|
|
|
Users may want the scanner to get the transitional dependency information for
|
|
headers. Otherwise, the project has to be scanned twice, once for headers and
|
|
once for modules. To address this, ``clang-scan-deps`` will recognize the
|
|
specified preprocessor options in the given command line and generate the
|
|
corresponding dependency information. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang-scan-deps -format=p1689 -- ../bin/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o -MD -MT impl_part.ddi -MF impl_part.dep
|
|
$ cat impl_part.dep
|
|
|
|
will produce:
|
|
|
|
.. code-block:: text
|
|
|
|
impl_part.ddi: \
|
|
/usr/include/bits/wchar.h /usr/include/bits/types/wint_t.h \
|
|
/usr/include/bits/types/mbstate_t.h \
|
|
/usr/include/bits/types/__mbstate_t.h /usr/include/bits/types/__FILE.h \
|
|
/usr/include/bits/types/FILE.h /usr/include/bits/types/locale_t.h \
|
|
/usr/include/bits/types/__locale_t.h \
|
|
...
|
|
|
|
When ``clang-scan-deps`` detects the ``-MF`` option, it will try to write the
|
|
dependency information for headers to the file specified by ``-MF``.
|
|
|
|
Possible Issues: Failed to find system headers
|
|
----------------------------------------------
|
|
|
|
If encountering an error like ``fatal error: 'stddef.h' file not found``,
|
|
the specified ``<path-to-compiler-executable>/clang++`` probably refers to a
|
|
symlink instead a real binary. There are four potential solutions to the
|
|
problem:
|
|
|
|
1. Point the specified compiler executable to the real binary instead of the
|
|
symlink.
|
|
2. Invoke ``<path-to-compiler-executable>/clang++ -print-resource-dir`` to get
|
|
the corresponding resource directory for your compiler and add that
|
|
directory to the include search paths manually in the build scripts.
|
|
3. For build systems that use a compilation database as the input for
|
|
``clang-scan-deps``, the build system can add the
|
|
``--resource-dir-recipe invoke-compiler`` option when executing
|
|
``clang-scan-deps`` to calculate the resource directory dynamically.
|
|
The calculation happens only once for a unique ``<path-to-compiler-executable>/clang++``.
|
|
4. For build systems that invoke ``clang-scan-deps`` per file, repeatedly
|
|
calculating the resource directory may be inefficient. In such cases, the
|
|
build system can cache the resource directory and specify
|
|
``-resource-dir <resource-dir>`` explicitly, as in:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 -resource-dir <resource-dir> mod.cppm -c -o mod.o
|
|
|
|
|
|
Import modules with clang-repl
|
|
==============================
|
|
|
|
``clang-repl`` supports importing C++20 named modules. For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
// M.cppm
|
|
export module M;
|
|
export const char* Hello() {
|
|
return "Hello Interpreter for Modules!";
|
|
}
|
|
|
|
The named module still needs to be compiled ahead of time.
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
|
|
$ clang++ M.pcm -c -o M.o
|
|
$ clang++ -shared M.o -o libM.so
|
|
|
|
Note that the module unit needs to be compiled as a dynamic library so that
|
|
``clang-repl`` can load the object files of the module units. Then it is
|
|
possible to import module ``M`` in clang-repl.
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang-repl -Xcc=-std=c++20 -Xcc=-fprebuilt-module-path=.
|
|
# We need to load the dynamic library first before importing the modules.
|
|
clang-repl> %lib libM.so
|
|
clang-repl> import M;
|
|
clang-repl> extern "C" int printf(const char *, ...);
|
|
clang-repl> printf("%s\n", Hello());
|
|
Hello Interpreter for Modules!
|
|
clang-repl> %quit
|
|
|
|
Possible Questions
|
|
==================
|
|
|
|
How modules speed up compilation
|
|
--------------------------------
|
|
|
|
A classic theory for the reason why modules speed up the compilation is: if
|
|
there are ``n`` headers and ``m`` source files and each header is included by
|
|
each source file, then the complexity of the compilation is ``O(n*m)``.
|
|
However, if there are ``n`` module interfaces and ``m`` source files, the
|
|
complexity of the compilation is ``O(n+m)``. Therefore, using modules would be
|
|
a significant improvement at scale. More simply, use of modules causes many of
|
|
the redundant compilations to no longer be necessary.
|
|
|
|
While this is accurate at a high level, this depends greatly on the
|
|
optimization level, as illustrated below.
|
|
|
|
First is ``-O0``. The compilation process is described in the following graph.
|
|
|
|
.. code-block:: none
|
|
|
|
├-------------frontend----------┼-------------middle end----------------┼----backend----┤
|
|
│ │ │ │
|
|
└---parsing----sema----codegen--┴----- transformations ---- codegen ----┴---- codegen --┘
|
|
|
|
├---------------------------------------------------------------------------------------┐
|
|
| │
|
|
| source file │
|
|
| │
|
|
└---------------------------------------------------------------------------------------┘
|
|
|
|
├--------┐
|
|
│ │
|
|
│imported│
|
|
│ │
|
|
│ code │
|
|
│ │
|
|
└--------┘
|
|
|
|
In this case, the source file (which could be a non-module unit or a module
|
|
unit) would get processed by the entire pipeline. However, the imported code
|
|
would only get involved in semantic analysis, which, for the most part, is name
|
|
lookup, overload resolution, and template instantiation. All of these processes
|
|
are fast relative to the whole compilation process. More importantly, the
|
|
imported code only needs to be processed once during frontend code generation,
|
|
as well as the whole middle end and backend. So we could get a big win for the
|
|
compilation time in ``-O0``.
|
|
|
|
But with optimizations, things are different (the ``code generation`` part for
|
|
each end is omitted due to limited space):
|
|
|
|
.. code-block:: none
|
|
|
|
├-------- frontend ---------┼--------------- middle end --------------------┼------ backend ----┤
|
|
│ │ │ │
|
|
└--- parsing ---- sema -----┴--- optimizations --- IPO ---- optimizations---┴--- optimizations -┘
|
|
|
|
├-----------------------------------------------------------------------------------------------┐
|
|
│ │
|
|
│ source file │
|
|
│ │
|
|
└-----------------------------------------------------------------------------------------------┘
|
|
├---------------------------------------┐
|
|
│ │
|
|
│ │
|
|
│ imported code │
|
|
│ │
|
|
│ │
|
|
└---------------------------------------┘
|
|
|
|
It would be very unfortunate if we end up with worse performance when using
|
|
modules. The main concern is that when a source file is compiled, the compiler
|
|
needs to see the body of imported module units so that it can perform IPO
|
|
(InterProcedural Optimization, primarily inlining in practice) to optimize
|
|
functions in the current source file with the help of the information provided
|
|
by the imported module units. In other words, the imported code would be
|
|
processed again and again in importee units by optimizations (including IPO
|
|
itself). The optimizations before IPO and IPO itself are the most time-consuming
|
|
part in whole compilation process. So from this perspective, it might not be
|
|
possible to get the compile time improvements described, but there could be
|
|
time savings for optimizations after IPO and the whole backend.
|
|
|
|
Overall, at ``-O0`` the implementations of functions defined in a module will
|
|
not impact module users, but at higher optimization levels the definitions of
|
|
such functions are provided to user compilations for the purposes of
|
|
optimization (but definitions of these functions are still not included in the
|
|
use's object file). This means the build speedup at higher optimization levels
|
|
may be lower than expected given ``-O0`` experience, but does provide more
|
|
optimization opportunities.
|
|
|
|
Interoperability with Clang Modules
|
|
-----------------------------------
|
|
|
|
We **wish** to support Clang modules and standard C++ modules at the same time,
|
|
but the mixing them together is not well used/tested yet. Please file new
|
|
GitHub issues as you find interoperability problems.
|