[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

This revision was not accepted when it landed; it landed in state "Needs 
Review".
This revision was automatically updated to reflect the committed changes.
Closed by commit rGb1d5af81249d: [docs] Add Standard C++ Modules 
(authored by ChuanqiXu).

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

Files:
  clang/docs/StandardCPlusPlusModules.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -40,6 +40,7 @@
SafeStack
ShadowCallStack
SourceBasedCodeCoverage
+   StandardCPlusPlusModules
Modules
MSVCCompatibility
MisExpect
Index: clang/docs/StandardCPlusPlusModules.rst
===
--- /dev/null
+++ clang/docs/StandardCPlusPlusModules.rst
@@ -0,0 +1,876 @@
+
+Standard C++ Modules
+
+
+.. contents::
+   :local:
+
+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.
+
+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.
+
+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:
+
+.. 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.
+
+* Module interface partition unit.
+
+* Internal module partition 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
+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.
+
+A module interface partition unit is a module unit whose module declaration is
+``export module module_name:partition_name;``. The ``partition_name`` should be
+unique within any given module.
+
+An internal module partition unit is a module unit whose module declaration
+is ``module module_name:partition_name;``. The ``partition_name`` should be
+unique within any given module.
+
+In this document, we use the following 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``.
+
+* A ``module partition unit`` refers to either a ``module interface partition unit``
+  or a ``internal module partition unit``.
+
+Built Module Interface file

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu accepted this revision.
ChuanqiXu added a comment.

I'm going to land this. Thanks for everyone who reviewed this!


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu added a comment.

@bbrown105 I am going to land this today. it looks like you're not objecting it 
and we don't have the time to wait for your formal approval...


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu added a comment.

In D131388#3758898 , @aaronmondal 
wrote:

> I just noticed that there probably needs to be one change. The doc sometimes 
> describes `-fprebuilt-module-interface`, which is not a valid option. I think 
> the occurrences were meant to be `-fpbrebuilt-module-path`.

Oh, thanks for noticing. It is weird that I made such a mistake...


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu updated this revision to Diff 456844.
ChuanqiXu added a comment.

Address comments.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

Files:
  clang/docs/StandardCPlusPlusModules.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -40,6 +40,7 @@
SafeStack
ShadowCallStack
SourceBasedCodeCoverage
+   StandardCPlusPlusModules
Modules
MSVCCompatibility
MisExpect
Index: clang/docs/StandardCPlusPlusModules.rst
===
--- /dev/null
+++ clang/docs/StandardCPlusPlusModules.rst
@@ -0,0 +1,876 @@
+
+Standard C++ Modules
+
+
+.. contents::
+   :local:
+
+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.
+
+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.
+
+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:
+
+.. 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.
+
+* Module interface partition unit.
+
+* Internal module partition 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
+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.
+
+A module interface partition unit is a module unit whose module declaration is
+``export module module_name:partition_name;``. The ``partition_name`` should be
+unique within any given module.
+
+An internal module partition unit is a module unit whose module declaration
+is ``module module_name:partition_name;``. The ``partition_name`` should be
+unique within any given module.
+
+In this document, we use the following 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``.
+
+* A ``module partition unit`` refers to either a ``module interface partition unit``
+  or a ``internal module partition unit``.
+
+Built Module Interface file
+~~~
+
+A ``Built Module Interface file`` stands for the precompiled result of an importable module unit.
+It is also called the acronym ``BMI`` genrally.
+
+Global module 

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Aaron Siddhartha Mondal via Phabricator via cfe-commits]

aaronmondal requested changes to this revision.
aaronmondal added a comment.
This revision now requires changes to proceed.

I just noticed that there probably needs to be one change. The doc sometimes 
describes `-fprebuilt-module-interface`, which is not a valid option. I think 
the occurrences were meant to be `-fpbrebuilt-module-path`.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Aaron Siddhartha Mondal via Phabricator via cfe-commits]

aaronmondal accepted this revision.
aaronmondal added a comment.

Thanks for addressing my comment. I think I overlooked the part about 
`-fmodules-embed-all-files` 

I'm fine with this revision 


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu added a comment.

In D131388#3753522 , @aaronmondal 
wrote:

> @ChuanqiXu Thanks a lot for this!
>
> We are currently implementing this module logic in the Bazel ruleset rules_ll 
> .
> This page helps clarify the differences between clang modules and C++ modules 
> a lot. If I knew about this earlier we'd probably have saved a lot of time 

