[clang] Revise the modules document for clarity (PR #90237)
@@ -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 Endilll wrote: ```suggestion because it only sees one translation unit at a time. Now, 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)
@@ -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. Endilll wrote: ```suggestion to better understand use of modules in 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)
@@ -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 Endilll wrote: ```suggestion introduction to the use of C++20 modules in Clang. In the remainder ``` > focuses on an introduction of focusing doesn't sound good 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)
@@ -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. Endilll wrote: ```suggestion **Currently**, Clang does very strict checking 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)
https://github.com/Endilll 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)
llvmbot wrote: @llvm/pr-subscribers-clang-modules Author: Aaron Ballman (AaronBallman) Changes 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. --- Patch is 84.98 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/90237.diff 1 Files Affected: - (modified) clang/docs/StandardCPlusPlusModules.rst (+561-572) ``diff 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. +In this document, module units are classified as: -* Internal module partition
[clang] Revise the modules document for clarity (PR #90237)
https://github.com/AaronBallman created https://github.com/llvm/llvm-project/pull/90237 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. >From a75aa14fcad6f346a3073ae88e91fa890e803422 Mon Sep 17 00:00:00 2001 From: Aaron Ballman Date: Fri, 26 Apr 2024 13:12:51 -0400 Subject: [PATCH] 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
