[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

https://github.com/AaronBallman closed 
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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -1753,91 +1742,93 @@ 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)``;
-But if there are ``n`` module interfaces and ``m`` source files, the 
complexity of the compilation is
-``O(n+m)``. So, using modules would be a big win when scaling.
-In a simpler word, we could get rid of many redundant compilations by using 
modules.
+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.
 
-Roughly, this theory is correct. But the problem is that it is too rough.
-The behavior depends on the optimization level, as we will illustrate below.
+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.
+First is ``-O0``. The compilation process is described in the following graph.
 
 .. code-block:: none
 
   ├-frontend--┼-middle 
end┼backend┤
   │   │   │
   │
   └---parsingsemacodegen--┴- transformations  codegen 
┴ codegen --┘
 
-  
┌---┐
+  
├---┐
   |
   │
   | source file
   │
   |
   │
   
└---┘
 
-  ┌┐
+  ├┐
   ││
   │imported│
   ││
   │  code  │
   ││
   └┘
 
-Here we can see that the source file (could be a non-module unit or a module 
unit) would get processed by the
-whole pipeline.
-But the imported code would only get involved in semantic analysis, which is 
mainly about 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 in 
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.
+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:
-
-(we omit ``code generation`` part for each end due to the limited space)
+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
   │
   │
   │
   
└---┘
- 

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -1753,91 +1742,93 @@ 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)``;
-But if there are ``n`` module interfaces and ``m`` source files, the 
complexity of the compilation is
-``O(n+m)``. So, using modules would be a big win when scaling.
-In a simpler word, we could get rid of many redundant compilations by using 
modules.
+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.
 
-Roughly, this theory is correct. But the problem is that it is too rough.
-The behavior depends on the optimization level, as we will illustrate below.
+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.
+First is ``-O0``. The compilation process is described in the following graph.
 
 .. code-block:: none
 
   ├-frontend--┼-middle 
end┼backend┤
   │   │   │
   │
   └---parsingsemacodegen--┴- transformations  codegen 
┴ codegen --┘
 
-  
┌---┐
+  
├---┐
   |
   │
   | source file
   │
   |
   │
   
└---┘
 
-  ┌┐
+  ├┐
   ││
   │imported│
   ││
   │  code  │
   ││
   └┘
 
-Here we can see that the source file (could be a non-module unit or a module 
unit) would get processed by the
-whole pipeline.
-But the imported code would only get involved in semantic analysis, which is 
mainly about 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 in 
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.
+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:
-
-(we omit ``code generation`` part for each end due to the limited space)
+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
   │
   │
   │
   
└---┘
- 

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -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 `_, it
-should be helpful to read `Clang modules `_ 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 `_ (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 

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

https://github.com/ChuanqiXu9 approved this pull request.

LGTM, thanks : )

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -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 `_, it
-should be helpful to read `Clang modules `_ 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 `_ (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 

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

https://github.com/ChuanqiXu9 edited 
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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -738,22 +736,21 @@ the following style significantly:
   import M;
   ... // use declarations from module M.
 
-The key part of the tip is to reduce the duplications from the text includes.
+Reducing the duplication from textual includes is what improves compile-time
+performance.
 
-Ideas for converting to modules

+Transitioning to modules
+
 
-For new libraries, we encourage them to use modules completely from day one if 
possible.
-This will be pretty helpful to make the whole ecosystems to get ready.
+New code and libraries should use modules from the start if possible. However,

ChuanqiXu9 wrote:

Yeah, I think so.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

AaronBallman wrote:

I think I've addressed all of the feedback (thank you all for the 
improvements!), except for the suggestion from @Endilll to switch to using 
italics rather than code font. I think the suggestion is a good one, but it's a 
time-consuming edit that doesn't change the meaning of the document, so I'd 
prefer that be done in a follow-up.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -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 `_, it
-should be helpful to read `Clang modules `_ 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 `_ (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

AaronBallman wrote:

Okay, I've reverted back to the old form.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -925,45 +923,41 @@ In that case, you need to convert your source files (.cpp 
files) to module imple
   // Following off should be unchanged.
   ...
 
-The module implementation unit will import the primary module implicitly.
-We don't include any headers in the module implementation units
-here since we want to avoid duplicated declarations between translation units.
-This is the reason why we add non-exported using declarations from the third
-party libraries in the primary module interface unit.
+The module implementation unit will import the primary module implicitly. Do
+not include any headers in the module implementation units because that avoids
+duplicated declarations between translation units. This is why non-exported
+using declarations are added from third-party libraries in the primary module
+interface unit.
 
-And if you provide your library as ``libyour_library.so``, you probably need to
-provide a modular one ``libyour_library_modules.so`` since you changed the ABI.
+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 inclued by the source files
 ^^
 
-The above practice may be problematic if there are headers only included by 
the source
-files. If you're using private module fragment, you may solve the issue by 
including them
-in the private module fragment. While it is OK to solve it by including the 
implementation
-headers in the module purview if you're using implementation module units, it 
may be
-suboptimal since the primary module interface units now containing entities 
not belongs
-to the interface.
-
-If you're a perfectionist, maybe you can improve it by introducing internal 
module partition unit.
+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.
 
-The internal module partition unit is an importable module unit which is 
internal
-to the module itself. The concept just meets the headers only included by the 
source files.
-
-We don't show code snippet since it may be too verbose or not good or not 
general.
-But it may not be too hard if you can understand the points of the section.
+This can potentially be improved by introducing module partition implementation
+unit. The module partition implementation unit is an importable module unit
+which is internal to the module itself. However, this approach may not always
+be the best way forward.

AaronBallman wrote:

Ah, I read the original wording wrong, I'll drop this sentence entirely.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -738,22 +736,21 @@ the following style significantly:
   import M;
   ... // use declarations from module M.
 
-The key part of the tip is to reduce the duplications from the text includes.
+Reducing the duplication from textual includes is what improves compile-time
+performance.
 
-Ideas for converting to modules

+Transitioning to modules
+
 
-For new libraries, we encourage them to use modules completely from day one if 
possible.
-This will be pretty helpful to make the whole ecosystems to get ready.
+New code and libraries should use modules from the start if possible. However,

AaronBallman wrote:

I reworded slightly to "It is best for new code and libraries to use modules 
from the start if possible." -- do you think that's an improvement?

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -400,24 +389,27 @@ And the compilation process for module units are like:
 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 link the object files.