Yeah, the reason why I want to land this faster is that I've seen some people 
confused about this too.

(I've watched rules_ll for releases. So it will be better to *release* it if 
you guys get something done)

> After reading this doc, a few things came to my mind. I can add a patch for 
> this as a follow-up diff when I better understand how things work.
>
> - The path logic that references the source files in BMIs is very important. 
> When precompiling a module in one directory and then moving a header included 
> in the global module fragment from the source file, things will break.

Yes and I mentioned it implicitly that we can workaround it by `-Xclang 
-fmodules-embed-all-files` options. And I add a paragraph at the end of `Source 
content consistency` section to make it explicitly. Would you like to take a 
look?

> - Clang modulemaps are cool, but for build systems that have to declare every 
> output, implicit modulemaps seem like a bad idea. Clang's caching system, 
> even with custom cache paths seems like a bad idea as well. It is probably 
> helpful to mention caveats of implicit modules and how to disable them (or 
> link to the Clang Module docs for this).
> - The doc describes how to build e.g. an `iostream` module using the C++ 
> semantics, but doesn't mention that AFAIK there is no "native" C++ Module 
> build for libcxx yet. One would currently actually use Clang modules with 
> implicit modulemaps. It may be helpful to mention this to avoid confusion.

In fact, initially I want this document to be separate from clang module map 
modules. Although they share a lot in the implementation, they are totally 
different to the users. (Although they share some options too). To be clear, 
I'm not saying we'll abandon/disallow the mixed use of clang module map modules 
with standard c++ modules. The status quo is that every thing is still 
**unclear**. I'm not sure if they will work together correctly or what the cost 
we'll pay for to make them work together. So when I wrote this document, I 
intentionally skipped the part of how to use clang module map modules.

And I think it will be great to add a section "interaction with clang module 
map modules" once we have the use experience of mixed form.

> - Issue https://github.com/llvm/llvm-project/issues/56770 and 
> seems-to-be-a-consequence-issue 
> https://github.com/llvm/llvm-project/issues/57293 may be relevant apart from 
> the already mentioned issue about clang-scan-deps.

I'm not sure. And for this document, I feel it is fine to not include all the 
issues. Otherwise it may be a little bit scary to people who reads it first.

---

@aaronmondal @bbrown105 Are you happy to land this document in the current 
status? So that I can backport this to 15.x in time. (clang 15.x is going to be 
released in the next week). Then the readers could read the document for 15.x 
at 
https://releases.llvm.org/15.0.0/tools/clang/docs/StandardCPlusPlusModules.html.
 Then we can keep maintaining it further. This should be helpful for version 
controlling.




Comment at: clang/docs/StandardCPlusPlusModules.rst:243-244
+since ``--precompile`` option now would only run preprocessor, which is equal 
to `-E` now.
+If we still want the filename of an ``importable module unit`` ends with 
``.cpp`` instead of ``.cppm``,
+we could put ``-x c++-module`` in front of the file. For example,
+

bbrown105 wrote:
> Is there a tracking issue to revise this choice? I seem to recall that we 
> settled on recommending a different file extension, `*.ixx`, for at least 
> primary module interface units.
> 
> We didn't really discuss extensions for other units, but maybe we should if 
> different toolchains are going to have different expectations. Of course, 
> build systems can work around this sort of thing. But if the expectation of 
> clang is that, practically speaking, you'll probably be using a build system, 
> maybe the docs should clarify as much. We could document that parts of this 
> document are intended for people configuring or implementing build systems.
> 
> FYI @Bigcheese 
> Is there a tracking issue to revise this choice? I seem to recall that we 
> settled on recommending a different file extension, *.ixx, for at least 
> primary module interface units.

I remember there is not an existing one. And I just filed 
https://github.com/llvm/llvm-project/issues/57416. I think you can post the 
consensus of SG15 in that issue and we can follow it.

I edit the wording slightly (must -> should) and add a 

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu updated this revision to Diff 456254.
ChuanqiXu added a comment.

Add contents for "When precompiling a module in one directory and then moving a 
header included in the global module fragment from the source file, things will 
break."


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

Files:
  clang/docs/StandardCPlusPlusModules.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -40,6 +40,7 @@
