[libc++] Rename __tuple to __tuple_dir to avoid file collision

[mgorny]

Summary

Rename the __tuple directory in libc++ headers to __tuple_dir
to avoid file collision when installing. Historically, __tuple has
been a file and it has been replaced by a directory
in 2d52c6bfae801b016dd3627b8c0e7c4a99405549. Replacing a regular file
with a directory (or more importantly, the other way around when
downgrading) is not universally supported. Since this is an internal
header, its actual name should not matter, so just rename it to avoid
problems.

[Mordante]

The build fails since the generated files aren't updated. This can be done by running ninja libcxx-generate-files. Alternatively one of the libc++ maintainers can commandeer the patch to fix these issues.

libcxx/include/CMakeLists.txt

521

IIRC this used to be a file to, is that also an issue?

[mgorny]

I've regenerated files. However, I needed to modify the generator to strip the extra 2 from public header name. That's not the prettiest solution, I admit, so I'm open to better ideas.

libcxx/include/CMakeLists.txt

521

Yeah, it was. However, since it's in 15.x already, I don't have a strong opinion wrt fixing it now. It only occurred to me now that there's a relatively simple solution to the problem.

If you think we should change that too, then I can make a patch (perhaps separate from this one?).

[mgorny]

Regenerate files.

[ldionne]

From the patch, I'm not sure I understand what's the process you are expecting us to follow for renaming a file to a directory. Are you suggesting that we rename it to __tuple2 for some amount of time (how long?) and then rename it back to __tuple? Are you suggesting that we instead never reuse a name that has been used for a header in the past for a directory?

I know that renaming files to directories can cause issues, I myself have issues downstream because of this. But I think those are shortcomings of the systems we are using, and I have been unwilling to create complexity upstream because of that, so far. If this problem is shared by more than just me, it may be worth finding a solution for everyone, however never reusing a previous file name is not going to fly. I think the best we can do is probably wait for one release before doing the renaming back to __tuple.

[mgorny]

Well, I'd prefer renaming them permanently but one release would be good enough for Gentoo. Alternatively, at least for private headers we could streamline this by using a distinct prefix/suffix for directories, e.g. __tuple for a file, and __tuple_dir for directory. This would probably be cleaner than temporarily appending 2.

[Mordante]

libcxx/include/CMakeLists.txt

521

Not per se, if there are no complains from users I don't feel we need to.

[mgorny]

Gentle ping. Do you have any specific requests on how this could be improved? I'd love to see the problem fixed before the next weekend (that's when I do snapshots for Gentoo).

[tahonermann]

I've hit this issue too and it was a source of frustration. Though the directory name is an internal detail that we should be free to change, I don't like the name __tuple2 as a permanent replacement. Unfortunately, any name we choose will be inconsistent with the names used for other such detail directories; the only directory currently present there that doesn't map directly to a header name is __debug_utils.

The core problem is that the install step does not attempt to delete any existing __tuple file before attempting to create the __tuple directory and copy files. Can we not just add a step to the install target to force that to happen?

[thesamesam]

In D139270#3984551, @tahonermann wrote:

The core problem is that the install step does not attempt to delete any existing __tuple file before attempting to create the __tuple directory and copy files. Can we not just add a step to the install target to force that to happen?

That won't help with anything that uses DESTDIR/some staging area before merging to the live filesystem, unfortunately.

Is __tuple2 acceptable to you if it's only for a single release?

[Mordante]

In D139270#3984551, @tahonermann wrote:

I've hit this issue too and it was a source of frustration. Though the directory name is an internal detail that we should be free to change, I don't like the name __tuple2 as a permanent replacement. Unfortunately, any name we choose will be inconsistent with the names used for other such detail directories; the only directory currently present there that doesn't map directly to a header name is __debug_utils.

I ran into it in the past too, but as libc++ developer it's quite easy to figure out what happened. But I agree that for the average user the current way isn't user friendly.

The core problem is that the install step does not attempt to delete any existing __tuple file before attempting to create the __tuple directory and copy files. Can we not just add a step to the install target to force that to happen?

I like this idea better than using (temporary) __fooN headers. @philnik do you know how easy it is to remove these "obsolete" files? This would solve upgrading, but not downgrading from the current __foo is a directory to __foo is a file.

[thesamesam]

In D139270#3984960, @Mordante wrote:

I like this idea better than using (temporary) __fooN headers. @philnik do you know how easy it is to remove these "obsolete" files? This would solve upgrading, but not downgrading from the current __foo is a directory to __foo is a file.

Like I said, it can't work. It implies that the build system would interfere with the live system and disrespect DESTDIR and friends. It would not work for distributions at all.

[tahonermann]

Is __tuple2 acceptable to you if it's only for a single release?

I don't think so. Unless I'm misunderstanding something, the same issue would occur when trying to revert to the original __tuple name since there is still no guarantee that a __tuple file from an earlier version wasn't still present.