-(But we can't do this for the BMI from header units. See the later section for 
the definition of header units)
+As the diagrams show, we need to compile the BMI from module units to object
+files and then link the object files. (However, we can't do this for the BMI
+from header units. See the section on :ref:`header units ` for
+more details.
 
-If we want to create a module library, we can't just ship the BMIs in an 
archive.
-We must compile these BMIs(``*.pcm``) into object files(``*.o``) and add those 
object files to the archive instead.
+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.
 
-Consistency Requirement
-~~~
+Consistency Requirements
+
 
-If we envision modules as a cache to speed up compilation, then - as with 
other caching techniques -
-it is important to keep cache consistency.
-So **currently** Clang will do very strict check for consistency.
+If modules are thought of as a kind of cache to speed up compilation, then, as
+with other caching techniques, it is important to keep cache consistency. Clang
+does very strict checking for that.
 
 Options consistency
 ^^^
 
-The language option of module units and their non-module-unit users should be 
consistent.
-The following example is not allowed:
+Language dialect compiler options for module units and their non-module-unit

AaronBallman wrote:

How about I go with "Compiler options related to the language dialect for a 
module unit and its non-module-unit uses need to be consistent."?

The problem is "language option" isn't sufficient, right? e.g., enabling 
`-fopenmp` in one place and not in the other would be just as much of a problem 
as setting `-std=c++20` in one place and not in the other.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -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 `_, it
-should be helpful to read `Clang modules `_ 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 `_ (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 

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -1391,17 +1381,17 @@ with the following one:
   $ 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, the Clang could find the BMI for the 
-so it would try to replace the ``#include `` to ``import 
;`` automatically.
+In the latter example, Clang can find the BMI for  and so it
+tries to replace the ``#include `` with ``import ;``
+automatically.
 
 
 Relationships between Clang modules
 ---
 
-Header units have pretty similar semantics with Clang modules.
-The semantics of both of them are like headers.
-
-In fact, we could even "mimic" the sytle of header units by Clang modules:
+Header units have similar semantics to Clang modules. The semantics of both are
+like headers. In fact, header units can be mimicked by Clang modules as in the

AaronBallman wrote:

I think we do mean Clang modules here, this is in a section about the 
relationship between C++ modules and Clang modules.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -633,36 +631,36 @@ example:
   // module M's interface, so is discarded
   int c = use_h();   // 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`` in ``M-impl.cpp`` fails
-to instantiate. For such issues, users can add references to ``N::g`` in the 
module purview
-of ``M.cppm`` to make sure it is reachable, e.g., ``using N::g;``.
-
-We think the Reduced BMI is the correct direction. But given it is a drastic 
change,
-we'd like to make it experimental first to avoid breaking existing users. The 
roadmap
-of Reduced BMI may be:
-
-1. ``-fexperimental-modules-reduced-bmi`` is opt in for 1~2 releases. The 
period depends
-on testing feedbacks.
-2. We would announce Reduced BMI is not experimental and introduce 
``-fmodules-reduced-bmi``.
-and suggest users to enable this mode. This may takes 1~2 releases too.
-3. Finally we will enable this by default. When that time comes, the term BMI 
will refer to
-the reduced BMI today and the Full BMI will only be meaningful to build 
systems which
-loves to support two phase compilations.
+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`` in ``M-impl.cpp``
+fails to instantiate. For such issues, users can add references to ``N::g`` in
+the module purview of ``M.cppm`` to ensure it is reachable, e.g.,

AaronBallman wrote:

https://eel.is/c++draft/module.unit#5, I'll add it as a link rather than try to 
explain it.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -400,24 +389,27 @@ And the compilation process for module units are like:
 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 link the object files.
-(But we can't do this for the BMI from header units. See the later section for 
the definition of header units)
+As the diagrams show, we need to compile the BMI from module units to object
+files and then link the object files. (However, we can't do this for the BMI
+from header units. See the section on :ref:`header units ` for
+more details.
 
-If we want to create a module library, we can't just ship the BMIs in an 
archive.
-We must compile these BMIs(``*.pcm``) into object files(``*.o``) and add those 
object files to the archive instead.
+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.
 
-Consistency Requirement
-~~~
+Consistency Requirements
+
 
-If we envision modules as a cache to speed up compilation, then - as with 
other caching techniques -
-it is important to keep cache consistency.
-So **currently** Clang will do very strict check for consistency.
+If modules are thought of as a kind of cache to speed up compilation, then, as

AaronBallman wrote:

I went with:

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.


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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -312,75 +300,76 @@ So all of the following name is not valid by default:
 __test
 // and so on ...
 
-If you still want to use the reserved module names for any reason, use
-``-Wno-reserved-module-identifier`` to suppress the warning.
+Using a reserved module name is strongly discouraged, but
+``-Wno-reserved-module-identifier`` can be used to suppress the warning.
 
-How to specify the dependent BMIs
-~
+Specifying dependent BMIs
+~
 
-There are 3 methods to specify the dependent BMIs:
+There are 3 ways to specify a dependent BMI:
 
-* (1) ``-fprebuilt-module-path=``.
-* (2) ``-fmodule-file=`` (Deprecated).
-* (3) ``-fmodule-file==``.
+1. ``-fprebuilt-module-path=``.
+2. ``-fmodule-file=`` (Deprecated).
+3. ``-fmodule-file==``.
 
-The option ``-fprebuilt-module-path`` tells the compiler the path where to 
search for dependent BMIs.
-It may be used multiple times just like ``-I`` for specifying paths for header 
files. The look up rule here is:
+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``.
 
-* (1) When we import module M. The compiler would look up M.pcm in the 
directories specified
-  by ``-fprebuilt-module-path``.
-* (2) When we import partition module unit M:P. The compiler would look up 
M-P.pcm in the
-  directories specified by ``-fprebuilt-module-path``.
-
-The option ``-fmodule-file=`` tells the compiler to load the 
specified BMI directly.
-The option ``-fmodule-file==`` tells the compiler to 
load the specified BMI
-for the module specified by  when necessary. The main 
difference is that
+The ``-fmodule-file=`` option causes the compiler to load the
+specified BMI directly. The ``-fmodule-file==``
+option causes the compiler to load the specified BMI for the module specified
+by  when necessary. The main difference is that
 ``-fmodule-file=`` will load the BMI eagerly, whereas
-``-fmodule-file==`` will only load the BMI lazily, 
which is similar
-with ``-fprebuilt-module-path``. The option ``-fmodule-file=`` 
for named modules is deprecated
-and is planning to be removed in future versions.
+``-fmodule-file==`` will only load the BMI lazily,
+which is similar to ``-fprebuilt-module-path``. The
+``-fmodule-file=`` option for named modules is deprecated and will
+be removed in a future version of Clang.
 
-In case all ``-fprebuilt-module-path=``, 
``-fmodule-file=`` and
-``-fmodule-file==`` exist, the 
``-fmodule-file=`` option
-takes highest precedence and ``-fmodule-file==`` 
will take the second
-highest precedence.
+When these options are specified in the same invocation of the compiler, the
+``-fmodule-file=`` option takes precedence over
+``-fmodule-file==``, which takes precedence over
+``-fprebuilt-module-path=``.
 
-We need to specify all the dependent (directly and indirectly) BMIs.
-See https://github.com/llvm/llvm-project/issues/62707 for detail.
+Note: you must specify all the (directly or indirectly) dependent BMIs
+explicitly. See https://github.com/llvm/llvm-project/issues/62707 for details.
 
-When we compile a ``module implementation unit``, we must specify the BMI of 
the corresponding
-``primary module interface unit``.
-Since the language specification says a module implementation unit implicitly 
imports
-the primary module interface unit.
+When compiling a ``module implementation unit``, the BMI of the corresponding
+``primary module interface unit`` must be specified. This is 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.
 
-All of the 3 options ``-fprebuilt-module-path=``, 
``-fmodule-file=``
-and ``-fmodule-file==`` may occur multiple times.
-For example, the command line to compile ``M.cppm`` in
-the above example could be rewritten into:
+The ``-fprebuilt-module-path=``, 
``-fmodule-file=``, 
+and ``-fmodule-file==`` 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==`` options for the same
-, the last ``-fmodule-file==`` will override the 
previous
-``-fmodule-file==`` options.
+, 

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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

AaronBallman wrote:

I changed it to "A module unit should almost always start with a module 
declaration." as that seems sufficiently hand-wavy.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

https://github.com/AaronBallman updated 
https://github.com/llvm/llvm-project/pull/90237

>From a75aa14fcad6f346a3073ae88e91fa890e803422 Mon Sep 17 00:00:00 2001
From: Aaron Ballman 
Date: Fri, 26 Apr 2024 13:12:51 -0400
Subject: [PATCH 1/2] Revise the modules document for clarity

The intention isn't to add or change the information provided, but to
improve clarity through some grammar fixes, improvements to the
markdown, and so forth.
---
 clang/docs/StandardCPlusPlusModules.rst | 1133 +++
 1 file changed, 561 insertions(+), 572 deletions(-)

diff --git a/clang/docs/StandardCPlusPlusModules.rst 
b/clang/docs/StandardCPlusPlusModules.rst
index ee57fb5da64857..e0ceb2582725c2 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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).
-
-In this document, module units are classified into:
-
-* Primary module interface unit.
-
-* Module implementation unit.
+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).
 
-* Module interface partition unit.

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -530,43 +527,43 @@ Now the linkage name of ``NS::foo()`` will be 
``_ZN2NS3fooEv``.
 Module Initializers
 ~~~
 
-All the importable module units are required to emit an initializer function.
-The initializer function should contain calls to importing modules first and
-all the dynamic-initializers in the current module unit then.
-
-Translation units explicitly or implicitly importing named modules must call
-the initializer functions of the imported named modules within the sequence of
-the dynamic-initializers in the TU. Initializations of entities at namespace
-scope are appearance-ordered. This (recursively) extends into imported modules
-at the point of appearance of the import declaration.
+All importable module units are required to emit an initializer function. The
+initializer function emits calls to imported modules first followed by calls
+to all to dynamic initializers in the current module unit.
 
-It is allowed to omit calls to importing modules if it is known empty.
+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.
 
-It is allowed to omit calls to importing modules for which is known to be 
called.
+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 2 phase compilation model, Clang chose to put everything needed 
to
-produce an object into the BMI. But every consumer of the BMI, except itself, 
doesn't
-need such informations. It makes the BMI to larger and so may introduce 
unnecessary
-dependencies into the BMI. To mitigate the problem, we decided to reduce the 
information
-contained in the 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 informations. This makes the BMI larger and may introduce
+unnecessary dependencies for the BMI. To mitigate the problem, Clang added a
+compiler option to reduce the information contained in the BMI. These two
+formats are known as Full BMI and Reduced BMI, respectively.
 
-To be clear, we call the default BMI as Full BMI and the new introduced BMI as 
Reduced
-BMI.
+Users can use the ``-fexperimental-modules-reduced-bmi`` option to produce a
+Reduced BMI.

ChuanqiXu9 wrote:

Do you mean `Reduced BMI`? The name was discussed in 
`https://discourse.llvm.org/t/rfc-c-20-modules-introduce-thin-bmi-and-decls-hash/74755/52`.

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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

ChuanqiXu9 wrote:

Technically not true: https://eel.is/c++draft/gram.basic#:translation-unit.

More specifically, a valid module unit may be:

```
module;
#include 
export module M;
...
```

Here the first `module;` keywords is not considered as module declaration.

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -577,15 +574,16 @@ the generated BMI specified by ``-o`` will be full BMI 
and the BMI specified by
-> ...
-> consumer_n.cpp
 
-We don't emit diagnostics if ``-fexperimental-modules-reduced-bmi`` is used 
with a non-module
-unit. This design helps the end users of one phase compilation model to 
perform experiments
-early without asking for the help of build systems. The users of build systems 
which supports
-two phase compilation model still need helps from build systems.
+Clang does not emit diagnostics when ``-fexperimental-modules-reduced-bmi`` is
+used with a non-module unit. This design helps the end users of the one-phase
+compilation model to perform experiments without needing to modify the build

ChuanqiXu9 wrote:

Or try Reduced BMI?

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -738,22 +736,21 @@ the following style significantly:
   import M;
   ... // use declarations from module M.
 
-The key part of the tip is to reduce the duplications from the text includes.
+Reducing the duplication from textual includes is what improves compile-time
+performance.
 
-Ideas for converting to modules

+Transitioning to modules
+
 
-For new libraries, we encourage them to use modules completely from day one if 
possible.
-This will be pretty helpful to make the whole ecosystems to get ready.
+New code and libraries should use modules from the start if possible. However,

ChuanqiXu9 wrote:

I am not sure if `should` is a too strong term from the non-native speaker 
perspective.

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

https://github.com/ChuanqiXu9 commented:

Big thanks!

I left some comments about correctness or clearness. And all other change looks 
good to me.

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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).
-
-In this document, module units are classified into:
-
-* Primary module interface unit.
-
-* Module implementation unit.
+Terms enclosed in ``[]`` are optional. ``module_name`` and ``partition_name``
+are typical C++ identifiers, except that they may contain a period (``.``).

ChuanqiXu9 wrote:

Yes

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -312,75 +300,76 @@ So all of the following name is not valid by default:
 __test
 // and so on ...
 
-If you still want to use the reserved module names for any reason, use
-``-Wno-reserved-module-identifier`` to suppress the warning.
+Using a reserved module name is strongly discouraged, but
+``-Wno-reserved-module-identifier`` can be used to suppress the warning.
 
-How to specify the dependent BMIs
-~
+Specifying dependent BMIs
+~
 
-There are 3 methods to specify the dependent BMIs:
+There are 3 ways to specify a dependent BMI:
 
-* (1) ``-fprebuilt-module-path=``.
-* (2) ``-fmodule-file=`` (Deprecated).
-* (3) ``-fmodule-file==``.
+1. ``-fprebuilt-module-path=``.
+2. ``-fmodule-file=`` (Deprecated).
+3. ``-fmodule-file==``.
 
-The option ``-fprebuilt-module-path`` tells the compiler the path where to 
search for dependent BMIs.
-It may be used multiple times just like ``-I`` for specifying paths for header 
files. The look up rule here is:
+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``.
 
-* (1) When we import module M. The compiler would look up M.pcm in the 
directories specified
-  by ``-fprebuilt-module-path``.
-* (2) When we import partition module unit M:P. The compiler would look up 
M-P.pcm in the
-  directories specified by ``-fprebuilt-module-path``.
-
-The option ``-fmodule-file=`` tells the compiler to load the 
specified BMI directly.
-The option ``-fmodule-file==`` tells the compiler to 
load the specified BMI
-for the module specified by  when necessary. The main 
difference is that
+The ``-fmodule-file=`` option causes the compiler to load the
+specified BMI directly. The ``-fmodule-file==``
+option causes the compiler to load the specified BMI for the module specified
+by  when necessary. The main difference is that
 ``-fmodule-file=`` will load the BMI eagerly, whereas
-``-fmodule-file==`` will only load the BMI lazily, 
which is similar
-with ``-fprebuilt-module-path``. The option ``-fmodule-file=`` 
for named modules is deprecated
-and is planning to be removed in future versions.
+``-fmodule-file==`` will only load the BMI lazily,
+which is similar to ``-fprebuilt-module-path``. The
+``-fmodule-file=`` option for named modules is deprecated and will
+be removed in a future version of Clang.
 
-In case all ``-fprebuilt-module-path=``, 
``-fmodule-file=`` and
-``-fmodule-file==`` exist, the 
``-fmodule-file=`` option
-takes highest precedence and ``-fmodule-file==`` 
will take the second
-highest precedence.
+When these options are specified in the same invocation of the compiler, the
+``-fmodule-file=`` option takes precedence over
+``-fmodule-file==``, which takes precedence over
+``-fprebuilt-module-path=``.
 
-We need to specify all the dependent (directly and indirectly) BMIs.
-See https://github.com/llvm/llvm-project/issues/62707 for detail.
+Note: you must specify all the (directly or indirectly) dependent BMIs
+explicitly. See https://github.com/llvm/llvm-project/issues/62707 for details.
 
-When we compile a ``module implementation unit``, we must specify the BMI of 
the corresponding
-``primary module interface unit``.
-Since the language specification says a module implementation unit implicitly 
imports
-the primary module interface unit.
+When compiling a ``module implementation unit``, the BMI of the corresponding
+``primary module interface unit`` must be specified. This is 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.
 
