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

Sun Aug 28 23:20:22 PDT 2022

ChuanqiXu added a comment.

In D131388#3753522 <https://reviews.llvm.org/D131388#3753522>, @aaronmondal wrote:

> @ChuanqiXu Thanks a lot for this!
>
> We are currently implementing this module logic in the Bazel ruleset rules_ll <https://github.com/eomii/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 known problem section for it. I think we can edit the document further after we get more consensus.

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

No, I am not using/developing a build system for modules (Currently I write command line options manually by Makefile). And the suffix expectation are required by the **current** clang15.x. And we can change it in further versions.

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

https://reviews.llvm.org/D131388