Skip to content

[libc++] Stabilize transitive includes for C++23 #134143

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 3 commits into from
Aug 28, 2025
Merged

[libc++] Stabilize transitive includes for C++23 #134143

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
08e02bc
[libc++] Stabilize transitive includes for C++23
ldionne Apr 2, 2025
4fa2006
Update documentation per discussion
ldionne Jul 2, 2025
c095b42
Review comments
ldionne Jul 3, 2025
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
31 changes: 21 additions & 10 deletions libcxx/docs/DesignDocs/HeaderRemovalPolicy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,10 @@ to port headers to platforms with reduced functionality.

A disadvantage is that users unknowingly depend on these transitive includes.
Thus removing an include might break their build after upgrading a newer
version of libc++. For example, ``<algorithm>`` is often forgotten but using
algorithms will still work through those transitive includes. This problem is
solved by modules, however in practice most people do not use modules (yet).
version of libc++ by reducing the set of declarations provided by a header.
For example, ``<algorithm>`` is often forgotten but using algorithms will
still work through those transitive includes. This problem is solved by modules,
however in practice most people do not use modules (yet).

To ease the removal of transitive includes in libc++, libc++ will remove
unnecessary transitive includes in newly supported C++ versions. This means
Expand All @@ -33,21 +34,31 @@ newer version of the Standard. Libc++ also reserves the right to remove
transitive includes at any other time, however new language versions will be
used as a convenient way to perform bulk removals of transitive includes.

For libc++ developers, this means that any transitive include removal must be
guarded by something of the form:
However, libc++ intends not to gratuitously break users on stable versions of
the Standard. Hence, we intend to maintain backwards compatibility of the
declarations we provide in a header, within reason. For libc++ developers, this
means that any transitive include removal of a public header must be guarded by
something of the form:
Copy link
Contributor

Choose a reason for hiding this comment

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

This sounds to me a bit like we'll never remove the transitive includes. Could we add a "for now" somewhere so that it's clear this is just the current state and not a guarantee we want to keep forever? (At least I think we agree that we don't want to keep it forever?)

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes, we agree that we may not keep them forever. I'd be okay with removing them, I just want an agreed-upon plan to do that and in particular I'd like to avoid breaking users piece by piece at every release: one large documented break creates a lot less work for everyone.


.. code-block:: cpp

#if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 20
#if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 23
# include <algorithm>
# include <iterator>
# include <utility>
#endif

When users define ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES``, libc++ will not
include transitive headers, regardless of the language version. This can be
useful for users to aid the transition to a newer language version, or by users
who simply want to make sure they include what they use in their code.
Occasionally, private headers may also be included transitively for backwards
compatibility in the same manner.

When users define ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES``, libc++ will not include
transitive headers, regardless of the language version. This can be useful for users
to aid the transition to a newer language version, or by users who simply want to
make sure they include what they use in their code.
Copy link
Contributor

Choose a reason for hiding this comment

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

We should mention that this is not stable. (And maybe consider adding a stable version of it so people can migrate?)

Copy link
Member Author

Choose a reason for hiding this comment

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

I've mentioned that this isn't stable. I don't think it makes sense to provide a stable version of it since this is inherently for people who can manage (or want to) to adapt.


We currently strive to provide backwards compatibility on the set of declarations
provided by a header in all Standard modes starting with C++23. Note that this is
very difficult to actually enforce, so this is done only on a best effort basis.


Rationale
Expand Down
Loading