-All of the 3 options ``-fprebuilt-module-path=``, 
``-fmodule-file=``
-and ``-fmodule-file==`` may occur multiple times.
-For example, the command line to compile ``M.cppm`` in
-the above example could be rewritten into:
+The ``-fprebuilt-module-path=``, 
``-fmodule-file=``, 
+and ``-fmodule-file==`` 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==`` options for the same
-, the last ``-fmodule-file==`` will override the 
previous
-``-fmodule-file==`` options.
+, 

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -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 `_, it
-should be helpful to read `Clang modules `_ 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 `_ (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 

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -925,45 +923,41 @@ In that case, you need to convert your source files (.cpp 
files) to module imple
   // Following off should be unchanged.
   ...
 
-The module implementation unit will import the primary module implicitly.
-We don't include any headers in the module implementation units
-here since we want to avoid duplicated declarations between translation units.
-This is the reason why we add non-exported using declarations from the third
-party libraries in the primary module interface unit.
+The module implementation unit will import the primary module implicitly. Do
+not include any headers in the module implementation units because that avoids
+duplicated declarations between translation units. This is why non-exported
+using declarations are added from third-party libraries in the primary module
+interface unit.
 
-And if you provide your library as ``libyour_library.so``, you probably need to
-provide a modular one ``libyour_library_modules.so`` since you changed the ABI.
+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 inclued by the source files
 ^^
 
-The above practice may be problematic if there are headers only included by 
the source
-files. If you're using private module fragment, you may solve the issue by 
including them
-in the private module fragment. While it is OK to solve it by including the 
implementation
-headers in the module purview if you're using implementation module units, it 
may be
-suboptimal since the primary module interface units now containing entities 
not belongs
-to the interface.
-
-If you're a perfectionist, maybe you can improve it by introducing internal 
module partition unit.
+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.
 
-The internal module partition unit is an importable module unit which is 
internal
-to the module itself. The concept just meets the headers only included by the 
source files.
-
-We don't show code snippet since it may be too verbose or not good or not 
general.
-But it may not be too hard if you can understand the points of the section.
+This can potentially be improved by introducing module partition implementation
+unit. The module partition implementation unit is an importable module unit
+which is internal to the module itself. However, this approach may not always
+be the best way forward.

ChuanqiXu9 wrote:

Maybe I misunderstand the sentence "However, this approach may not always
be the best way forward." But it reads as, it is not good to use `module 
partition implementation unit`. This is not true.

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -400,24 +389,27 @@ And the compilation process for module units are like:
 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 link the object files.
-(But we can't do this for the BMI from header units. See the later section for 
the definition of header units)
+As the diagrams show, we need to compile the BMI from module units to object
+files and then link the object files. (However, we can't do this for the BMI
+from header units. See the section on :ref:`header units ` for
+more details.
 
-If we want to create a module library, we can't just ship the BMIs in an 
archive.
-We must compile these BMIs(``*.pcm``) into object files(``*.o``) and add those 
object files to the archive instead.
+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.
 
-Consistency Requirement
-~~~
+Consistency Requirements
+
 
-If we envision modules as a cache to speed up compilation, then - as with 
other caching techniques -
-it is important to keep cache consistency.
-So **currently** Clang will do very strict check for consistency.
+If modules are thought of as a kind of cache to speed up compilation, then, as
+with other caching techniques, it is important to keep cache consistency. Clang
+does very strict checking for that.
 
 Options consistency
 ^^^
 
-The language option of module units and their non-module-unit users should be 
consistent.
-The following example is not allowed:
+Language dialect compiler options for module units and their non-module-unit

ChuanqiXu9 wrote:

This is my first time to see the term `Language dialect compiler options`. 
Maybe it is better to explain the language option as compiler options may 
affect the semantics of the program if the term "language option" is not clear?



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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -216,51 +198,56 @@ We explain the options in the following sections.
 How to enable standard C++ modules
 ~~
 
-Currently, standard C++ modules are enabled automatically
-if the language standard is ``-std=c++20`` or newer.
+Standard C++ modules are enabled automatically if the language standard is
+``-std=c++20`` or newer.
 
 How to produce a BMI
 
 
-We can generate a BMI for an importable module unit by either ``--precompile``
-or ``-fmodule-output`` flags.
+To generate a BMI for an importable module unit, use either the 
``--precompile``
+or ``-fmodule-output`` command line option.
 
-The ``--precompile`` option generates the BMI as the output of the compilation 
and the output path
-can be specified using the ``-o`` option.
+The ``--precompile`` option generates the BMI as the output of the compilation
+and the output path can be 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 the specified 
location. Then 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 new extension ``.pcm``. 
Otherwise, the BMI
-will be emitted in the working directory with the name of the input file with 
the new extension
+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

ChuanqiXu9 wrote:

e.g,

```
clang++ a.cpp -c -o result/a.o
```

then `.` is the `working directory` and `./result` is the directory of the 
output file.

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -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 `_, it
-should be helpful to read `Clang modules `_ 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 `_ (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 

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -530,43 +527,43 @@ Now the linkage name of ``NS::foo()`` will be 
``_ZN2NS3fooEv``.
 Module Initializers
 ~~~
 
-All the importable module units are required to emit an initializer function.
-The initializer function should contain calls to importing modules first and
-all the dynamic-initializers in the current module unit then.
-
-Translation units explicitly or implicitly importing named modules must call
-the initializer functions of the imported named modules within the sequence of
-the dynamic-initializers in the TU. Initializations of entities at namespace
-scope are appearance-ordered. This (recursively) extends into imported modules
-at the point of appearance of the import declaration.
+All importable module units are required to emit an initializer function. The
+initializer function emits calls to imported modules first followed by calls
+to all to dynamic initializers in the current module unit.
 
-It is allowed to omit calls to importing modules if it is known empty.
+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.

ChuanqiXu9 wrote:

I feel it might not be related here?

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -633,36 +630,37 @@ example:
   // module M's interface, so is discarded
   int c = use_h();   // 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`` in ``M-impl.cpp`` fails
-to instantiate. For such issues, users can add references to ``N::g`` in the 
module purview
-of ``M.cppm`` to make sure it is reachable, e.g., ``using N::g;``.
-
-We think the Reduced BMI is the correct direction. But given it is a drastic 
change,
-we'd like to make it experimental first to avoid breaking existing users. The 
roadmap
-of Reduced BMI may be:
-
-1. ``-fexperimental-modules-reduced-bmi`` is opt in for 1~2 releases. The 
period depends
-on testing feedbacks.
-2. We would announce Reduced BMI is not experimental and introduce 
``-fmodules-reduced-bmi``.
-and suggest users to enable this mode. This may takes 1~2 releases too.
-3. Finally we will enable this by default. When that time comes, the term BMI 
will refer to
-the reduced BMI today and the Full BMI will only be meaningful to build 
systems which
-loves to support two phase compilations.
+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`` in ``M-impl.cpp``
+fails to instantiate. For such issues, users can add references to ``N::g`` in
+the module purview of ``M.cppm`` to ensure it is reachable, e.g.
+``using N::g;``.
+
+Long-term, Clang is likely to make Reduced BMIs the default rather than Full
+BMIs. Because it would be a drastic change of user interface, it is initially

ChuanqiXu9 wrote:

```suggestion
BMIs. Because it would be a drastic change, it is initially
```

not only the `user interface`, it requires some fundamental changes in the 
serializer, so there might be some bugs in the implementation.

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -312,75 +300,76 @@ So all of the following name is not valid by default:
 __test
 // and so on ...
 
-If you still want to use the reserved module names for any reason, use
-``-Wno-reserved-module-identifier`` to suppress the warning.
+Using a reserved module name is strongly discouraged, but
+``-Wno-reserved-module-identifier`` can be used to suppress the warning.
 
-How to specify the dependent BMIs
-~
+Specifying dependent BMIs
+~
 
-There are 3 methods to specify the dependent BMIs:
+There are 3 ways to specify a dependent BMI:

ChuanqiXu9 wrote:

If we have the following code:

```
// foo.cc
import a;
...
```

then we need a BMI of module `a` to compile `foo.cc`. Here the BMI of module 
`a` is the dependent BMI for `foo.cc`. I feel this clear. But if we don't think 
so, we can add a definition for that.

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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

https://github.com/ChuanqiXu9 edited 
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

[clang] Revise the modules document for clarity (PR #90237)

[Chuanqi Xu via cfe-commits]

@@ -530,43 +527,43 @@ Now the linkage name of ``NS::foo()`` will be 
``_ZN2NS3fooEv``.
 Module Initializers
 ~~~
 
-All the importable module units are required to emit an initializer function.
-The initializer function should contain calls to importing modules first and
-all the dynamic-initializers in the current module unit then.
-
-Translation units explicitly or implicitly importing named modules must call
-the initializer functions of the imported named modules within the sequence of
-the dynamic-initializers in the TU. Initializations of entities at namespace
-scope are appearance-ordered. This (recursively) extends into imported modules
-at the point of appearance of the import declaration.
+All importable module units are required to emit an initializer function. The

ChuanqiXu9 wrote:

They are required to handle the dynamic initializations of non-inline variables 
in the module unit. But the importable module units have to emit the 
initializer even if there is no dynamic initialization. Otherwise, the importer 
may calling a non-exist function.

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

[clang] Revise the modules document for clarity (PR #90237)

[Aaron Ballman via cfe-commits]

https://github.com/AaronBallman updated 
https://github.com/llvm/llvm-project/pull/90237

>From a75aa14fcad6f346a3073ae88e91fa890e803422 Mon Sep 17 00:00:00 2001
From: Aaron Ballman 
Date: Fri, 26 Apr 2024 13:12:51 -0400
Subject: [PATCH 1/2] Revise the modules document for clarity

The intention isn't to add or change the information provided, but to
improve clarity through some grammar fixes, improvements to the
markdown, and so forth.
---
 clang/docs/StandardCPlusPlusModules.rst | 1133 +++
 1 file changed, 561 insertions(+), 572 deletions(-)

diff --git a/clang/docs/StandardCPlusPlusModules.rst 
b/clang/docs/StandardCPlusPlusModules.rst
index ee57fb5da64857..e0ceb2582725c2 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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).
-
-In this document, module units are classified into:
-
-* Primary module interface unit.
-
-* Module implementation unit.
+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).
 
-* Module interface partition unit.

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -577,15 +574,16 @@ the generated BMI specified by ``-o`` will be full BMI 
and the BMI specified by
-> ...
-> consumer_n.cpp
 
-We don't emit diagnostics if ``-fexperimental-modules-reduced-bmi`` is used 
with a non-module
-unit. This design helps the end users of one phase compilation model to 
perform experiments
-early without asking for the help of build systems. The users of build systems 
which supports
-two phase compilation model still need helps from build systems.
+Clang does not emit diagnostics when ``-fexperimental-modules-reduced-bmi`` is
+used with a non-module unit. This design helps the end users of the one-phase
+compilation model to perform experiments without needing to modify the build
+system. The two-phase compilation module requires build system support.
 
-Within Reduced BMI, we won't write unreachable entities from GMF, definitions 
of non-inline
-functions and non-inline variables. This may not be a transparent change.
-`[module.global.frag]ex2 
`_ may be a good
-example:
+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.
+
+[module.global.frag]ex2 provides a good example:

cor3ntin wrote:

The specific c++ standard reference isn't useful. Just "consider the following 
example"

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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -577,15 +574,16 @@ the generated BMI specified by ``-o`` will be full BMI 
and the BMI specified by
-> ...
-> consumer_n.cpp
 
-We don't emit diagnostics if ``-fexperimental-modules-reduced-bmi`` is used 
with a non-module
-unit. This design helps the end users of one phase compilation model to 
perform experiments
-early without asking for the help of build systems. The users of build systems 
which supports
-two phase compilation model still need helps from build systems.
+Clang does not emit diagnostics when ``-fexperimental-modules-reduced-bmi`` is
+used with a non-module unit. This design helps the end users of the one-phase
+compilation model to perform experiments without needing to modify the build

cor3ntin wrote:

Perform experiments?

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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -400,24 +389,27 @@ And the compilation process for module units are like:
 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 link the object files.
-(But we can't do this for the BMI from header units. See the later section for 
the definition of header units)
+As the diagrams show, we need to compile the BMI from module units to object
+files and then link the object files. (However, we can't do this for the BMI
+from header units. See the section on :ref:`header units ` for
+more details.
 
-If we want to create a module library, we can't just ship the BMIs in an 
archive.
-We must compile these BMIs(``*.pcm``) into object files(``*.o``) and add those 
object files to the archive instead.
+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.
 
-Consistency Requirement
-~~~
+Consistency Requirements
+
 
-If we envision modules as a cache to speed up compilation, then - as with 
other caching techniques -
-it is important to keep cache consistency.
-So **currently** Clang will do very strict check for consistency.
+If modules are thought of as a kind of cache to speed up compilation, then, as
+with other caching techniques, it is important to keep cache consistency.
+**Currently**, Clang does very strict checking for consistency.

cor3ntin wrote:

The "currently" is not useful here

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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -633,36 +631,36 @@ example:
   // module M's interface, so is discarded
   int c = use_h();   // 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`` in ``M-impl.cpp`` fails
-to instantiate. For such issues, users can add references to ``N::g`` in the 
module purview
-of ``M.cppm`` to make sure it is reachable, e.g., ``using N::g;``.
-
-We think the Reduced BMI is the correct direction. But given it is a drastic 
change,
-we'd like to make it experimental first to avoid breaking existing users. The 
roadmap
-of Reduced BMI may be:
-
-1. ``-fexperimental-modules-reduced-bmi`` is opt in for 1~2 releases. The 
period depends
-on testing feedbacks.
-2. We would announce Reduced BMI is not experimental and introduce 
``-fmodules-reduced-bmi``.
-and suggest users to enable this mode. This may takes 1~2 releases too.
-3. Finally we will enable this by default. When that time comes, the term BMI 
will refer to
-the reduced BMI today and the Full BMI will only be meaningful to build 
systems which
-loves to support two phase compilations.
+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`` in ``M-impl.cpp``
+fails to instantiate. For such issues, users can add references to ``N::g`` in
+the module purview of ``M.cppm`` to ensure it is reachable, e.g.,
+``using N::g;``.
+
+Long-term, Clang is likely to make Reduced BMIs the default rather than Full

cor3ntin wrote:

Support for reduced BMI is still experimental but it might become the default 
in the future.

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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -530,43 +527,43 @@ Now the linkage name of ``NS::foo()`` will be 
``_ZN2NS3fooEv``.
 Module Initializers
 ~~~
 
-All the importable module units are required to emit an initializer function.
-The initializer function should contain calls to importing modules first and
-all the dynamic-initializers in the current module unit then.
-
-Translation units explicitly or implicitly importing named modules must call
-the initializer functions of the imported named modules within the sequence of
-the dynamic-initializers in the TU. Initializations of entities at namespace
-scope are appearance-ordered. This (recursively) extends into imported modules
-at the point of appearance of the import declaration.
+All importable module units are required to emit an initializer function. The
+initializer function emits calls to imported modules first followed by calls
+to all to dynamic initializers in the current module unit.
 
-It is allowed to omit calls to importing modules if it is known empty.
+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.
 
-It is allowed to omit calls to importing modules for which is known to be 
called.
+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 2 phase compilation model, Clang chose to put everything needed 
to
-produce an object into the BMI. But every consumer of the BMI, except itself, 
doesn't
-need such informations. It makes the BMI to larger and so may introduce 
unnecessary
-dependencies into the BMI. To mitigate the problem, we decided to reduce the 
information
-contained in the 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 informations. This makes the BMI larger and may introduce
+unnecessary dependencies for the BMI. To mitigate the problem, Clang added a
+compiler option to reduce the information contained in the BMI. These two
+formats are known as Full BMI and Reduced BMI, respectively.
 
-To be clear, we call the default BMI as Full BMI and the new introduced BMI as 
Reduced
-BMI.
+Users can use the ``-fexperimental-modules-reduced-bmi`` option to produce a
+Reduced BMI.

cor3ntin wrote:

We should find a better name in a subsequent pr

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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -444,53 +435,57 @@ For example, the following example is allowed:
   # Inconsistent debugging level.
   $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
 
-Although the two examples have inconsistent optimization and debugging level, 
both of them are accepted.
+Although the optimization and debugging levels are inconsistent, these
+compilations are accepted because the compiler options do not impact the
+language dialect.
 
-Note that **currently** the compiler doesn't consider inconsistent macro 
definition a problem. For example:
+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 would accept the above example. But it may produce surprising 
results if the
-debugging code depends on consistent use of ``NDEBUG`` also in other 
translation units.
-
-Definitions consistency
-^^^
-
-The C++ language defines that same declarations in different translation units 
should have
-the same definition, as known as ODR (One Definition Rule). Prior to modules, 
the translation
-units don't dependent on each other and the compiler itself can't perform a 
strong
-ODR violation check. With the introduction of modules, now the compiler have
-the chance to perform ODR violations with language semantics across 
translation units.
-
-However, in the practice, we found the existing ODR checking mechanism is not 
stable
-enough. Many people suffers from the false positive ODR violation diagnostics, 
AKA,
-the compiler are complaining two identical declarations have different 
definitions
-incorrectly. Also the true positive ODR violations are rarely reported.
-Also we learned that MSVC don't perform ODR check for declarations in the 
global module
-fragment.
-
-So in order to get better user experience, save the time checking ODR and keep 
consistent
-behavior with MSVC, we disabled the ODR check for the declarations in the 
global module
-fragment by default. Users who want more strict check can still use the
-``-Xclang -fno-skip-odr-check-in-gmf`` flag to get the ODR check enabled. It 
is also
-encouraged to report issues if users find false positive ODR violations or 
false negative ODR
-violations with the flag enabled.
+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.
+
+Object definition consistency
+^
+
+The C++ language requires that the same declarations in different translation
+units have the same definition, which is known as the One Definition Rule 
(ODR).
+Prior to modules, the compiler cannot perform strong ODR violation checking
+because it only sees one translation unit at a time. With 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.
+Additionally, MSVC does not currently perform ODR checking for declarations in
+the global module fragment.
+

cor3ntin wrote:

Why are we talking about msvc? The mention below is sufficient 

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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -530,43 +527,43 @@ Now the linkage name of ``NS::foo()`` will be 
``_ZN2NS3fooEv``.
 Module Initializers
 ~~~
 
-All the importable module units are required to emit an initializer function.
-The initializer function should contain calls to importing modules first and
-all the dynamic-initializers in the current module unit then.
-
-Translation units explicitly or implicitly importing named modules must call
-the initializer functions of the imported named modules within the sequence of
-the dynamic-initializers in the TU. Initializations of entities at namespace
-scope are appearance-ordered. This (recursively) extends into imported modules
-at the point of appearance of the import declaration.
+All importable module units are required to emit an initializer function. The
+initializer function emits calls to imported modules first followed by calls
+to all to dynamic initializers in the current module unit.
 
-It is allowed to omit calls to importing modules if it is known empty.
+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.
 
-It is allowed to omit calls to importing modules for which is known to be 
called.
+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 2 phase compilation model, Clang chose to put everything needed 
to
-produce an object into the BMI. But every consumer of the BMI, except itself, 
doesn't
-need such informations. It makes the BMI to larger and so may introduce 
unnecessary
-dependencies into the BMI. To mitigate the problem, we decided to reduce the 
information
-contained in the 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 informations. This makes the BMI larger and may introduce
+unnecessary dependencies for the BMI. To mitigate the problem, Clang added a

cor3ntin wrote:

added is weird. It should be more declarative/present tense.

Offers/has

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -1753,17 +1740,18 @@ 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)``;
-But if there are ``n`` module interfaces and ``m`` source files, the 
complexity of the compilation is
-``O(n+m)``. So, using modules would be a big win when scaling.
-In a simpler word, we could get rid of many redundant compilations by using 
modules.
+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)``. But if
+there are ``n`` module interfaces and ``m`` source files, the complexity of the
+compilation is ``O(n+m)``. So, using modules would be a big win when scaling.
+In a simpler word, we could get rid of many redundant compilations by using

erichkeane wrote:

```suggestion
More simply, modules causes much of the redundant compilations to no longer be 
necessary.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder

erichkeane wrote:

```suggestion
introduction to the use of C++20 modules in Clang. In the remainder
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -998,25 +992,23 @@ headers to:
   ...
   #endif
 
-If the modules imported by your library provides such headers too, remember to 
add them to
-your ``your_library_imported.h`` too.
+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, we suggest you to import 
that in
-your module.
-
-Most of the existing libraries would fall into this catagory once the std 
module gets available.
+When there are dependent libraries providing modules, they should be imported
+in your module as well. Many existing libraries will fall into this catagory
+once the ``std`` module is more widely available.
 
 All dependent libraries providing modules
 ^
 
-Life gets easier if all the dependent libraries providing modules.
+Life gets easier if all the dependent libraries provide modules.

erichkeane wrote:

```suggestion
Of course, most of the complexity disappears if all the dependent libraries 
provide modules.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -1222,33 +1214,31 @@ One often reported example is:
   export module repro;
   export import :part;
 
-Currently the compiler complains about the inconsistent definition of `fun()` 
in
-2 module units. This is incorrect. Since both definitions of `fun()` has the 
same
-spelling and `T` refers to the same type entity finally. So the program should 
be
-fine.
-
-This is tracked in https://github.com/llvm/llvm-project/issues/78850.
+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, so there is no ODR
+violation. This is tracked by
+`#78850 `_.
 
 Using TU-local entity in other units
 
 
-Module units are translation units. So the entities which should only be local 
to the
-module unit itself shouldn't be used by other units in any means.
+Module units are translation units, so the entities which should be local to
+the module unit itself should never be used by other units.
 
-In the language side, to address the idea formally, the language specification 
defines
-the concept of ``TU-local`` and ``exposure`` in
+The C++ standard defines the concept of ``TU-local`` and ``exposure`` in
 `basic.link/p14 `_,
 `basic.link/p15 `_,
 `basic.link/p16 `_,
-`basic.link/p17 `_ and
+`basic.link/p17 `_, and
 `basic.link/p18 `_.
 
-However, the compiler doesn't support these 2 ideas formally.
-This results in unclear and confusing diagnostic messages.
-And it is worse that the compiler may import TU-local entities to other units 
without any
-diagnostics.
+However, Clang doesn't formally support these two ideas. This results in
+unclear or confusing diagnostic messages. Further, Clang may import TU-local

erichkeane wrote:

```suggestion
unclear or confusing diagnostic messages. Further, Clang may import ``TU-local``
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -738,22 +736,21 @@ the following style significantly:
   import M;
   ... // use declarations from module M.
 
-The key part of the tip is to reduce the duplications from the text includes.
+Reducing the duplication from textual includes is what improves compile-time
+performance.
 
-Ideas for converting to modules

+Transitioning to modules
+
 
-For new libraries, we encourage them to use modules completely from day one if 
possible.
-This will be pretty helpful to make the whole ecosystems to get ready.
-
-For many existing libraries, it may be a breaking change to refactor themselves
-into modules completely. So that many existing libraries need to provide 
headers and module
+New code and libraries should use modules from day one if possible. However,
+it may be a breaking change for existing code or libraries to refactor to use
+modules. As a result, many existing libraries need to provide headers and 
module
 interfaces for a while to not break existing users.
-Here we provide some ideas to ease the transition process for existing 
libraries.
-**Note that the this section is only about helping ideas instead of 
requirement from clang**.
 
-Let's start with the case that there is no dependency or no dependent 
libraries providing
-modules for your library.
+This section provides some ideas on how to ease the transition process for
+existing libraries. **Note that this information is only intended as helpful

erichkeane wrote:

```suggestion
existing libraries. **Note that this information is only intended as guidance, 
rather than as requirements to use modules in Clang.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -925,45 +923,41 @@ In that case, you need to convert your source files (.cpp 
files) to module imple
   // Following off should be unchanged.
   ...
 
-The module implementation unit will import the primary module implicitly.
-We don't include any headers in the module implementation units
-here since we want to avoid duplicated declarations between translation units.
-This is the reason why we add non-exported using declarations from the third
-party libraries in the primary module interface unit.
+The module implementation unit will import the primary module implicitly. Do
+not include any headers in the module implementation units because that avoids
+duplicated declarations between translation units. This is why non-exported
+using declarations are added from third-party libraries in the primary module

erichkeane wrote:

```suggestion
using declarations should be added from third-party libraries in the primary 
module
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -738,22 +736,21 @@ the following style significantly:
   import M;
   ... // use declarations from module M.
 
-The key part of the tip is to reduce the duplications from the text includes.
+Reducing the duplication from textual includes is what improves compile-time
+performance.
 
-Ideas for converting to modules

+Transitioning to modules
+
 
-For new libraries, we encourage them to use modules completely from day one if 
possible.
-This will be pretty helpful to make the whole ecosystems to get ready.
-
-For many existing libraries, it may be a breaking change to refactor themselves
-into modules completely. So that many existing libraries need to provide 
headers and module
+New code and libraries should use modules from day one if possible. However,
+it may be a breaking change for existing code or libraries to refactor to use
+modules. As a result, many existing libraries need to provide headers and 
module
 interfaces for a while to not break existing users.
-Here we provide some ideas to ease the transition process for existing 
libraries.
-**Note that the this section is only about helping ideas instead of 
requirement from clang**.
 
-Let's start with the case that there is no dependency or no dependent 
libraries providing
-modules for your library.
+This section provides some ideas on how to ease the transition process for

erichkeane wrote:

```suggestion
This section provides some suggestions on how to ease the transition process for
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -577,15 +574,16 @@ the generated BMI specified by ``-o`` will be full BMI 
and the BMI specified by
-> ...
-> consumer_n.cpp
 
-We don't emit diagnostics if ``-fexperimental-modules-reduced-bmi`` is used 
with a non-module
-unit. This design helps the end users of one phase compilation model to 
perform experiments
-early without asking for the help of build systems. The users of build systems 
which supports
-two phase compilation model still need helps from build systems.
+Clang does not emit diagnostics when ``-fexperimental-modules-reduced-bmi`` is
+used with a non-module unit. This design helps the end users of the one-phase

erichkeane wrote:

```suggestion
used with a non-module unit. This design permits users of the one-phase
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -875,11 +872,11 @@ The pattern for ABI breaking style is similar with export 
extern-C++ style.
   }
   #endif
 
-(And add `EXPORT` and conditional include to the headers as suggested in the 
export
-extern-C++ style section)
+(And add `EXPORT` and conditional include to the headers as suggested in the
+export extern-C++ style section.)
 
-Remember that the ABI get changed and we need to compile our source files into 
the
-new ABI format. This is the job of the additional part of the interface unit:
+The ABI with modules is different and so we need to compile the source files

erichkeane wrote:

```suggestion
The ABI with modules is different and thus we need to compile the source files
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -216,51 +198,56 @@ We explain the options in the following sections.
 How to enable standard C++ modules
 ~~
 
-Currently, standard C++ modules are enabled automatically
-if the language standard is ``-std=c++20`` or newer.
+Standard C++ modules are enabled automatically if the language standard is
+``-std=c++20`` or newer.
 
 How to produce a BMI
 
 
-We can generate a BMI for an importable module unit by either ``--precompile``
-or ``-fmodule-output`` flags.
+To generate a BMI for an importable module unit, use either the 
``--precompile``
+or ``-fmodule-output`` command line option.
 
-The ``--precompile`` option generates the BMI as the output of the compilation 
and the output path
-can be specified using the ``-o`` option.
+The ``--precompile`` option generates the BMI as the output of the compilation
+and the output path can be 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 the specified 
location. Then 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 new extension ``.pcm``. 
Otherwise, the BMI
-will be emitted in the working directory with the name of the input file with 
the new extension
+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``.
 
-The style to generate BMIs by ``--precompile`` is called two-phase compilation 
since it takes
-2 steps to compile a source file to an object file. The style to generate BMIs 
by ``-fmodule-output``
-is called one-phase compilation respectively. The one-phase compilation model 
is simpler
-for build systems to implement and 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 would need to compile them serially, whereas the 
two-phase compilation
-model may be able to compile them simultaneously if the compilation from A.pcm 
to A.o takes a long
-time.
-
-File name requirement
-~
+Generating BMIs with ``--precompile`` is called 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 and 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 may be able to compile them simultaneously if

erichkeane wrote:

```suggestion
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.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -289,20 +277,20 @@ we can't compile them by the original command lines. But 
we are still able to do
   $ ./Hello.out
   Hello World!
 
-Module name requirement
-~~~
+Module name requirements
+
 
-[module.unit]p1 says:
+..
 
-.. code-block:: text
+  [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.
 
-So all of the following name is not valid by default:
+So none of the following names are valid by default:

erichkeane wrote:

```suggestion
Therefore, none of the following names are valid by default:
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -312,75 +300,76 @@ So all of the following name is not valid by default:
 __test
 // and so on ...
 
-If you still want to use the reserved module names for any reason, use
-``-Wno-reserved-module-identifier`` to suppress the warning.
+Using a reserved module name is strongly discouraged, but
+``-Wno-reserved-module-identifier`` can be used to suppress the warning.
 
-How to specify the dependent BMIs
-~
+Specifying dependent BMIs
+~
 
-There are 3 methods to specify the dependent BMIs:
+There are 3 ways to specify a dependent BMI:
 
-* (1) ``-fprebuilt-module-path=``.
-* (2) ``-fmodule-file=`` (Deprecated).
-* (3) ``-fmodule-file==``.
+1. ``-fprebuilt-module-path=``.
+2. ``-fmodule-file=`` (Deprecated).
+3. ``-fmodule-file==``.
 
-The option ``-fprebuilt-module-path`` tells the compiler the path where to 
search for dependent BMIs.
-It may be used multiple times just like ``-I`` for specifying paths for header 
files. The look up rule here is:
+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``.
 
-* (1) When we import module M. The compiler would look up M.pcm in the 
directories specified
-  by ``-fprebuilt-module-path``.
-* (2) When we import partition module unit M:P. The compiler would look up 
M-P.pcm in the
-  directories specified by ``-fprebuilt-module-path``.
-
-The option ``-fmodule-file=`` tells the compiler to load the 
specified BMI directly.
-The option ``-fmodule-file==`` tells the compiler to 
load the specified BMI
-for the module specified by  when necessary. The main 
difference is that
+The ``-fmodule-file=`` option causes the compiler to load the
+specified BMI directly. The ``-fmodule-file==``
+option causes the compiler to load the specified BMI for the module specified
+by  when necessary. The main difference is that
 ``-fmodule-file=`` will load the BMI eagerly, whereas
-``-fmodule-file==`` will only load the BMI lazily, 
which is similar
-with ``-fprebuilt-module-path``. The option ``-fmodule-file=`` 
for named modules is deprecated
-and is planning to be removed in future versions.
+``-fmodule-file==`` will only load the BMI lazily,
+which is similar to ``-fprebuilt-module-path``. The

erichkeane wrote:

```suggestion
as will ``-fprebuilt-module-path``. The
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -312,75 +300,76 @@ So all of the following name is not valid by default:
 __test
 // and so on ...
 
-If you still want to use the reserved module names for any reason, use
-``-Wno-reserved-module-identifier`` to suppress the warning.
+Using a reserved module name is strongly discouraged, but
+``-Wno-reserved-module-identifier`` can be used to suppress the warning.
 
-How to specify the dependent BMIs
-~
+Specifying dependent BMIs
+~
 
-There are 3 methods to specify the dependent BMIs:
+There are 3 ways to specify a dependent BMI:

erichkeane wrote:

WTF is a dependent BMI?

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -138,7 +120,7 @@ Let's see a "hello world" example that uses modules.
 return 0;
   }
 
-Then we type:
+From the command line, enter:

erichkeane wrote:

Then, on the command line, invoke clang like:

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -312,75 +300,76 @@ So all of the following name is not valid by default:
 __test
 // and so on ...
 
-If you still want to use the reserved module names for any reason, use
-``-Wno-reserved-module-identifier`` to suppress the warning.
+Using a reserved module name is strongly discouraged, but
+``-Wno-reserved-module-identifier`` can be used to suppress the warning.
 
-How to specify the dependent BMIs
-~
+Specifying dependent BMIs
+~
 
-There are 3 methods to specify the dependent BMIs:
+There are 3 ways to specify a dependent BMI:
 
-* (1) ``-fprebuilt-module-path=``.
-* (2) ``-fmodule-file=`` (Deprecated).
-* (3) ``-fmodule-file==``.
+1. ``-fprebuilt-module-path=``.
+2. ``-fmodule-file=`` (Deprecated).
+3. ``-fmodule-file==``.
 
-The option ``-fprebuilt-module-path`` tells the compiler the path where to 
search for dependent BMIs.
-It may be used multiple times just like ``-I`` for specifying paths for header 
files. The look up rule here is:
+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``.
 
-* (1) When we import module M. The compiler would look up M.pcm in the 
directories specified
-  by ``-fprebuilt-module-path``.
-* (2) When we import partition module unit M:P. The compiler would look up 
M-P.pcm in the
-  directories specified by ``-fprebuilt-module-path``.
-
-The option ``-fmodule-file=`` tells the compiler to load the 
specified BMI directly.
-The option ``-fmodule-file==`` tells the compiler to 
load the specified BMI
-for the module specified by  when necessary. The main 
difference is that
+The ``-fmodule-file=`` option causes the compiler to load the
+specified BMI directly. The ``-fmodule-file==``
+option causes the compiler to load the specified BMI for the module specified
+by  when necessary. The main difference is that
 ``-fmodule-file=`` will load the BMI eagerly, whereas
-``-fmodule-file==`` will only load the BMI lazily, 
which is similar
-with ``-fprebuilt-module-path``. The option ``-fmodule-file=`` 
for named modules is deprecated
-and is planning to be removed in future versions.
+``-fmodule-file==`` will only load the BMI lazily,
+which is similar to ``-fprebuilt-module-path``. The
+``-fmodule-file=`` option for named modules is deprecated and will
+be removed in a future version of Clang.
 
-In case all ``-fprebuilt-module-path=``, 
``-fmodule-file=`` and
-``-fmodule-file==`` exist, the 
``-fmodule-file=`` option
-takes highest precedence and ``-fmodule-file==`` 
will take the second
-highest precedence.
+When these options are specified in the same invocation of the compiler, the
+``-fmodule-file=`` option takes precedence over
+``-fmodule-file==``, which takes precedence over
+``-fprebuilt-module-path=``.
 
-We need to specify all the dependent (directly and indirectly) BMIs.
-See https://github.com/llvm/llvm-project/issues/62707 for detail.
+Note: you must specify all the (directly or indirectly) dependent BMIs
+explicitly. See https://github.com/llvm/llvm-project/issues/62707 for details.
 
-When we compile a ``module implementation unit``, we must specify the BMI of 
the corresponding
-``primary module interface unit``.
-Since the language specification says a module implementation unit implicitly 
imports
-the primary module interface unit.
+When compiling a ``module implementation unit``, the BMI of the corresponding
+``primary module interface unit`` must be specified. This is 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.
 
-All of the 3 options ``-fprebuilt-module-path=``, 
``-fmodule-file=``
-and ``-fmodule-file==`` may occur multiple times.
-For example, the command line to compile ``M.cppm`` in
-the above example could be rewritten into:
+The ``-fprebuilt-module-path=``, 
``-fmodule-file=``, 
+and ``-fmodule-file==`` 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==`` options for the same
-, the last ``-fmodule-file==`` will override the 
previous
-``-fmodule-file==`` options.
+, 

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -530,43 +527,43 @@ Now the linkage name of ``NS::foo()`` will be 
``_ZN2NS3fooEv``.
 Module Initializers
 ~~~
 
-All the importable module units are required to emit an initializer function.
-The initializer function should contain calls to importing modules first and
-all the dynamic-initializers in the current module unit then.
-
-Translation units explicitly or implicitly importing named modules must call
-the initializer functions of the imported named modules within the sequence of
-the dynamic-initializers in the TU. Initializations of entities at namespace
-scope are appearance-ordered. This (recursively) extends into imported modules
-at the point of appearance of the import declaration.
+All importable module units are required to emit an initializer function. The
+initializer function emits calls to imported modules first followed by calls
+to all to dynamic initializers in the current module unit.
 
-It is allowed to omit calls to importing modules if it is known empty.
+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.
 
-It is allowed to omit calls to importing modules for which is known to be 
called.
+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 2 phase compilation model, Clang chose to put everything needed 
to
-produce an object into the BMI. But every consumer of the BMI, except itself, 
doesn't
-need such informations. It makes the BMI to larger and so may introduce 
unnecessary
-dependencies into the BMI. To mitigate the problem, we decided to reduce the 
information
-contained in the 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 informations. This makes the BMI larger and may introduce

erichkeane wrote:

```suggestion
don't need that information. This makes the BMI larger and may introduce
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). The implementation of all these kinds of modules in
+Clang shares a lot of code, but from the perspective of users, their semantics

