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

[Chuanqi Xu via Phabricator via cfe-commits]

ChuanqiXu added inline comments.


================
Comment at: clang/docs/CPlusPlus20Modules.rst:70-76
+* Primary module interface unit.
+
+* Module implementation unit.
+
+* Module partition interface unit.
+
+* Module partition implementation unit.
----------------
ruoso wrote:
> The terminology here is a bit different than what we've been building the consensus on. Please take a look at [[ https://github.com/cplusplus/modules-ecosystem-tr/blob/master/sourcefiles.tex#L19 | sourcefiles.tex ]] (or section `[source.types]` in the [[ 
> https://github.com/cplusplus/modules-ecosystem-tr/files/9237071/iso_cpp_modules_ecosystem_technical_report.pdf | rendered version ]] 
> 
> 
If there is a consensus already, we should follow. 

(BTW, I thought we'll discuss module things in SG2 but it looks like we're discussing them in SG15... my bad)


================
Comment at: clang/docs/CPlusPlus20Modules.rst:225
+
+It is possible to generate a module file for an importable module unit by specifying the ``--precompile`` option.
+
----------------
ruoso wrote:
> Likewise, here the term "Built Module Interface file", with the acronym "BMI" is what we're generally using when talking about the generated file.
Yeah, this is what I was confused in the chat. In my mind, "BMI" describes a compatible interface format like ABI (like Itanium ABI). In another words, a BMI could be compiled by compiler which follows the BMI standard (like clang and gcc both accepts Itanium ABI). But currrently, a module file couldn't be compiled by clang in different versions.

So from my point of view, the term `module file` is more appropriate than `BMI` now.


================
Comment at: clang/docs/CPlusPlus20Modules.rst:243-244
+
+The option ``-fprebuilt-module-interface`` tells the compiler the path where to search for dependent module files.
+It may be used multiple times just like ``-I`` for specifying paths for header files.
+
----------------
ruoso wrote:
> Is that the case for C++20 named modules as well? I thought this was just for clang modules. How does the lookup work?
In this document, modules are referring to `C++20 Named Modules` by default. The option is borrowed from clang modules. The look up rule here is:

(1) When we import module `M`. The compiler would look up `M.pcm` in the directories specified by ``-fprebuilt-module-interface``.
(2) When we import partition module unit `M:P`. The compiler would look up `M-P.pcm` in the directories specified by ``-fprebuilt-module-interface``.

I thought this is clear enough. Do you have suggestion to improve? I am a little worried to be wordy.


================
Comment at: clang/docs/CPlusPlus20Modules.rst:250-253
+When we compile a ``module implementation unit``, we must pass the module file of the corresponding
+``primary module interface unit`` by ``-fmodule-file``.
+Again, this option may occur multiple times. For example, the command line to compile ``M.cppm`` in
+the above example could be rewritten into:
----------------
ruoso wrote:
> I wonder if it's easier to explain that a module implementation unit implicitly imports the primary module interface unit, and therefore it needs the BMI for that interface to be provided, just like it's the case for every other import statement.
OK, I was afraid to cite too many standard paragraphs to scare readers. But this point looks necessary 


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

https://reviews.llvm.org/D131388