[RFC] Unifying the terminology about modules in clang

Clang Frontend
1

Currently, the term modules have multiple meanings in clang. The meaning of modules now including general concepts of modules, ObjC Modules, Clang C++ Modules, Standard C++ Named Modules and Standard C++ Header Unit. Sometimes it can refer to LLVM modules in the CodeGen directories too! And it is confusing to developers especially for new coming developers.

So I want to propose to unify the terminologies about modules in the clang code. I suggest to use:

  • Modules: the general concepts of modules in the frontend languages. It includes ObjCModules, clang header modules and standard c++ modules. But it doesn’t include the LLVM modules and MLIR modules (if introduced).
  • LLVM Modules
  • Clang Named Modules: The Clang modulemap based extension that supports import using @import in Objective-C[++].
  • Clang Modules: Clang Header Modules and Clang Named Modules.
  • Standard C++ Named Modules: the standard c++ modules.
  • Standard C++ Header Units: the standard c++ header unit.
  • Standard C++ Modules: the named modules and header units.
  • Header like modules: the Header Units and Clang Header Modules

If we get a consensus on the names, I’d love to do many NFC changes in the code to avoid further misunderstandings.

CC: @iains @Bigcheese @dblaikie @tahonermann @jansvoboda11 @vsapsai

1 Like
2

I find the “ObjC Modules” and “Clang C++ Modules” terminology a little confusing. I’m guessing that “ObjC Modules” is intended to refer to the form of “Clang Modules” for which the @import directive supports importing a module by name and that “Clang C++ Modules” is intended for the form of “Clang Modules” for which the #include directive supports importing a module by header file name (which is supported in C, C++, and Objective-C[++]). I suggest instead:

The rest sounds good to me.

3

Thanks. The suggestion makes sense. I’ve applied them. And to avoid the ambiguity about Named Modules, I add the prefix Standard C++ to the original Named Modules. Although it is longer, it is much clearer now : )

1 Like
4

I think “Header like modules” should now name Clang Header Modules and Standard C++ Header Units. Looks great otherwise.

1 Like
5

Good catcha! Done.

6

Nice effort into making this easier to understand, way to go!

My two cents is that you only need “Clang Modules” or “Clang Header Modules” for these 3. I wouldn’t differentiate Header/Named since they share 99% of the functionality, and “Named” could be confusing since it’s used by C++20 Modules nomenclature. Also @import is just a usability detail that requires ObjC, so it’s pretty orthogonal and the implementation semantics aren’t too much different between include-to-pcm-mapping vs importing-by-pcm-name.

7

I agree that would be reasonable as well.

1 Like
8

Also @import is just a usability detail that requires ObjC, so it’s pretty orthogonal and the implementation semantics aren’t too much different between include-to-pcm-mapping vs importing-by-pcm-name.

Yeah, there aren’t too much differences. But they do have differences. For example, currently in the preprocessor, both the so called Clang Named Modules and StdCXXModules share one components: ModuleImportPath. So ModuleImportPath will be std in the following two cases:

@import std;

or

import std;

So the emptiness of ModuleImportPath implies if we’re importing so called named modules or header like modules. I feel like this is a good example to show the necessity to use the term clang named modules. And I agree that we can use Clang Modules for most of the places. I just want to leave some spaces for corner cases.

2 Likes
9

Right! At the higher level though I feel like this is more about an implementation detail that both implementations somewhat share.

I feel like this is a good example to show the necessity to use the term clang named modules. And I agree that we can use Clang Modules for most of the places. I just want to leave some spaces for corner cases.

Fair, my only concern is that it could cause confusion for something that is mostly ObjectiveC(++) related and probably noisy for the average C++ user trying to understand the difference between compiler knobs and overall Clang Modules versus C++ Standard Modules.

One thing I haven’t thought before though is that while reading clang documentation folks might see @import and get confused with import, so perhaps this count towards your point on making this more clear.

1 Like
10

Yeah, this is the point. My (current) intention for this thread is for developers instead of the end users. The motivation is when I read the codes, I often can’t identify the what’s the purpose for the function or that variable from its name. I can only to make it clear by reading its context and use points. It is a little bit painful. So I mean if we can get a consensus here. We can do a lot of NFC changes to make the names more clear.

And for users, I guess we can’t do nothing with the existing command line flags. It is not good to change many command line flags’ names. It’ll break users code.

1 Like
11

Gotcha, I’m good with the latest version you did (and any other improvement you might wanna make over that), overall clear improvement over previous state, so thanks for pushing this fwd!

1 Like