That won't help with anything that uses DESTDIR/some staging area before merging to the live filesystem, unfortunately.

I'm not sure I'm following. It sounds like you are suggesting there are two issues:

1. As part of the install step performed by the LLVM build system, a __tuple file in the install location will interfere with the installation of the __tuple directory.
2. If the target of the install step performed by the LLVM build system is a staging area, then a secondary non-LLVM process that copies/merges (portions of) the LLVM install to a live system might (or might not) encounter a problem copying/merging the __tuple directory if a file is present.

If I have that right, then my perspective is that the second problem is not one that should be solved by LLVM. If I don't have that right, please clarify the scenario.

[thesamesam]

In D139270#3984998, @tahonermann wrote:

Is __tuple2 acceptable to you if it's only for a single release?

I don't think so. Unless I'm misunderstanding something, the same issue would occur when trying to revert to the original `__tuple` name since there is still no guarantee that a __tuple file from an earlier version wasn't still present.

It wouldn't, because:

• going from 15->16, __tuple gets replaced by __tuple2 (and the package manager can remove __tuple)
• going from 16->17, __tuple2 is removed, and __tuple is added (as a new directory, not a replacement of a file)

You can't really have libcxx installed in parallel with multiple versions (at least, Gentoo doesn't, and I'm not aware of anyone else doing this, as it's not really interesting to do it), so it ends up being a non-issue as a result.

You might have it being an issue upgrading older systems, but then it already is now, and at least we mitigated it for most people.

No guarantee, but way less likely, and then way less inconvenience for the 90% case.

The issue is package managers often can't handle replacing a symlink directly with a directory. By having a release in between, it becomes the same as a new file.

That won't help with anything that uses DESTDIR/some staging area before merging to the live filesystem, unfortunately.

I'm not sure I'm following. It sounds like you are suggesting there are two issues:

1. As part of the install step performed by the LLVM build system, a __tuple file in the install location will interfere with the installation of the __tuple directory.
2. If the target of the install step performed by the LLVM build system is a staging area, then a secondary non-LLVM process that copies/merges (portions of) the LLVM install to a live system might (or might not) encounter a problem copying/merging the __tuple directory if a file is present.

If I have that right, then my perspective is that the second problem is not one that should be solved by LLVM. If I don't have that right, please clarify the scenario.

1. This would affect any tarball to be installed to a system (including e.g. cpack) because you can't represent that "delete the dir first" part in extraction. Build systems do not usually touch the live filesystem for this reason - it prevents any sort of staging area or packing. I don't know if LLVM produces any of these, but the fact that a few people have mentioned they've hit this outside of Gentoo means it's not specific to us at all.
2. Even if something is not _technically_ within LLVM's purview, it's often nice to distributions to accommodate them if it's not a major inconvenience. That's what the discussion above mentions -- a lot of this is about making life easier by handling it upstream briefly. It's an unusual operation to do (changing a file to a directory) and it's hit an edge-case which somebody has asked for a temporary workaround for. As explained earlier in this comment, it's sufficient for almost-all hitting this to just have it for one release, because then it's no longer a "replacement", just a "new directory".

[tahonermann]

The issue is package managers often can't handle replacing a symlink directly with a directory. By having a release in between, it becomes the same as a new file.

Doesn't that assume that the intervening package is actually installed?

If we just ship a renamed directory now, what are the chances that package managers will know to modify their package to remove the __tuple file so that a future version of the package can reuse that name? The chances seem pretty high to me.

For tarball-based installations, a temporary rename doesn't seem to allow a return to the original name without some additional ability to delete the original file.

I empathize with the issue you are facing. I don't have a lot of experience with package managers, but my understanding is that most have some ability to run code ahead of time. If nothing else, a package could have a dependency on another package that only contains post-install cleanup steps; e.g., a package that installs nothing and then runs a cleanup step to remove the __tuple file. Is this not a viable option for Gentoo?

[mgorny]

Package managers track all installed files, and remove files that are no longer installed by the specific package version. However, the removal happens *after* installing the new version.

Yes, Gentoo can workaround this, and every other distribution out there can also probably work around this. The problem is: why does everyone has to repeatedly add complex workarounds when this can be resolved here trivially, so that things "just work" for everyone?

[tahonermann]

Package managers track all installed files, and remove files that are no longer installed by the specific package version. However, the removal happens *after* installing the new version.

Thank you; that resolves my concern about package managers neglecting to remove outdated files.

Yes, Gentoo can workaround this, and every other distribution out there can also probably work around this. The problem is: why does everyone has to repeatedly add complex workarounds when this can be resolved here trivially, so that things "just work" for everyone?

That question can be turned around; why should software authors need to rename their source files to work around deficiencies in package managers?

Part of my reaction is due to dislike for the proposed names. It is somewhat common to tag a number on to the end of a file name to indicate a new version of some feature, often one that is incompatible or risky in some way. In this case, source files are just being reorganized; the interface isn't changing. The "2" is confusing in that respect. I'm not fond of "__tuple_dir" either as the "_dir" part is redundant and doesn't add any additional information.