SafeStack
ShadowCallStack
SourceBasedCodeCoverage
+   StandardCPlusPlusModules
Modules
MSVCCompatibility
MisExpect
Index: clang/docs/StandardCPlusPlusModules.rst
===
--- /dev/null
+++ clang/docs/StandardCPlusPlusModules.rst
@@ -0,0 +1,835 @@
+
+Standard C++ Modules
+
+
+.. contents::
+   :local:
+
+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.
+
+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.
+
+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:
+
+.. 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.
+
+* Module interface partition unit.
+
+* Internal module partition 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
+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.
+
+A module interface partition unit is a module unit whose module declaration is
+``export module module_name:partition_name;``. The ``partition_name`` should be
+unique within any given module.
+
+An internal module partition unit is a module unit whose module declaration
+is ``module module_name:partition_name;``. The ``partition_name`` should be
+unique within any given module.
+
+In this document, we use the following 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``.
+
+* A ``module partition unit`` refers to either a ``module interface partition unit``
+  or a ``internal module partition unit``.
+
+Built Module Interface file
+~~~
+
+A ``Built Module 

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu updated this revision to Diff 456244.
ChuanqiXu marked 5 inline comments as done.
ChuanqiXu added a comment.

Address comments.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

Files:
  clang/docs/StandardCPlusPlusModules.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -40,6 +40,7 @@
SafeStack
ShadowCallStack
SourceBasedCodeCoverage
+   StandardCPlusPlusModules
Modules
MSVCCompatibility
MisExpect
Index: clang/docs/StandardCPlusPlusModules.rst
===
--- /dev/null
+++ clang/docs/StandardCPlusPlusModules.rst
@@ -0,0 +1,835 @@
+
+Standard C++ Modules
+
+
+.. contents::
+   :local:
+
+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.
+
+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.
+
+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:
+
+.. 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.
+
+* Module interface partition unit.
+
+* Internal module partition 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
+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.
+
+A module interface partition unit is a module unit whose module declaration is
+``export module module_name:partition_name;``. The ``partition_name`` should be
+unique within any given module.
+
+An internal module partition unit is a module unit whose module declaration
+is ``module module_name:partition_name;``. The ``partition_name`` should be
+unique within any given module.
+
+In this document, we use the following 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``.
+
+* A ``module partition unit`` refers to either a ``module interface partition unit``
+  or a ``internal module partition unit``.
+
+Built Module Interface file
+~~~
+
+A ``Built Module Interface file`` stands for the precompiled result of an importable module unit.
+It is also called the 

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Aaron Siddhartha Mondal via Phabricator via cfe-commits]

aaronmondal added a comment.

@ChuanqiXu Thanks a lot for this!

We are currently implementing this module logic in the Bazel ruleset rules_ll 
.
This page helps clarify the differences between clang modules and C++ modules a 
lot. If I knew about this earlier we'd probably have saved a lot of time 

After reading this doc, a few things came to my mind. I can add a patch for 
this as a follow-up diff when I better understand how things work.

- The path logic that references the source files in BMIs is very important. 
When precompiling a module in one directory and then moving a header included 
in the global module fragment from the source file, things will break.
- As a result of this, some unintuitive things can happen when using sandboxed 
compilation. E.g. precompile BMI in sandbox, move BMI out of that sandbox, then 
start another sandbox that loads the previously built BMI. If the BMI used 
headers in a global module fragment, and those headers were in the original 
sandboxe, the header in the new sandbox will be in a different location 
(because the new sandbox is at a new location) and things will break.
- Clang modulemaps are cool, but for build systems that have to declare every 
output, implicit modulemaps seem like a bad idea. Clang's caching system, even 
with custom cache paths seems like a bad idea as well. It is probably helpful 
to mention caveats of implicit modules and how to disable them (or link to the 
Clang Module docs for this).
- The doc describes how to build e.g. an `iostream` module using the C++ 
semantics, but doesn't mention that AFAIK there is no "native" C++ Module build 
for libcxx yet. One would currently actually use Clang modules with implicit 
modulemaps. It may be helpful to mention this to avoid confusion.
- Issue https://github.com/llvm/llvm-project/issues/56770 and 
seems-to-be-a-consequence-issue 
https://github.com/llvm/llvm-project/issues/57293 may be relevant apart from 
the already mentioned issue about clang-scan-deps.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Bret Brown via Phabricator via cfe-commits]

bbrown105 added a comment.

Nice writeup! I appreciate the work that went into this.




Comment at: clang/docs/StandardCPlusPlusModules.rst:27
+
+standard C++ Named modules
+==