erichkeane wrote:

```suggestion
Clang shares a lot of code, but from the perspective of users their semantics
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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

erichkeane wrote:

```suggestion
of translation unit. Every module unit must start with a module declaration. The
```

If this is true?

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -530,43 +527,43 @@ Now the linkage name of ``NS::foo()`` will be 
``_ZN2NS3fooEv``.
 Module Initializers
 ~~~
 
-All the importable module units are required to emit an initializer function.
-The initializer function should contain calls to importing modules first and
-all the dynamic-initializers in the current module unit then.
-
-Translation units explicitly or implicitly importing named modules must call
-the initializer functions of the imported named modules within the sequence of
-the dynamic-initializers in the TU. Initializations of entities at namespace
-scope are appearance-ordered. This (recursively) extends into imported modules
-at the point of appearance of the import declaration.
+All importable module units are required to emit an initializer function. The

erichkeane wrote:

```suggestion
All importable module units are required to emit an initializer function to 
handle . The
```

ARE they required, or only if there is some sort of static initialization 
happening in the module?

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -444,53 +435,57 @@ For example, the following example is allowed:
   # Inconsistent debugging level.
   $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
 
-Although the two examples have inconsistent optimization and debugging level, 
both of them are accepted.
+Although the optimization and debugging levels are inconsistent, these
+compilations are accepted because the compiler options do not impact the
+language dialect.
 
-Note that **currently** the compiler doesn't consider inconsistent macro 
definition a problem. For example:
+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 would accept the above example. But it may produce surprising 
results if the
-debugging code depends on consistent use of ``NDEBUG`` also in other 
translation units.
-
-Definitions consistency
-^^^
-
-The C++ language defines that same declarations in different translation units 
should have
-the same definition, as known as ODR (One Definition Rule). Prior to modules, 
the translation
-units don't dependent on each other and the compiler itself can't perform a 
strong
-ODR violation check. With the introduction of modules, now the compiler have
-the chance to perform ODR violations with language semantics across 
translation units.
-
-However, in the practice, we found the existing ODR checking mechanism is not 
stable
-enough. Many people suffers from the false positive ODR violation diagnostics, 
AKA,
-the compiler are complaining two identical declarations have different 
definitions
-incorrectly. Also the true positive ODR violations are rarely reported.
-Also we learned that MSVC don't perform ODR check for declarations in the 
global module
-fragment.
-
-So in order to get better user experience, save the time checking ODR and keep 
consistent
-behavior with MSVC, we disabled the ODR check for the declarations in the 
global module
-fragment by default. Users who want more strict check can still use the
-``-Xclang -fno-skip-odr-check-in-gmf`` flag to get the ODR check enabled. It 
is also
-encouraged to report issues if users find false positive ODR violations or 
false negative ODR
-violations with the flag enabled.
+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.
+
+Object definition consistency
+^
+
+The C++ language requires that the same declarations in different translation
+units have the same definition, which is known as the One Definition Rule 
(ODR).
+Prior to modules, the compiler cannot perform strong ODR violation checking
+because it only sees one translation unit at a time. With use of modules, the

erichkeane wrote:

```suggestion
because it only sees one translation unit at a time. With the use of modules, 
the
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -1753,17 +1740,18 @@ 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)``;
-But if there are ``n`` module interfaces and ``m`` source files, the 
complexity of the compilation is
-``O(n+m)``. So, using modules would be a big win when scaling.
-In a simpler word, we could get rid of many redundant compilations by using 
modules.
+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)``. But if
+there are ``n`` module interfaces and ``m`` source files, the complexity of the
+compilation is ``O(n+m)``. So, using modules would be a big win when scaling.
+In a simpler word, we could get rid of many redundant compilations by using
+modules.
 
