1===================== 2Header Removal Policy 3===================== 4 5Policy 6------ 7 8Libc++ is in the process of splitting larger headers into smaller modular 9headers. This makes it possible to remove these large headers from other 10headers. For example, instead of including ``<algorithm>`` entirely it is 11possible to only include the headers for the algorithms used. When the 12Standard indirectly adds additional header includes, using the smaller headers 13aids reducing the growth of top-level headers. For example ``<atomic>`` uses 14``std::chrono::nanoseconds`` and included ``<chrono>``. In C++20 ``<chrono>`` 15requires ``<format>`` which adds several other headers (like ``<string>``, 16``<optional>``, ``<tuple>``) which are not needed in ``<atomic>``. 17 18The benefit of using minimal headers is that the size of libc++'s top-level 19headers becomes smaller. This improves the compilation time when users include 20a top-level header. It also avoids header inclusion cycles and makes it easier 21to port headers to platforms with reduced functionality. 22 23A disadvantage is that users unknowingly depend on these transitive includes. 24Thus removing an include might break their build after upgrading a newer 25version of libc++. For example, ``<algorithm>`` is often forgotten but using 26algorithms will still work through those transitive includes. This problem is 27solved by modules, however in practice most people do not use modules (yet). 28 29To ease the removal of transitive includes in libc++, libc++ will remove 30unnecessary transitive includes in newly supported C++ versions. This means 31that users will have to fix their missing includes in order to upgrade to a 32newer version of the Standard. Libc++ also reserves the right to remove 33transitive includes at any other time, however new language versions will be 34used as a convenient way to perform bulk removals of transitive includes. 35 36For libc++ developers, this means that any transitive include removal must be 37guarded by something of the form: 38 39.. code-block:: cpp 40 41 #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 20 42 # include <algorithm> 43 # include <iterator> 44 # include <utility> 45 #endif 46 47When users define ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES``, libc++ will not 48include transitive headers, regardless of the language version. This can be 49useful for users to aid the transition to a newer language version, or by users 50who simply want to make sure they include what they use in their code. 51 52 53Rationale 54--------- 55 56Removing headers is not only an issue for software developers, but also for 57vendors. When a vendor updates libc++ several of their upstream packages might 58fail to compile, forcing them to fix these packages or file a bug with their 59upstream packages. Usually upgrading software to a new language standard is 60done explicitly by software developers. This means they most likely will 61discover and fix the missing includes, lessening the burden for the vendors. 62