Just matching the capitalization of the other sections and subsections.



Comment at: clang/docs/StandardCPlusPlusModules.rst:87
+``export module module_name:partition_name;``. The ``partition_name`` should be
+unique to the module.
+

This is a small tweak but it should clarify that using the same 
`partition_name` with entirely different `module_names` is fine.



Comment at: clang/docs/StandardCPlusPlusModules.rst:89
+
+A internal module partition unit is a module unit whose module declaration
+is ``module module_name:partition_name;``. The ``partition_name`` should be





Comment at: clang/docs/StandardCPlusPlusModules.rst:91
+is ``module module_name:partition_name;``. The ``partition_name`` should be
+unique to the module.
+





Comment at: clang/docs/StandardCPlusPlusModules.rst:243-244
+since ``--precompile`` option now would only run preprocessor, which is equal 
to `-E` now.
+If we still want the filename of an ``importable module unit`` ends with 
``.cpp`` instead of ``.cppm``,
+we could put ``-x c++-module`` in front of the file. For example,
+

Is there a tracking issue to revise this choice? I seem to recall that we 
settled on recommending a different file extension, `*.ixx`, for at least 
primary module interface units.

We didn't really discuss extensions for other units, but maybe we should if 
different toolchains are going to have different expectations. Of course, build 
systems can work around this sort of thing. But if the expectation of clang is 
that, practically speaking, you'll probably be using a build system, maybe the 
docs should clarify as much. We could document that parts of this document are 
intended for people configuring or implementing build systems.

FYI @Bigcheese 



Comment at: clang/docs/StandardCPlusPlusModules.rst:744
+
+How module speed up compilation
+---




CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Daniel Ruoso via Phabricator via cfe-commits]

ruoso accepted this revision.
ruoso added a comment.

Thanks for taking my last minute suggestions


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu added a comment.

In D131388#3748769 , @ruoso wrote:

> I just noticed that the document was implying that Header Units were separate 
> from the Standard C++ Modules, but they are an integral part of the language 
> in the specification of modules. The contrast that we do is between "Named 
> Modules" and "Header Units". I did some edits to help convey that.

Done. Although I wanted to land this today but I feel it will be better to be 
approved by you. So I'll wait longer.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu updated this revision to Diff 455802.
ChuanqiXu marked 5 inline comments as done.
ChuanqiXu added a comment.

Address comments:

- Change the file name to `StandardCPlusPlusModules`
- Combine header units with modules more tightly.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

Files:
  clang/docs/StandardCPlusPlusModules.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -40,6 +40,7 @@
SafeStack
ShadowCallStack
SourceBasedCodeCoverage
+   StandardCPlusPlusModules
Modules
MSVCCompatibility
MisExpect
Index: clang/docs/StandardCPlusPlusModules.rst
===
--- /dev/null
+++ clang/docs/StandardCPlusPlusModules.rst
@@ -0,0 +1,827 @@
+
+Standard C++ Modules
+
+
+.. contents::
+   :local:
+
+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.
+
+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.
+
+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:
+
+.. 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.
+
+* Module interface partition unit.
+
+* Internal module partition 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
+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.
+
+A module interface partition unit is a module unit whose module declaration is
+``export module module_name:partition_name;``. The ``partition_name`` should be
+unique to the module.
+
+A internal module partition unit is a module unit whose module declaration
+is ``module module_name:partition_name;``. The ``partition_name`` should be
+unique to the module.
+
+In this document, we use the following umbrella terms:
+
+* A ``module interface unit`` refers to either a ``primary module interface unit``
+  or a ``module interface partition unit``.
+
+* An ``importable module unit`` refers to either a ``module interface unit``
+  or a ``internal module partition unit``.
+
+* A ``module partition unit`` refers to either a ``module interface partition unit``
+  or a ``internal module partition unit``.
+
+Built Module Interface file
+~~~
+
+A ``Built Module Interface file`` stands 

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu added a comment.

In D131388#3748769 , @ruoso wrote:

> I just noticed that the document was implying that Header Units were separate 
> from the Standard C++ Modules, but they are an integral part of the language 
> in the specification of modules. The contrast that we do is between "Named 
> Modules" and "Header Units". I did some edits to help convey that.