-Roughly, this theory is correct. But the problem is that it is too rough.
-The behavior depends on the optimization level, as we will illustrate below.
+Roughly, this theory is correct. But the problem is that it is too rough. The

erichkeane wrote:

```suggestion
While this is accurate at a high level, this depends greatly on optimization 
level, as illustrated below.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -633,36 +631,36 @@ example:
   // module M's interface, so is discarded
   int c = use_h();   // 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`` in ``M-impl.cpp`` fails
-to instantiate. For such issues, users can add references to ``N::g`` in the 
module purview
-of ``M.cppm`` to make sure it is reachable, e.g., ``using N::g;``.
-
-We think the Reduced BMI is the correct direction. But given it is a drastic 
change,
-we'd like to make it experimental first to avoid breaking existing users. The 
roadmap
-of Reduced BMI may be:
-
-1. ``-fexperimental-modules-reduced-bmi`` is opt in for 1~2 releases. The 
period depends
-on testing feedbacks.
-2. We would announce Reduced BMI is not experimental and introduce 
``-fmodules-reduced-bmi``.
-and suggest users to enable this mode. This may takes 1~2 releases too.
-3. Finally we will enable this by default. When that time comes, the term BMI 
will refer to
-the reduced BMI today and the Full BMI will only be meaningful to build 
systems which
-loves to support two phase compilations.
+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`` in ``M-impl.cpp``
+fails to instantiate. For such issues, users can add references to ``N::g`` in
+the module purview of ``M.cppm`` to ensure it is reachable, e.g.,

erichkeane wrote:

what is 'module purview' here?  Do we just mean "in the `M` module"?

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -530,43 +527,43 @@ Now the linkage name of ``NS::foo()`` will be 
``_ZN2NS3fooEv``.
 Module Initializers
 ~~~
 
-All the importable module units are required to emit an initializer function.
-The initializer function should contain calls to importing modules first and
-all the dynamic-initializers in the current module unit then.
-
-Translation units explicitly or implicitly importing named modules must call
-the initializer functions of the imported named modules within the sequence of
-the dynamic-initializers in the TU. Initializations of entities at namespace
-scope are appearance-ordered. This (recursively) extends into imported modules
-at the point of appearance of the import declaration.
+All importable module units are required to emit an initializer function. The
+initializer function emits calls to imported modules first followed by calls
+to all to dynamic initializers in the current module unit.

erichkeane wrote:

```suggestion
to all of the dynamic initializers in the current module unit.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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).
-
-In this document, module units are classified into:
-
-* Primary module interface unit.
-
-* Module implementation unit.
+Terms enclosed in ``[]`` are optional. ``module_name`` and ``partition_name``
+are typical C++ identifiers, except that they may contain a period (``.``).

