Skip to content

Commit

Permalink
[docs] Update StandardCPlusPlusModules.rst with clang18
Browse files Browse the repository at this point in the history
Changed Things:
- Mentioning we need to specify BMIs for indirectly dependent BMIs too.
- Remove the note for `delayed-template-parsing` since
  #61068 got closed.
- Add a note for #78850 since
  we've seen it for a lot of times.
- Add a note for #78173 since
  we've seen it for a lot of times.
  • Loading branch information
ChuanqiXu9 committed Jan 22, 2024
1 parent 745883b commit a31a600
Showing 1 changed file with 63 additions and 6 deletions.
69 changes: 63 additions & 6 deletions clang/docs/StandardCPlusPlusModules.rst
Original file line number Diff line number Diff line change
Expand Up @@ -345,6 +345,9 @@ In case all ``-fprebuilt-module-path=<path/to/directory>``, ``-fmodule-file=<pat
takes highest precedence and ``-fmodule-file=<module-name>=<path/to/BMI>`` will take the second
highest precedence.

We need to specify all the dependent (directly and indirectly) BMIs.
See https://github.com/llvm/llvm-project/issues/62707 for detail.

When we compile a ``module implementation unit``, we must specify the BMI of the corresponding
``primary module interface unit``.
Since the language specification says a module implementation unit implicitly imports
Expand Down Expand Up @@ -689,14 +692,68 @@ the BMI within ``clang-cl.exe``.

This is tracked in: https://github.com/llvm/llvm-project/issues/64118

delayed template parsing is not supported/broken with C++ modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
false positive ODR violation diagnostic due to using inconsistent qualified but the same type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ODR violation is a pretty common issue when using modules.
Sometimes the program violated the One Definition Rule actually.
But sometimes it shows the compiler gives false positive diagnostics.

One often reported example is:

.. code-block:: c++

// part.cc
module;
typedef long T;
namespace ns {
inline void fun() {
(void)(T)0;
}
}
export module repro:part;

// repro.cc
module;
typedef long T;
namespace ns {
using ::T;
}
namespace ns {
inline void fun() {
(void)(T)0;
}
}
export module repro;
export import :part;

Currently the compiler complains about the inconsistent definition of `fun()` in
2 module units. This is incorrect. Since both definitions of `fun()` has the same
spelling and `T` refers to the same type entity finally. So the program should be
fine.

This is tracked in https://github.com/llvm/llvm-project/issues/78850.

Using TU-local entity in other units
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Module units are translation units. So the entities which should only be local to the
module unit itself shouldn't be used by other units in any means.

In the language side, to address the idea formally, the language specification defines
the concept of ``TU-local`` and ``exposure`` in
`basic.link/p14 <https://eel.is/c++draft/basic.link#14>`_,
`basic.link/p15 <https://eel.is/c++draft/basic.link#15>`_,
`basic.link/p16 <https://eel.is/c++draft/basic.link#16>`_,
`basic.link/p17 <https://eel.is/c++draft/basic.link#17>`_ and
`basic.link/p18 <https://eel.is/c++draft/basic.link#18>`_.

The feature `-fdelayed-template-parsing` can't work well with C++ modules now.
Note that this is significant on Windows since the option will be enabled by default
on Windows.
However, the compiler doesn't support these 2 ideas formally.
This results in unclear and confusing diagnostic messages.
And it is worse that the compiler may import TU-local entities to other units without any
diagnostics.

This is tracked in: https://github.com/llvm/llvm-project/issues/61068
This is tracked in https://github.com/llvm/llvm-project/issues/78173.

Header Units
============
Expand Down

0 comments on commit a31a600

Please sign in to comment.