Yeah, I know header units are part of modules. Technically, the "header units" 
are special synthesized units . And the entities in header units part of the 
global module. And global module have no name. So here is the term `Named 
Modules`. I didn't mention this since I feel this bring some language details 
to the users but I feel like this is not helpful for users. For me, it is 
simpler and workable to think "header units" are special headers and treat 
"named modules" and "modules" interchangeably. But given you are doing a lot of 
modules documentation work, I'll follow your suggestion to make the terms 
consistency.

(BTW, it is a little bit weird to me since "header units" should be "units" 
literally but we call it modules)


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Daniel Ruoso via Phabricator via cfe-commits]

ruoso added a comment.

I just noticed that the document was implying that Header Units were separate 
from the Standard C++ Modules, but they are an integral part of the language in 
the specification of modules. The contrast that we do is between "Named 
Modules" and "Header Units". I did some edits to help convey that.




Comment at: clang/docs/CPlusPlus20Modules.rst:24-26
+Although the term ``modules`` has a unique meaning in C++20 Language 
Specification,
+when people talk about standard C++ modules, they may refer to another C++20 
feature:
+header units, which are also covered in this document.





Comment at: clang/docs/CPlusPlus20Modules.rst:28-29
+
+standard C++ modules
+
+





Comment at: clang/docs/CPlusPlus20Modules.rst:285-287
+Another way to specify the dependent BMIs is to use ``-fmodule-file``. The 
main difference
+is that ``-fprebuilt-module-interface`` takes a directory, whereas 
``-fmodule-file`` requires a
+specific file.

Which one takes precedence?



Comment at: clang/docs/CPlusPlus20Modules.rst:585-586
+
+Similar to modules, we could use ``--precompile`` to produce the BMI.
+But we need to specify that the input file is a header by 
``-xc++-system-header`` or ``-xc++-user-header``.
+





Comment at: clang/docs/CPlusPlus20Modules.rst:728-729
+wrapping multiple headers together as a big module.
+However, these things are not part of C++20 Header units, and we want to avoid 
the impression that these
+additional semantics get interpreted as standard C++20 behavior.
+




CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[H. Vetinari via Phabricator via cfe-commits]

h-vetinari added a comment.

In D131388#3748062 , @ChuanqiXu wrote:

> Replace `C++20 Modules` with `Standard C++ Modules` since @ruoso pointed out 
> that `Modules` is not specific to certain versions of C++ (for example, 
> Modules may get some big changes in C++23, C++26, ...).

The filename (and hence future doc URL) still contains the "20".


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D131388: [docs] Add "Standard C++ Modules"

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu updated this revision to Diff 455462.
ChuanqiXu retitled this revision from "[docs] Add "C++20 Modules"" to "[docs] 
Add "Standard C++ Modules"".
ChuanqiXu edited the summary of this revision.
ChuanqiXu added a comment.

Replace `C++20 Modules` with `Standard C++ Modules` since @ruoso pointed out 
that `Modules` is not specific to certain versions of C++ (for example, Modules 
may get some big changes in C++23, C++26, ...).


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D131388/new/

https://reviews.llvm.org/D131388

Files:
  clang/docs/CPlusPlus20Modules.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -40,6 +40,7 @@
SafeStack
ShadowCallStack
SourceBasedCodeCoverage
+   CPlusPlus20Modules
Modules
MSVCCompatibility
MisExpect
Index: clang/docs/CPlusPlus20Modules.rst
===
--- /dev/null
+++ clang/docs/CPlusPlus20Modules.rst
@@ -0,0 +1,825 @@
+
+Standard C++ Modules
+
+
+.. contents::
+   :local:
+
+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.
+
+Although the term ``modules`` has a unique meaning in C++20 Language Specification,
+when people talk about standard C++ modules, they may refer to another C++20 feature:
+header units, which are also covered in this document.
+
+standard C++ 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.
+
+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:
+
+.. 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.
+
+* Module interface partition unit.
+
+* Internal module partition 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
+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.
+
+A module interface partition unit is a module unit whose module declaration is
+``export module module_name:partition_name;``. The ``partition_name`` should be
+unique to the module.
+
+A internal module partition unit is a module unit whose module declaration
+is ``module module_name:partition_name;``. The ``partition_name`` should be
+unique to the module.
+
+In this document, we use the following umbrella terms:
+
+* A ``module interface unit`` refers to either a ``primary module interface unit``
+  or a ``module interface partition unit``.
+
+* An ``importable module unit`` refers to either a ``module interface unit``
+  or a ``internal module partition unit``.
+
+* A