I took a closer look at the files in the "tuple" directory. None of them are directly included by the "tuple" header. They all appear to be related to support for tuple-like types in general; not to the implementation of std::tuple. That suggests names like "tuple_protocol", "tuple_support", or "tuple_like" might be more appropriate. If @ldionne is supportive of any of those names (or something similar), I'll have no objection to a rename.

[tahonermann]

libcxx/utils/generate_iwyu_mapping.py

35–36

This is a change I would object to on the basis that it is fragile.

[Mordante]

In D139270#3989169, @tahonermann wrote:

I took a closer look at the files in the "tuple" directory. None of them are directly included by the "tuple" header. They all appear to be related to support for tuple-like types in general; not to the implementation of std::tuple. That suggests names like "tuple_protocol", "tuple_support", or "tuple_like" might be more appropriate. If @ldionne is supportive of any of those names (or something similar), I'll have no objection to a rename.

Interesting. Normally we always should include the __foo/*.h headers in foo. But here we indeed don't do that. I leave the choice to @ldionne.

[philnik]

In D139270#3989229, @Mordante wrote:

In D139270#3989169, @tahonermann wrote:

I took a closer look at the files in the "tuple" directory. None of them are directly included by the "tuple" header. They all appear to be related to support for tuple-like types in general; not to the implementation of std::tuple. That suggests names like "tuple_protocol", "tuple_support", or "tuple_like" might be more appropriate. If @ldionne is supportive of any of those names (or something similar), I'll have no objection to a rename.

Interesting. Normally we always should include the __foo/*.h headers in foo. But here we indeed don't do that. I leave the choice to @ldionne.

I'm quite certain this was an oversight. Almost all the headers are actually used in <tuple>. I wonder why the modules build doesn't complain.

[mgorny]

Use __tuple_dir instead of the icky __tuple2.

[mgorny]

That question can be turned around; why should software authors need to rename their source files to work around deficiencies in package managers?

Well, I'm of the opinion that if you can help someone and it doesn't cost you anything, then there's no reason not to help. And that working with people who show concern about downstream problems and appreciation about their work is much nicer. The alternative is insulting distributors, so they lose interest, stop reporting bugs, start accumulating local patches and next thing you know, everything's one huge mess where every single program needs to include hacks for every variant of iibc++ out there.

[Mordante]

In D139270#4003752, @mgorny wrote:

That question can be turned around; why should software authors need to rename their source files to work around deficiencies in package managers?

Well, I'm of the opinion that if you can help someone and it doesn't cost you anything, then there's no reason not to help. And that working with people who show concern about downstream problems and appreciation about their work is much nicer. The alternative is insulting distributors, so they lose interest, stop reporting bugs, start accumulating local patches and next thing you know, everything's one huge mess where every single program needs to include hacks for every variant of iibc++ out there.

+1 I think we should try to avoid breaking downstream.

I see the build failed, this has nothing to do with your patch. Can you rebase your patch on main to fix that issue.

[mgorny]

Rebased.

[mgorny]

Thinking about it more, probably the cleanest long term solution would be to simply use .h suffix for files but that obviously won't solve the existing upgrade problem.

[tschuett]

Would __tuple_helpers or __tuple_utils be less ugly resp. obvious solutions to the challenge?

[mgorny]

In D139270#4003978, @tschuett wrote:

Would __tuple_helpers or __tuple_utils be less ugly resp. obvious solutions to the challenge?

I'm open to any name. I'd just appreciate if someone made a decision, so I wouldn't be updating the patch a few times in a row.

[ldionne]

In D139270#3989169, @tahonermann wrote:

That question can be turned around; why should software authors need to rename their source files to work around deficiencies in package managers?

This, x1000.

However, concretely I think it's reasonable to use this workaround if it's only for a single release, and then we can rename it to __tuple again. And indeed, if we follow our own conventions going forward, this shouldn't be an issue since detail headers have a .h extension.

Let's use __tuple_dir for LLVM 16 and rename it back to __tuple in LLVM 17. We also have the same problem for __string unless I am mistaken, @mgorny
can you handle that in your patch?

@Mordante @philnik We had agreed to include all __foo/*.h headers inside <foo>, but we didn't do it consistently and it turns out that it's sometimes impossible to do it consistently because of circular dependencies (in type_traits for example IIRC). We will have to reconsider that policy.

@mgorny Please let us know whether the above solution (i.e. rename but only for one release) works for you.

[mgorny]

In D139270#4005137, @ldionne wrote:

Let's use __tuple_dir for LLVM 16 and rename it back to __tuple in LLVM 17. We also have the same problem for __string unless I am mistaken, @mgorny
can you handle that in your patch?

Will do.

@mgorny Please let us know whether the above solution (i.e. rename but only for one release) works for you.

It's not perfect but it's good enough. I suppose you'll also accept future one-release renames if similar problems occur?

Also, I'd really prefer if you didn't call it "deficiency in the package manager" because I find that insulting to the lot of effort many of us put in the package managers. It's not a "deficiency", it's a conscious decision not to add a lot of complexity combined with fragility to handle a corner case affecting at most a few (libc++ is the only one I'm aware of) out of 20000+ packages.

[mgorny]

We also have the same problem for __string unless I am mistaken, @mgorny

Actually, __string was granularized in LLVM 15 already, so I don't think that's necessary. However, I can still do it if you preferred.

[ldionne]

In D139270#4005162, @mgorny wrote:

We also have the same problem for __string unless I am mistaken, @mgorny

Actually, __string was granularized in LLVM 15 already, so I don't think that's necessary. However, I can still do it if you preferred.

Oh, really? Ok, then leave it out.

In D139270#4005151, @mgorny wrote:

It's not perfect but it's good enough. I suppose you'll also accept future one-release renames if similar problems occur?

Yes, in fact the expectation would be that we rename them to __foo_dir immediately upon creating them if we remember about this (which I hope we will, and also the risk for this happening again is not suuuuper high since we don't have that many headers in that category).

Also, I'd really prefer if you didn't call it "deficiency in the package manager" because I find that insulting to the lot of effort many of us put in the package managers. It's not a "deficiency", it's a conscious decision not to add a lot of complexity combined with fragility to handle a corner case affecting at most a few (libc++ is the only one I'm aware of) out of 20000+ packages.

Don't get me wrong, I think everybody here has tremendous respect for folks who handle distributions. From our perspective though, it seems kind of surprising that making a seemingly valid and simple change to our code organization would trigger an issue much further down the distribution pipeline due to a directory/file mismatch. But like I said, I don't think it matters much -- the workaround is simple and temporary, so we'll try to remember to do it on a best effort basis and everyone should be happy.

libcxx/utils/generate_iwyu_mapping.py

35–36

I actually don't quite understand why this change is needed, can you explain? Sorry if that's simple.

[mgorny]

libcxx/utils/generate_iwyu_mapping.py

35–36

Without this change:

diff --git a/libcxx/include/libcxx.imp b/libcxx/include/libcxx.imp
index 2c591b71737b..2ed026d76e4a 100644
--- a/libcxx/include/libcxx.imp
+++ b/libcxx/include/libcxx.imp
@@ -39,7 +39,7 @@
   { include: [ "@<__string/.*>", "private", "<string>", "public" ] },
   { include: [ "@<__support/.*>", "private", "<support>", "public" ] },
   { include: [ "@<__thread/.*>", "private", "<thread>", "public" ] },
-  { include: [ "@<__tuple_dir/.*>", "private", "<tuple>", "public" ] },
+  { include: [ "@<__tuple_dir/.*>", "private", "<tuple_dir>", "public" ] },
   { include: [ "@<__type_traits/.*>", "private", "<type_traits>", "public" ] },
   { include: [ "@<__utility/.*>", "private", "<utility>", "public" ] },
   { include: [ "@<__variant/.*>", "private", "<variant>", "public" ] },

[ldionne]

libcxx/utils/generate_iwyu_mapping.py

35–36

Oh, thanks. I suggest we do this instead:

temporary_mappings = {'__tuple_dir': 'tuple'}
for dir in detail_directories:
    public_header = temporary_mappings.get(dir, dir.lstrip('_'))
    result.append(f'{generate(f"@<{dir}/.*>", public_header)},')

That way we'll find this when we grep for __tuple_dir in the future.

[mgorny]

Use explicit mapping as requested.

[mgorny]

libcxx/utils/generate_iwyu_mapping.py

35–36

Thanks. I've done that, except that I've left i as the loop var since dir is a built-in function in Python.

[ldionne]

Thanks, LGTM with green CI.

libcxx/include/CMakeLists.txt

set(files
   __ranges/take_view.h
   __ranges/take_while_view.h
   __ranges/transform_view.h
   __ranges/view_interface.h
   __ranges/views.h
   __ranges/zip_view.h
   __split_buffer
   __std_stream
   __string/char_traits.h
   __string/extern_template_lists.h
   __support/android/locale_bionic.h
   __support/fuchsia/xlocale.h
   __support/ibm/gettod_zos.h
   __support/ibm/locale_mgmt_zos.h
   __support/ibm/nanosleep.h
   __support/ibm/xlocale.h
   __support/musl/xlocale.h
   __support/newlib/xlocale.h
   __support/openbsd/xlocale.h
   __support/solaris/floatingpoint.h
   __support/solaris/wchar.h
   __support/solaris/xlocale.h
   __support/win32/locale_win32.h
   __support/xlocale/__nop_locale_mgmt.h
   __support/xlocale/__posix_l_fallback.h
   __support/xlocale/__strtonum_fallback.h
   __thread/poll_with_backoff.h
   __thread/timed_backoff_policy.h
   __threading_support
   __tree
-  __tuple/apply_cv.h
-  __tuple/make_tuple_types.h
-  __tuple/sfinae_helpers.h
-  __tuple/tuple_element.h
-  __tuple/tuple_indices.h
-  __tuple/tuple_like.h
-  __tuple/tuple_size.h
-  __tuple/tuple_types.h
+  __tuple_dir/apply_cv.h
+  __tuple_dir/make_tuple_types.h
+  __tuple_dir/sfinae_helpers.h
+  __tuple_dir/tuple_element.h
+  __tuple_dir/tuple_indices.h
+  __tuple_dir/tuple_like.h
+  __tuple_dir/tuple_size.h
+  __tuple_dir/tuple_types.h
   __type_traits/add_const.h
   __type_traits/add_cv.h
   __type_traits/add_lvalue_reference.h
   __type_traits/add_pointer.h
   __type_traits/add_rvalue_reference.h
   __type_traits/add_volatile.h
   __type_traits/aligned_storage.h
   __type_traits/aligned_union.h

libcxx/include/__functional/hash.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___FUNCTIONAL_HASH_H
 #define _LIBCPP___FUNCTIONAL_HASH_H
 
 #include <__config>
 #include <__functional/unary_function.h>
 #include <__fwd/hash.h>
-#include <__tuple/sfinae_helpers.h>
+#include <__tuple_dir/sfinae_helpers.h>
 #include <__utility/forward.h>
 #include <__utility/move.h>
 #include <__utility/pair.h>
 #include <__utility/swap.h>
 #include <cstddef>
 #include <cstdint>
 #include <cstring>
 #include <limits>

libcxx/include/__fwd/get.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___FWD_GET_H
 #define _LIBCPP___FWD_GET_H
 
 #include <__config>
 #include <__fwd/array.h>
 #include <__fwd/pair.h>
 #include <__fwd/tuple.h>
-#include <__tuple/tuple_element.h>
+#include <__tuple_dir/tuple_element.h>
 #include <cstddef>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 
 _LIBCPP_BEGIN_NAMESPACE_STD
 

libcxx/include/__memory/compressed_pair.h

 // -*- C++ -*-
 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___MEMORY_COMPRESSED_PAIR_H
 #define _LIBCPP___MEMORY_COMPRESSED_PAIR_H
 
 #include <__config>
 #include <__fwd/get.h>
 #include <__fwd/tuple.h>
-#include <__tuple/tuple_indices.h>
+#include <__tuple_dir/tuple_indices.h>
 #include <__type_traits/dependent_type.h>
 #include <__utility/forward.h>
 #include <__utility/move.h>
 #include <__utility/piecewise_construct.h>
 #include <type_traits>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header

libcxx/include/__ranges/subrange.h

 #include <__iterator/incrementable_traits.h>
 #include <__iterator/iterator_traits.h>
 #include <__ranges/access.h>
 #include <__ranges/concepts.h>
 #include <__ranges/dangling.h>
 #include <__ranges/enable_borrowed_range.h>
 #include <__ranges/size.h>
 #include <__ranges/view_interface.h>
-#include <__tuple/tuple_element.h>
-#include <__tuple/tuple_size.h>
+#include <__tuple_dir/tuple_element.h>
+#include <__tuple_dir/tuple_size.h>
 #include <__utility/move.h>
 #include <type_traits>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 
 _LIBCPP_BEGIN_NAMESPACE_STD

libcxx/include/__tuple_dir/make_tuple_types.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___TUPLE_MAKE_TUPLE_TYPES_H
 #define _LIBCPP___TUPLE_MAKE_TUPLE_TYPES_H
 
 #include <__config>
 #include <__fwd/array.h>
 #include <__fwd/tuple.h>
-#include <__tuple/apply_cv.h>
-#include <__tuple/tuple_element.h>
-#include <__tuple/tuple_indices.h>
-#include <__tuple/tuple_size.h>
-#include <__tuple/tuple_types.h>
+#include <__tuple_dir/apply_cv.h>
+#include <__tuple_dir/tuple_element.h>
+#include <__tuple_dir/tuple_indices.h>
+#include <__tuple_dir/tuple_size.h>
+#include <__tuple_dir/tuple_types.h>
 #include <__type_traits/remove_cv.h>
 #include <__type_traits/remove_reference.h>
 #include <cstddef>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 

libcxx/include/__tuple_dir/sfinae_helpers.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___TUPLE_SFINAE_HELPERS_H
 #define _LIBCPP___TUPLE_SFINAE_HELPERS_H
 
 #include <__config>
 #include <__fwd/tuple.h>
-#include <__tuple/make_tuple_types.h>
-#include <__tuple/tuple_element.h>
-#include <__tuple/tuple_like.h>
-#include <__tuple/tuple_size.h>
-#include <__tuple/tuple_types.h>
+#include <__tuple_dir/make_tuple_types.h>
+#include <__tuple_dir/tuple_element.h>
+#include <__tuple_dir/tuple_like.h>
+#include <__tuple_dir/tuple_size.h>
+#include <__tuple_dir/tuple_types.h>
 #include <__type_traits/enable_if.h>
 #include <__type_traits/integral_constant.h>
 #include <__type_traits/is_assignable.h>
 #include <__type_traits/is_constructible.h>
 #include <__type_traits/is_convertible.h>
 #include <__type_traits/is_same.h>
 #include <__type_traits/remove_cvref.h>
 #include <__type_traits/remove_reference.h>

libcxx/include/__tuple_dir/tuple_element.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___TUPLE_TUPLE_ELEMENT_H
 #define _LIBCPP___TUPLE_TUPLE_ELEMENT_H
 
 #include <__config>
-#include <__tuple/tuple_indices.h>
-#include <__tuple/tuple_types.h>
+#include <__tuple_dir/tuple_indices.h>
+#include <__tuple_dir/tuple_types.h>
 #include <__type_traits/add_const.h>
 #include <__type_traits/add_cv.h>
 #include <__type_traits/add_volatile.h>
 #include <cstddef>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif

libcxx/include/__tuple_dir/tuple_like.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___TUPLE_TUPLE_LIKE_H
 #define _LIBCPP___TUPLE_TUPLE_LIKE_H
 
 #include <__config>
 #include <__fwd/array.h>
 #include <__fwd/pair.h>
 #include <__fwd/tuple.h>
-#include <__tuple/tuple_types.h>
+#include <__tuple_dir/tuple_types.h>
 #include <__type_traits/integral_constant.h>
 #include <cstddef>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 
 _LIBCPP_BEGIN_NAMESPACE_STD

libcxx/include/__tuple_dir/tuple_size.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___TUPLE_TUPLE_SIZE_H
 #define _LIBCPP___TUPLE_TUPLE_SIZE_H
 
 #include <__config>
 #include <__fwd/tuple.h>
-#include <__tuple/tuple_types.h>
+#include <__tuple_dir/tuple_types.h>
 #include <__type_traits/is_const.h>
 #include <__type_traits/is_volatile.h>
 #include <cstddef>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 

libcxx/include/__utility/pair.h

 #define _LIBCPP___UTILITY_PAIR_H
 
 #include <__compare/common_comparison_category.h>
 #include <__compare/synth_three_way.h>
 #include <__config>
 #include <__functional/unwrap_ref.h>
 #include <__fwd/get.h>
 #include <__fwd/tuple.h>
-#include <__tuple/sfinae_helpers.h>
-#include <__tuple/tuple_element.h>
-#include <__tuple/tuple_indices.h>
-#include <__tuple/tuple_size.h>
+#include <__tuple_dir/sfinae_helpers.h>
+#include <__tuple_dir/tuple_element.h>
+#include <__tuple_dir/tuple_indices.h>
+#include <__tuple_dir/tuple_size.h>
 #include <__type_traits/is_implicitly_default_constructible.h>
 #include <__utility/forward.h>
 #include <__utility/move.h>
 #include <__utility/piecewise_construct.h>
 #include <cstddef>
 #include <type_traits>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)

libcxx/include/array

 
 #include <__algorithm/equal.h>
 #include <__algorithm/fill_n.h>
 #include <__algorithm/lexicographical_compare.h>
 #include <__algorithm/swap_ranges.h>
 #include <__assert> // all public C++ headers provide the assertion handler
 #include <__config>
 #include <__iterator/reverse_iterator.h>
-#include <__tuple/sfinae_helpers.h>
+#include <__tuple_dir/sfinae_helpers.h>
 #include <__utility/integer_sequence.h>
 #include <__utility/move.h>
 #include <__utility/unreachable.h>
 #include <stdexcept>
 #include <type_traits>
 #include <version>
 
 // standard-mandated includes
 
 // [iterator.range]
 #include <__iterator/access.h>
 #include <__iterator/data.h>
 #include <__iterator/empty.h>
 #include <__iterator/reverse_access.h>
 #include <__iterator/size.h>
 
 // [array.syn]
 #include <compare>
 #include <initializer_list>
 
 // [tuple.helper]
-#include <__tuple/tuple_element.h>
-#include <__tuple/tuple_size.h>
+#include <__tuple_dir/tuple_element.h>
+#include <__tuple_dir/tuple_size.h>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 
 _LIBCPP_BEGIN_NAMESPACE_STD
 
 template <class _Tp, size_t _Size>

libcxx/include/libcxx.imp

[
   { include: [ "@<__memory/.*>", "private", "<memory>", "public" ] },
   { include: [ "@<__memory_resource/.*>", "private", "<memory_resource>", "public" ] },
   { include: [ "@<__numeric/.*>", "private", "<numeric>", "public" ] },
   { include: [ "@<__random/.*>", "private", "<random>", "public" ] },
   { include: [ "@<__ranges/.*>", "private", "<ranges>", "public" ] },
   { include: [ "@<__string/.*>", "private", "<string>", "public" ] },
   { include: [ "@<__support/.*>", "private", "<support>", "public" ] },
   { include: [ "@<__thread/.*>", "private", "<thread>", "public" ] },
-  { include: [ "@<__tuple/.*>", "private", "<tuple>", "public" ] },
+  { include: [ "@<__tuple_dir/.*>", "private", "<tuple>", "public" ] },
   { include: [ "@<__type_traits/.*>", "private", "<type_traits>", "public" ] },
   { include: [ "@<__utility/.*>", "private", "<utility>", "public" ] },
   { include: [ "@<__variant/.*>", "private", "<variant>", "public" ] },
 ]

libcxx/include/module.modulemap.in

module __thread {
       module poll_with_backoff    { private header "__thread/poll_with_backoff.h" }
       module timed_backoff_policy { private header "__thread/timed_backoff_policy.h" }
     }
   }
   module tuple {
     header "tuple"
     export *
 
-    module apply_cv         { private header "__tuple/apply_cv.h" }
+    module apply_cv         { private header "__tuple_dir/apply_cv.h" }
     module get_fwd          { private header "__fwd/get.h" }
-    module make_tuple_types { private header "__tuple/make_tuple_types.h" }
-    module sfinae_helpers   { private header "__tuple/sfinae_helpers.h" }
-    module tuple_element    { private header "__tuple/tuple_element.h" }
+    module make_tuple_types { private header "__tuple_dir/make_tuple_types.h" }
+    module sfinae_helpers   { private header "__tuple_dir/sfinae_helpers.h" }
+    module tuple_element    { private header "__tuple_dir/tuple_element.h" }
     module tuple_fwd        { private header "__fwd/tuple.h" }
-    module tuple_indices    { private header "__tuple/tuple_indices.h" }
-    module tuple_like       { private header "__tuple/tuple_like.h" }
-    module tuple_size       { private header "__tuple/tuple_size.h" }
-    module tuple_types      { private header "__tuple/tuple_types.h" }
+    module tuple_indices    { private header "__tuple_dir/tuple_indices.h" }
+    module tuple_like       { private header "__tuple_dir/tuple_like.h" }
+    module tuple_size       { private header "__tuple_dir/tuple_size.h" }
+    module tuple_types      { private header "__tuple_dir/tuple_types.h" }
   }
   module type_traits {
     header "type_traits"
     export functional.__functional.unwrap_ref
     export *
 
     module add_const                           { private header "__type_traits/add_const.h" }
     module add_cv                              { private header "__type_traits/add_cv.h" }

libcxx/include/optional

 #include <__assert> // all public C++ headers provide the assertion handler
 #include <__availability>
 #include <__concepts/invocable.h>
 #include <__config>
 #include <__functional/hash.h>
 #include <__functional/invoke.h>
 #include <__functional/unary_function.h>
 #include <__memory/construct_at.h>
-#include <__tuple/sfinae_helpers.h>
+#include <__tuple_dir/sfinae_helpers.h>
 #include <__utility/forward.h>
 #include <__utility/in_place.h>
 #include <__utility/move.h>
 #include <__utility/swap.h>
 #include <initializer_list>
 #include <new>
 #include <stdexcept>
 #include <type_traits>

libcxx/include/ranges

 // standard-mandated includes
 
 // [ranges.syn]
 #include <compare>
 #include <initializer_list>
 #include <iterator>
 
 // [tuple.helper]
-#include <__tuple/tuple_element.h>
-#include <__tuple/tuple_size.h>
+#include <__tuple_dir/tuple_element.h>
+#include <__tuple_dir/tuple_size.h>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 
 #endif // _LIBCPP_RANGES

libcxx/include/utility

 
 // standard-mandated includes
 
 // [utility.syn]
 #include <compare>
 #include <initializer_list>
 
 // [tuple.helper]
-#include <__tuple/tuple_element.h>
-#include <__tuple/tuple_size.h>
+#include <__tuple_dir/tuple_element.h>
+#include <__tuple_dir/tuple_size.h>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 
 #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 20
 #  include <iosfwd>
 #endif
 
 #endif // _LIBCPP_UTILITY

libcxx/test/libcxx/private_headers.verify.cpp

 #include <__ranges/views.h> // expected-error@*:* {{use of private header from outside its module: '__ranges/views.h'}}
 #include <__ranges/zip_view.h> // expected-error@*:* {{use of private header from outside its module: '__ranges/zip_view.h'}}
 #include <__split_buffer> // expected-error@*:* {{use of private header from outside its module: '__split_buffer'}}
 #include <__std_stream> // expected-error@*:* {{use of private header from outside its module: '__std_stream'}}
 #include <__string/char_traits.h> // expected-error@*:* {{use of private header from outside its module: '__string/char_traits.h'}}
 #include <__string/extern_template_lists.h> // expected-error@*:* {{use of private header from outside its module: '__string/extern_template_lists.h'}}
 #include <__thread/poll_with_backoff.h> // expected-error@*:* {{use of private header from outside its module: '__thread/poll_with_backoff.h'}}
 #include <__thread/timed_backoff_policy.h> // expected-error@*:* {{use of private header from outside its module: '__thread/timed_backoff_policy.h'}}
-#include <__tuple/apply_cv.h> // expected-error@*:* {{use of private header from outside its module: '__tuple/apply_cv.h'}}
-#include <__tuple/make_tuple_types.h> // expected-error@*:* {{use of private header from outside its module: '__tuple/make_tuple_types.h'}}
-#include <__tuple/sfinae_helpers.h> // expected-error@*:* {{use of private header from outside its module: '__tuple/sfinae_helpers.h'}}
-#include <__tuple/tuple_element.h> // expected-error@*:* {{use of private header from outside its module: '__tuple/tuple_element.h'}}
-#include <__tuple/tuple_indices.h> // expected-error@*:* {{use of private header from outside its module: '__tuple/tuple_indices.h'}}
-#include <__tuple/tuple_like.h> // expected-error@*:* {{use of private header from outside its module: '__tuple/tuple_like.h'}}
-#include <__tuple/tuple_size.h> // expected-error@*:* {{use of private header from outside its module: '__tuple/tuple_size.h'}}
-#include <__tuple/tuple_types.h> // expected-error@*:* {{use of private header from outside its module: '__tuple/tuple_types.h'}}
+#include <__tuple_dir/apply_cv.h> // expected-error@*:* {{use of private header from outside its module: '__tuple_dir/apply_cv.h'}}
+#include <__tuple_dir/make_tuple_types.h> // expected-error@*:* {{use of private header from outside its module: '__tuple_dir/make_tuple_types.h'}}
+#include <__tuple_dir/sfinae_helpers.h> // expected-error@*:* {{use of private header from outside its module: '__tuple_dir/sfinae_helpers.h'}}
+#include <__tuple_dir/tuple_element.h> // expected-error@*:* {{use of private header from outside its module: '__tuple_dir/tuple_element.h'}}
+#include <__tuple_dir/tuple_indices.h> // expected-error@*:* {{use of private header from outside its module: '__tuple_dir/tuple_indices.h'}}
+#include <__tuple_dir/tuple_like.h> // expected-error@*:* {{use of private header from outside its module: '__tuple_dir/tuple_like.h'}}
+#include <__tuple_dir/tuple_size.h> // expected-error@*:* {{use of private header from outside its module: '__tuple_dir/tuple_size.h'}}
+#include <__tuple_dir/tuple_types.h> // expected-error@*:* {{use of private header from outside its module: '__tuple_dir/tuple_types.h'}}
 #include <__type_traits/add_const.h> // expected-error@*:* {{use of private header from outside its module: '__type_traits/add_const.h'}}
 #include <__type_traits/add_cv.h> // expected-error@*:* {{use of private header from outside its module: '__type_traits/add_cv.h'}}
 #include <__type_traits/add_lvalue_reference.h> // expected-error@*:* {{use of private header from outside its module: '__type_traits/add_lvalue_reference.h'}}
 #include <__type_traits/add_pointer.h> // expected-error@*:* {{use of private header from outside its module: '__type_traits/add_pointer.h'}}
 #include <__type_traits/add_rvalue_reference.h> // expected-error@*:* {{use of private header from outside its module: '__type_traits/add_rvalue_reference.h'}}
 #include <__type_traits/add_volatile.h> // expected-error@*:* {{use of private header from outside its module: '__type_traits/add_volatile.h'}}
 #include <__type_traits/aligned_storage.h> // expected-error@*:* {{use of private header from outside its module: '__type_traits/aligned_storage.h'}}
 #include <__type_traits/aligned_union.h> // expected-error@*:* {{use of private header from outside its module: '__type_traits/aligned_union.h'}}

libcxx/utils/generate_iwyu_mapping.py

for i in include.iterdir():
         if i.name.startswith('__'):
             detail_files.append(i.name)
             continue
 
         if i.name.endswith('.h'):
             c_headers.append(i.name)
 
     result = []
+    temporary_mappings = {'__tuple_dir': 'tuple'}
     for i in detail_directories:
-        result.append(f'{generate(f"@<{i}/.*>", i[2:])},')
+        public_header = temporary_mappings.get(i, i.lstrip('_'))
+        result.append(f'{generate(f"@<{i}/.*>", public_header)},')
 
     for i in detail_files:
         public = []
         if   i == '__assert': continue
         elif i == '__availability': continue
         elif i == '__bit_reference': continue
         elif i == '__bits': public = ['bits']
         elif i == '__bsd_locale_defaults.h': continue