erichkeane wrote:

```suggestion
follow the rules of C++ identifiers, except that they may contain the period 
(``.``) character.
```

Not limtied to just 1 period, right?

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -216,51 +198,56 @@ We explain the options in the following sections.
 How to enable standard C++ modules
 ~~
 
-Currently, standard C++ modules are enabled automatically
-if the language standard is ``-std=c++20`` or newer.
+Standard C++ modules are enabled automatically if the language standard is
+``-std=c++20`` or newer.
 
 How to produce a BMI
 
 
-We can generate a BMI for an importable module unit by either ``--precompile``
-or ``-fmodule-output`` flags.
+To generate a BMI for an importable module unit, use either the 
``--precompile``
+or ``-fmodule-output`` command line option.

erichkeane wrote:

```suggestion
or ``-fmodule-output`` command line options.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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

erichkeane wrote:

```suggestion
and command line interfaces are very different. This document is an
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` will refer to the Clang modules extension.

erichkeane wrote:

```suggestion
the term ``Clang modules`` will refer to the Clang Modules extension.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -216,51 +198,56 @@ We explain the options in the following sections.
 How to enable standard C++ modules
 ~~
 
-Currently, standard C++ modules are enabled automatically
-if the language standard is ``-std=c++20`` or newer.
+Standard C++ modules are enabled automatically if the language standard is
+``-std=c++20`` or newer.
 
 How to produce a BMI
 
 
-We can generate a BMI for an importable module unit by either ``--precompile``
-or ``-fmodule-output`` flags.
+To generate a BMI for an importable module unit, use either the 
``--precompile``
+or ``-fmodule-output`` command line option.
 
-The ``--precompile`` option generates the BMI as the output of the compilation 
and the output path
-can be specified using the ``-o`` option.
+The ``--precompile`` option generates the BMI as the output of the compilation
+and the output path can be specified using the ``-o`` option.

erichkeane wrote:

