Skip to content

[clang][docs] assert.h is not a good candidate for a textual header #165057

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 30, 2025
Merged

[clang][docs] assert.h is not a good candidate for a textual header #165057

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 5 additions & 12 deletions clang/docs/Modules.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -421,13 +421,7 @@ As an example, the module map file for the C standard library might look a bit l

.. parsed-literal::

module std [system] [extern_c] {
Copy link
Collaborator

@zygoloid zygoloid Oct 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why remove the extern_c here? This seems like a pretty good example of a time when it'd make sense to use this attribute.

Copy link
Collaborator

@zygoloid zygoloid Oct 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see you mentioned this in the PR description. I suppose whether this is appropriate depends on whether these headers are all pure C headers or if they themselves try to support inclusion from C++. I don't really mind whether we keep this or remove it.

Copy link
Contributor Author

@ian-twilightcoder ian-twilightcoder Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem with [extern_c] is it sticks all of the includes in the module inside of extern C which runs you into -Wmodule-import-in-extern-c which is promoted to an error by default. Plus you never know when an include will transitively include a C++ header like <stdint.h>, so you really don't want your includes to be extern C. It's kind of a flawed attribute, at some point I would propose that we remove it.

Copy link
Collaborator

@zygoloid zygoloid Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm.

It's definitely flawed in that it's viral and requires strong layering between your C headers and your C++ headers, but if you have proper layering, if your C library isn't including C++ headers, and if you can add the attribute to your C library and its transitive dependencies, it can work well. Not everyone has a setup where the C library includes C++ headers rather than being layered entirely beneath the C++ library.

But you make a good point that it's got enough problems that making a blanket recommendation to use it would be unreasonable. Yeah, I'm convinced we shouldn't be using it in this example.

module assert {
textual header "assert.h"
header "bits/assert-decls.h"
export *
}

module std [system] {
module complex {
header "complex.h"
export *
Expand All @@ -440,7 +434,6 @@ As an example, the module map file for the C standard library might look a bit l

module errno {
header "errno.h"
header "sys/errno.h"
export *
}

Expand Down Expand Up @@ -673,14 +666,14 @@ of checking *use-declaration*\s, and must still be a lexically-valid header
file. In the future, we intend to pre-tokenize such headers and include the
token sequence within the prebuilt module representation.

A header with the ``exclude`` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module, even if an ``umbrella`` header or directory would otherwise make it part of the module.
A header with the ``exclude`` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module, even if an ``umbrella`` directory would otherwise make it part of the module.

**Example:** The C header ``assert.h`` is an excellent candidate for a textual header, because it is meant to be included multiple times (possibly with different ``NDEBUG`` settings). However, declarations within it should typically be split into a separate modular header.
**Example:** A "X macro" header is an excellent candidate for a textual header, because it is can't be compiled standalone, and by itself does not contain any declarations.

.. parsed-literal::

module std [system] {
textual header "assert.h"
module MyLib [system] {
textual header "xmacros.h"
}

A given header shall not be referenced by more than one *header-declaration*.
Expand Down
Loading