================ @@ -8,109 +8,91 @@ Standard C++ Modules Introduction ============ -The term ``modules`` has a lot of meanings. For the users of Clang, modules may -refer to ``Objective-C Modules``, ``Clang C++ Modules`` (or ``Clang Header Modules``, -etc.) or ``Standard C++ Modules``. The implementation of all these kinds of modules in Clang -has a lot of shared code, but from the perspective of users, their semantics and -command line interfaces are very different. This document focuses on -an introduction of how to use standard C++ modules in Clang. - -There is already a detailed document about `Clang modules <Modules.html>`_, it -should be helpful to read `Clang modules <Modules.html>`_ if you want to know -more about the general idea of modules. Since standard C++ modules have different semantics -(and work flows) from `Clang modules`, this page describes the background and use of -Clang with standard C++ modules. - -Modules exist in two forms in the C++ Language Specification. They can refer to -either "Named Modules" or to "Header Units". This document covers both forms. +The term ``module`` has a lot of meanings. 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 focuses on 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. + +Modules exist in two forms in the C++ Standard. They can refer to either +"Named Modules" or "Header Units". This document covers both forms. Standard C++ Named modules ========================== -This document was intended to be a manual first and foremost, however, we consider it helpful to -introduce some language background here for readers who are not familiar with -the new language feature. This document is not intended to be a language -tutorial; it will only introduce necessary concepts about the -structure and building of the project. +In order to understand compiler behavior, it is helpful to introduce 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 -------------------------- -Modules -~~~~~~~ - -In this document, the term ``Modules``/``modules`` refers to standard C++ modules -feature if it is not decorated by ``Clang``. - -Clang Modules -~~~~~~~~~~~~~ - -In this document, the term ``Clang Modules``/``Clang modules`` refer to Clang -c++ modules extension. These are also known as ``Clang header modules``, -``Clang module map modules`` or ``Clang c++ modules``. - Module and module unit ~~~~~~~~~~~~~~~~~~~~~~ -A module consists of one or more module units. A module unit is a special -translation unit. Every module unit must have a module declaration. The syntax -of the module declaration is: +A module consists of one or more module units. A module unit is a special kind +of translation unit. Every module unit must have a module declaration. The +syntax of the module declaration is: .. code-block:: c++ [export] module module_name[:partition_name]; -Terms enclosed in ``[]`` are optional. The syntax of ``module_name`` and ``partition_name`` -in regex form corresponds to ``[a-zA-Z_][a-zA-Z_0-9\.]*``. In particular, a literal dot ``.`` -in the name has no semantic meaning (e.g. implying a hierarchy). +Terms enclosed in ``[]`` are optional. ``module_name`` and ``partition_name`` +are typical C++ identifiers, except that they may contain a period (``.``). +Note that a ``.`` in the name has no semantic meaning (e.g. implying a +hierarchy or referring to the file system). -In this document, module units are classified into: +In this document, module units are classified as: -* Primary module interface unit. - -* Module implementation unit. - -* Module interface partition unit. - -* Internal module partition unit. +* Primary module interface unit +* Module implementation unit +* Module partition interface unit +* Module partition implementation unit A primary module interface unit is a module unit whose module declaration is -``export module module_name;``. The ``module_name`` here denotes the name of the +``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;``. A module could have multiple module implementation -units with the same declaration. +``module module_name;``. Multiple module implementation units can be declared +in the same translation unit. -A module interface partition unit is a module unit whose module declaration is +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. +An module partition implementation 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 umbrella terms: * A ``module interface unit`` refers to either a ``primary module interface unit`` - or a ``module interface partition unit``. + or a ``module partition interface unit``. -* An ``importable module unit`` refers to either a ``module interface unit`` - or a ``internal module partition unit``. +* An ``importable module unit`` refers to either a ``module interface unit`` or + an ``module partition implementation unit``. -* A ``module partition unit`` refers to either a ``module interface partition unit`` - or a ``internal module partition unit``. +* A ``module partition unit`` refers to either a ``module partition interface unit`` + or an ``module partition implementation unit``. -Built Module Interface file -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Binary Module Interface ---------------- ChuanqiXu9 wrote:
Maybe it is slightly `pedantic`. The term `Binary Module Interface` may make people wondering this is similar with `ABI`, which is a binary representation and an interface. But now the BMI is not like ABI since the compiler can't consume the BMI from different compilers even if they are from different versions. But maybe this is not a big deal really. https://github.com/llvm/llvm-project/pull/90237 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