```suggestion
with the output path specified using the ``-o`` option.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -95,22 +76,23 @@ In this document, we use the following umbrella terms:
 * A ``module interface unit`` refers to either a ``primary module interface 
unit``

erichkeane wrote:

^^ Line above but github wont let me: Don't use 'umbrella', its probably not a 
familiar term to foreign speakers.  Perhaps omit it entirely?

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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

erichkeane wrote:

```suggestion
In order to better understand compiler's behavior, it is helpful to understand
some concepts of the C++ language.This document is not a tutorial on C++; it 
only introduces concepts necessary to understand the use of modules for a 
project.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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).
-
-In this document, module units are classified into:
-
-* Primary module interface unit.
-
-* Module implementation unit.
+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

erichkeane wrote:

```suggestion
Note that a ``.`` in the name has no semantic meaning and does not imply any 
hierarchy.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer

erichkeane wrote:

```suggestion
The term ``modules`` is ambiguous, as it is used to mean multiple things in 
Clang: modules may refer
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Erich Keane via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` will refer to the Clang modules extension.
+
+Modules exist in two forms in the C++ Standard. They can refer to either

erichkeane wrote:

```suggestion
In terms of the C++ Standard, Modules consist of two components: "Named 
Modules" or "Header Units". This document covers both .
```

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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or

cor3ntin wrote:

Etc?

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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -95,22 +76,23 @@ 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``.
 
-* 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 ``internal module partition unit``.
 
 * A ``module partition unit`` refers to either a ``module interface partition 
unit``
-  or a ``internal module partition unit``.
+  or an ``internal module partition unit``.
 

cor3ntin wrote:

https://learn.microsoft.com/en-us/cpp/cpp/modules-cpp?view=msvc-170

S/internal/implementation 


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

[clang] Revise the modules document for clarity (PR #90237)

[via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here for readers who are not familiar with the C++ feature.

cor3ntin wrote:

Terms and definitions, or something like that.

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -738,22 +736,21 @@ the following style significantly:
   import M;
   ... // use declarations from module M.
 
-The key part of the tip is to reduce the duplications from the text includes.
+Reducing the duplication from textual includes is what improves compile-time
+performance.
 
-Ideas for converting to modules

+Transitioning to modules
+
 
-For new libraries, we encourage them to use modules completely from day one if 
possible.
-This will be pretty helpful to make the whole ecosystems to get ready.
-
-For many existing libraries, it may be a breaking change to refactor themselves
-into modules completely. So that many existing libraries need to provide 
headers and module
+New code and libraries should use modules from day one if possible. However,

Endilll wrote:

```suggestion
New code and libraries should use modules from day 1 if possible. However,
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -738,22 +736,21 @@ the following style significantly:
   import M;
   ... // use declarations from module M.
 
-The key part of the tip is to reduce the duplications from the text includes.
+Reducing the duplication from textual includes is what improves compile-time
+performance.
 
-Ideas for converting to modules

+Transitioning to modules
+
 
-For new libraries, we encourage them to use modules completely from day one if 
possible.
-This will be pretty helpful to make the whole ecosystems to get ready.
-
-For many existing libraries, it may be a breaking change to refactor themselves
-into modules completely. So that many existing libraries need to provide 
headers and module
+New code and libraries should use modules from day one if possible. However,
+it may be a breaking change for existing code or libraries to refactor to use

Endilll wrote:

```suggestion
it may be a breaking change for existing code or libraries to switch to
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -444,53 +435,57 @@ For example, the following example is allowed:
   # Inconsistent debugging level.
   $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
 
-Although the two examples have inconsistent optimization and debugging level, 
both of them are accepted.
+Although the optimization and debugging levels are inconsistent, these
+compilations are accepted because the compiler options do not impact the
+language dialect.
 
-Note that **currently** the compiler doesn't consider inconsistent macro 
definition a problem. For example:
+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 would accept the above example. But it may produce surprising 
results if the
-debugging code depends on consistent use of ``NDEBUG`` also in other 
translation units.
-
-Definitions consistency
-^^^
-
-The C++ language defines that same declarations in different translation units 
should have
-the same definition, as known as ODR (One Definition Rule). Prior to modules, 
the translation
-units don't dependent on each other and the compiler itself can't perform a 
strong
-ODR violation check. With the introduction of modules, now the compiler have
-the chance to perform ODR violations with language semantics across 
translation units.
-
-However, in the practice, we found the existing ODR checking mechanism is not 
stable
-enough. Many people suffers from the false positive ODR violation diagnostics, 
AKA,
-the compiler are complaining two identical declarations have different 
definitions
-incorrectly. Also the true positive ODR violations are rarely reported.
-Also we learned that MSVC don't perform ODR check for declarations in the 
global module
-fragment.
-
-So in order to get better user experience, save the time checking ODR and keep 
consistent
-behavior with MSVC, we disabled the ODR check for the declarations in the 
global module
-fragment by default. Users who want more strict check can still use the
-``-Xclang -fno-skip-odr-check-in-gmf`` flag to get the ODR check enabled. It 
is also
-encouraged to report issues if users find false positive ODR violations or 
false negative ODR
-violations with the flag enabled.
+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.
+
+Object definition consistency
+^
+
+The C++ language requires that the same declarations in different translation

Endilll wrote:

```suggestion
The C++ language requires that the declarations of the same entity in different 
translation
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -738,22 +736,21 @@ the following style significantly:
   import M;
   ... // use declarations from module M.
 
-The key part of the tip is to reduce the duplications from the text includes.
+Reducing the duplication from textual includes is what improves compile-time
+performance.
 
-Ideas for converting to modules

+Transitioning to modules
+
 
-For new libraries, we encourage them to use modules completely from day one if 
possible.
-This will be pretty helpful to make the whole ecosystems to get ready.
-
-For many existing libraries, it may be a breaking change to refactor themselves
-into modules completely. So that many existing libraries need to provide 
headers and module
+New code and libraries should use modules from day one if possible. However,
+it may be a breaking change for existing code or libraries to refactor to use
+modules. As a result, many existing libraries need to provide headers and 
module
 interfaces for a while to not break existing users.
-Here we provide some ideas to ease the transition process for existing 
libraries.
-**Note that the this section is only about helping ideas instead of 
requirement from clang**.
 
-Let's start with the case that there is no dependency or no dependent 
libraries providing
-modules for your library.
+This section provides some ideas on how to ease the transition process for

Endilll wrote:

```suggestion
This section suggests some ideas on how to ease the transition process for
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -1817,27 +1804,29 @@ But with optimizations, things are different:
 │   │
 └---┘
 
-It would be very unfortunate if we end up with worse performance after using 
modules.
-The main concern is that when we compile a source file, the compiler needs to 
see the function body
-of imported module units so that it can perform IPO (InterProcedural 
Optimization, primarily inlining
-in practice) to optimize functions in 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 the IPO itself are the most time-consuming 
part in whole compilation process.
-So from this perspective, we might not be able to get the improvements 
described in the theory.
-But we could still save the time 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 by more optimization opportunities.
+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 in the theory, 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

Endilll wrote:

```suggestion
use's object file). This means the build speedup at higher optimization
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -776,9 +773,9 @@ export-using style
 using decl_n;
   }
 
-As the example shows, you need to include all the headers containing 
declarations needs
-to be exported and `using` such declarations in an `export` block. Then, 
basically,
-we're done.
+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. Then, basically, we're done.

Endilll wrote:

```suggestion
produce the module interface.
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -432,9 +424,8 @@ The following example is not allowed:
   $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
   $ clang++ -std=c++23 Use.cpp -fprebuilt-module-path=.
 
-The compiler would reject the example due to the inconsistent language options.
-Not all options are language options.
-For example, the following example is allowed:
+Clang rejects the example due to the inconsistent language standard modes. Not
+all compiler options are language dialect options. For example:

Endilll wrote:

```suggestion
all compiler options are language dialect options, though. For example:
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -925,45 +923,41 @@ In that case, you need to convert your source files (.cpp 
files) to module imple
   // Following off should be unchanged.
   ...
 
-The module implementation unit will import the primary module implicitly.
-We don't include any headers in the module implementation units
-here since we want to avoid duplicated declarations between translation units.
-This is the reason why we add non-exported using declarations from the third
-party libraries in the primary module interface unit.
+The module implementation unit will import the primary module implicitly. Do
+not include any headers in the module implementation units because that avoids
+duplicated declarations between translation units. This is why non-exported
+using declarations are added from third-party libraries in the primary module
+interface unit.
 
-And if you provide your library as ``libyour_library.so``, you probably need to
-provide a modular one ``libyour_library_modules.so`` since you changed the ABI.
+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 inclued by the source files
 ^^
 
-The above practice may be problematic if there are headers only included by 
the source
-files. If you're using private module fragment, you may solve the issue by 
including them
-in the private module fragment. While it is OK to solve it by including the 
implementation
-headers in the module purview if you're using implementation module units, it 
may be
-suboptimal since the primary module interface units now containing entities 
not belongs
-to the interface.
-
-If you're a perfectionist, maybe you can improve it by introducing internal 
module partition unit.
+The above practice may be problematic if there are headers only included by the
+source files. If using a private module fragment, this issue may be solved by

Endilll wrote:

```suggestion
source files. When using a private module fragment, this issue may be solved by
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -633,36 +631,36 @@ example:
   // module M's interface, so is discarded
   int c = use_h();   // 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`` in ``M-impl.cpp`` fails
-to instantiate. For such issues, users can add references to ``N::g`` in the 
module purview
-of ``M.cppm`` to make sure it is reachable, e.g., ``using N::g;``.
-
-We think the Reduced BMI is the correct direction. But given it is a drastic 
change,
-we'd like to make it experimental first to avoid breaking existing users. The 
roadmap
-of Reduced BMI may be:
-
-1. ``-fexperimental-modules-reduced-bmi`` is opt in for 1~2 releases. The 
period depends
-on testing feedbacks.
-2. We would announce Reduced BMI is not experimental and introduce 
``-fmodules-reduced-bmi``.
-and suggest users to enable this mode. This may takes 1~2 releases too.
-3. Finally we will enable this by default. When that time comes, the term BMI 
will refer to
-the reduced BMI today and the Full BMI will only be meaningful to build 
systems which
-loves to support two phase compilations.
+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`` in ``M-impl.cpp``
+fails to instantiate. For such issues, users can add references to ``N::g`` in
+the module purview of ``M.cppm`` to ensure it is reachable, e.g.,
+``using N::g;``.
+
+Long-term, Clang is likely to make Reduced BMIs the default rather than Full
+BMIs. But because it is a drastic change, it is initially an experimental
+option to avoid breaking existing users. The expected roadmap for Reduced BMIs
+as of Clang 19.x is:
+
+1. ``-fexperimental-modules-reduced-bmi`` is opt-in for 1~2 releases. The 
period depends
+   on user feedback and may be extended.
+2. Announce that Reduced BMIs are no longer experimental and introduce
+   ``-fmodules-reduced-bmi`` as a new option, and recommend use of the new
+   option. This transition is expected to take 1~2 additional releases as well.
+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.
 
 Performance Tips
 
 
 Reduce duplications
 ~~~
 
-While it is legal 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. In other word, for a translation unit, it will compile slower if 
the
-translation unit itself and its importing module units contains a lot 
duplicated
-declarations.
-
-For example,
+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 it and its
+imported module units contain a lot of duplicated declarations. For example:

Endilll wrote:

"A translation unit will compile more slowly if there is a lot of duplicated 
declarations between the translation unit and modules it imports."

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -633,36 +631,36 @@ example:
   // module M's interface, so is discarded
   int c = use_h();   // 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`` in ``M-impl.cpp`` fails
-to instantiate. For such issues, users can add references to ``N::g`` in the 
module purview
-of ``M.cppm`` to make sure it is reachable, e.g., ``using N::g;``.
-
-We think the Reduced BMI is the correct direction. But given it is a drastic 
change,
-we'd like to make it experimental first to avoid breaking existing users. The 
roadmap
-of Reduced BMI may be:
-
-1. ``-fexperimental-modules-reduced-bmi`` is opt in for 1~2 releases. The 
period depends
-on testing feedbacks.
-2. We would announce Reduced BMI is not experimental and introduce 
``-fmodules-reduced-bmi``.
-and suggest users to enable this mode. This may takes 1~2 releases too.
-3. Finally we will enable this by default. When that time comes, the term BMI 
will refer to
-the reduced BMI today and the Full BMI will only be meaningful to build 
systems which
-loves to support two phase compilations.
+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`` in ``M-impl.cpp``
+fails to instantiate. For such issues, users can add references to ``N::g`` in
+the module purview of ``M.cppm`` to ensure it is reachable, e.g.,
+``using N::g;``.
+
+Long-term, Clang is likely to make Reduced BMIs the default rather than Full
+BMIs. But because it is a drastic change, it is initially an experimental
+option to avoid breaking existing users. The expected roadmap for Reduced BMIs
+as of Clang 19.x is:
+
+1. ``-fexperimental-modules-reduced-bmi`` is opt-in for 1~2 releases. The 
period depends
+   on user feedback and may be extended.
+2. Announce that Reduced BMIs are no longer experimental and introduce
+   ``-fmodules-reduced-bmi`` as a new option, and recommend use of the new
+   option. This transition is expected to take 1~2 additional releases as well.
+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

Endilll wrote:

```suggestion
   comes, the term BMI will refer to the Reduced BMI and the Full BMI will only
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -444,53 +435,57 @@ For example, the following example is allowed:
   # Inconsistent debugging level.
   $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
 
-Although the two examples have inconsistent optimization and debugging level, 
both of them are accepted.
+Although the optimization and debugging levels are inconsistent, these
+compilations are accepted because the compiler options do not impact the
+language dialect.
 
-Note that **currently** the compiler doesn't consider inconsistent macro 
definition a problem. For example:
+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 would accept the above example. But it may produce surprising 
results if the
-debugging code depends on consistent use of ``NDEBUG`` also in other 
translation units.
-
-Definitions consistency
-^^^
-
-The C++ language defines that same declarations in different translation units 
should have
-the same definition, as known as ODR (One Definition Rule). Prior to modules, 
the translation
-units don't dependent on each other and the compiler itself can't perform a 
strong
-ODR violation check. With the introduction of modules, now the compiler have
-the chance to perform ODR violations with language semantics across 
translation units.
-
-However, in the practice, we found the existing ODR checking mechanism is not 
stable
-enough. Many people suffers from the false positive ODR violation diagnostics, 
AKA,
-the compiler are complaining two identical declarations have different 
definitions
-incorrectly. Also the true positive ODR violations are rarely reported.
-Also we learned that MSVC don't perform ODR check for declarations in the 
global module
-fragment.
-
-So in order to get better user experience, save the time checking ODR and keep 
consistent
-behavior with MSVC, we disabled the ODR check for the declarations in the 
global module
-fragment by default. Users who want more strict check can still use the
-``-Xclang -fno-skip-odr-check-in-gmf`` flag to get the ODR check enabled. It 
is also
-encouraged to report issues if users find false positive ODR violations or 
false negative ODR
-violations with the flag enabled.
+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.
+
+Object definition consistency
+^
+
+The C++ language requires that the same declarations in different translation
+units have the same definition, which is known as the One Definition Rule 
(ODR).
+Prior to modules, the compiler cannot perform strong ODR violation checking

Endilll wrote:

```suggestion
Prior to modules, the compiler wasn't able to perform strong ODR violation 
checking
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer

Endilll wrote:

It feels strange to define a term in plural form while singular is available 
and fits nicely.

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -444,53 +435,57 @@ For example, the following example is allowed:
   # Inconsistent debugging level.
   $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
 
-Although the two examples have inconsistent optimization and debugging level, 
both of them are accepted.
+Although the optimization and debugging levels are inconsistent, these
+compilations are accepted because the compiler options do not impact the
+language dialect.
 
-Note that **currently** the compiler doesn't consider inconsistent macro 
definition a problem. For example:
+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 would accept the above example. But it may produce surprising 
results if the
-debugging code depends on consistent use of ``NDEBUG`` also in other 
translation units.
-
-Definitions consistency
-^^^
-
-The C++ language defines that same declarations in different translation units 
should have
-the same definition, as known as ODR (One Definition Rule). Prior to modules, 
the translation
-units don't dependent on each other and the compiler itself can't perform a 
strong
-ODR violation check. With the introduction of modules, now the compiler have
-the chance to perform ODR violations with language semantics across 
translation units.
-
-However, in the practice, we found the existing ODR checking mechanism is not 
stable
-enough. Many people suffers from the false positive ODR violation diagnostics, 
AKA,
-the compiler are complaining two identical declarations have different 
definitions
-incorrectly. Also the true positive ODR violations are rarely reported.
-Also we learned that MSVC don't perform ODR check for declarations in the 
global module
-fragment.
-
-So in order to get better user experience, save the time checking ODR and keep 
consistent
-behavior with MSVC, we disabled the ODR check for the declarations in the 
global module
-fragment by default. Users who want more strict check can still use the
-``-Xclang -fno-skip-odr-check-in-gmf`` flag to get the ODR check enabled. It 
is also
-encouraged to report issues if users find false positive ODR violations or 
false negative ODR
-violations with the flag enabled.
+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.
+
+Object definition consistency
+^
+
+The C++ language requires that the same declarations in different translation
+units have the same definition, which is known as the One Definition Rule 
(ODR).
+Prior to modules, the compiler cannot perform strong ODR violation checking
+because it only sees one translation unit at a time. With 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.
+Additionally, MSVC does not currently perform ODR checking for declarations in

Endilll wrote:

```suggestion
It's worth noting that MSVC does not currently perform ODR checking for 
declarations in
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -8,79 +8,60 @@ 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 `_, it
-should be helpful to read `Clang modules `_ 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 ``modules`` has a lot of meanings. For Clang users, modules may refer
+to ``Objective-C Modules``, `Clang Modules `_ (also called
+``Clang Header Modules``, etc.) or ``C++20 Modules`` (or
+``Standard C++ Modules``). 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 of focusing on the use of C++20 modules in Clang. In the remainder
+of this document, the term ``modules`` will refer to Standard C++20 modules and
+the term ``Clang modules`` 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
+language background here 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 for 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).
-
-In this document, module units are classified into:
-
-* Primary module interface unit.
-
-* Module implementation unit.
+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).

Endilll wrote:

```suggestion
hierarchy or referring to the file system).
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -279,8 +266,9 @@ we could put ``-x c++-module`` in front of the file. For 
example,
 return 0;
   }
 
-Now the filename of the ``module interface`` ends with ``.cpp`` instead of 
``.cppm``,
-we can't compile them by the original command lines. But we are still able to 
do it by:
+In this example, the extension used by the ``module interface`` is ``.cpp``
+instead of ``.cppm``, so is cannot be compiled with the command lines from the

Endilll wrote:

```suggestion
instead of ``.cppm``, so it cannot be compiled with the command lines from the
```

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -95,22 +76,23 @@ 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``.
 
-* 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

Endilll wrote:

This whole piece of documentation relies heavily on code font, and I feel we 
might be overusing it, like here. Maybe we should follow the example of the 
Standard, and use italics instead.

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

https://github.com/Endilll commented:

I have to admit that is rather shallow due to sheer amount of text, but it 
still took me more like 90 minutes. Hope you find it useful. 

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -444,53 +435,57 @@ For example, the following example is allowed:
   # Inconsistent debugging level.
   $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
 
-Although the two examples have inconsistent optimization and debugging level, 
both of them are accepted.
+Although the optimization and debugging levels are inconsistent, these
+compilations are accepted because the compiler options do not impact the
+language dialect.
 
-Note that **currently** the compiler doesn't consider inconsistent macro 
definition a problem. For example:
+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 would accept the above example. But it may produce surprising 
results if the
-debugging code depends on consistent use of ``NDEBUG`` also in other 
translation units.
-
-Definitions consistency
-^^^
-
-The C++ language defines that same declarations in different translation units 
should have
-the same definition, as known as ODR (One Definition Rule). Prior to modules, 
the translation
-units don't dependent on each other and the compiler itself can't perform a 
strong
-ODR violation check. With the introduction of modules, now the compiler have
-the chance to perform ODR violations with language semantics across 
translation units.
-
-However, in the practice, we found the existing ODR checking mechanism is not 
stable
-enough. Many people suffers from the false positive ODR violation diagnostics, 
AKA,
-the compiler are complaining two identical declarations have different 
definitions
-incorrectly. Also the true positive ODR violations are rarely reported.
-Also we learned that MSVC don't perform ODR check for declarations in the 
global module
-fragment.
-
-So in order to get better user experience, save the time checking ODR and keep 
consistent
-behavior with MSVC, we disabled the ODR check for the declarations in the 
global module
-fragment by default. Users who want more strict check can still use the
-``-Xclang -fno-skip-odr-check-in-gmf`` flag to get the ODR check enabled. It 
is also
-encouraged to report issues if users find false positive ODR violations or 
false negative ODR
-violations with the flag enabled.
+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.
+
+Object definition consistency
+^
+
+The C++ language requires that the same declarations in different translation
+units have the same definition, which is known as the One Definition Rule 
(ODR).
+Prior to modules, the compiler cannot perform strong ODR violation checking
+because it only sees one translation unit at a time. With 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.
+Additionally, MSVC does not currently perform ODR checking for declarations in
+the global module fragment.
+
+To give a better user experience, improve compilation performance, and for
+consistentency 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 `_.
 
 ABI Impacts
 ---
 
-This section describes the new ABI changes brought by modules.
-
-Only Itanium C++ ABI related change are mentioned
+This section describes the new ABI changes brought by modules. Only Itanium C++
+ABI related change are mentioned.

Endilll wrote:

"Only changes to Itanium C++ ABI are covered."

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

[clang] Revise the modules document for clarity (PR #90237)

[Vlad Serebrennikov via cfe-commits]

@@ -312,75 +300,76 @@ So all of the following name is not valid by default:
 __test
 // and so on ...
 
-If you still want to use the reserved module names for any reason, use
-``-Wno-reserved-module-identifier`` to suppress the warning.
+Using a reserved module name is strongly discouraged, but
+``-Wno-reserved-module-identifier`` can be used to suppress the warning.
 
-How to specify the dependent BMIs
-~
+Specifying dependent BMIs
+~
 
-There are 3 methods to specify the dependent BMIs:
+There are 3 ways to specify a dependent BMI:
 
-* (1) ``-fprebuilt-module-path=``.
-* (2) ``-fmodule-file=`` (Deprecated).
-* (3) ``-fmodule-file==``.
+1. ``-fprebuilt-module-path=``.
+2. ``-fmodule-file=`` (Deprecated).
+3. ``-fmodule-file==``.
 
-The option ``-fprebuilt-module-path`` tells the compiler the path where to 
search for dependent BMIs.
-It may be used multiple times just like ``-I`` for specifying paths for header 
files. The look up rule here is:
+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

Endilll wrote:

```suggestion
``-fprebuilt-module-path``. Similarly, when importing a partition module unit
```

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