76 lines · plain
1=====================2Header Removal Policy3=====================4 5Policy6------7 8Libc++ is in the process of splitting larger headers into smaller modular9headers. This makes it possible to remove these large headers from other10headers. For example, instead of including ``<algorithm>`` entirely it is11possible to only include the headers for the algorithms used. When the12Standard indirectly adds additional header includes, using the smaller headers13aids reducing the growth of top-level headers. For example ``<atomic>`` uses14``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-level19headers becomes smaller. This improves the compilation time when users include20a top-level header. It also avoids header inclusion cycles and makes it easier21to 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 newer25version of libc++ by reducing the set of declarations provided by a header.26For example, ``<algorithm>`` is often forgotten but using algorithms will27still work through those transitive includes. This problem is solved by modules,28however in practice most people do not use modules (yet).29 30To ease the removal of transitive includes in libc++, libc++ will remove31unnecessary transitive includes in newly supported C++ versions. This means32that users will have to fix their missing includes in order to upgrade to a33newer version of the Standard. Libc++ also reserves the right to remove34transitive includes at any other time, however new language versions will be35used as a convenient way to perform bulk removals of transitive includes.36 37However, libc++ intends not to gratuitously break users on stable versions of38the Standard. Hence, we intend to maintain backwards compatibility of the39declarations we provide in a header, within reason. We reserve the right to40break such backwards compatibility in the future, however we will strive to41do it in a user-friendly way, again within reason. For libc++ developers, this42means that any transitive include removal of a public header must be guarded by43something of the form:44 45.. code-block:: cpp46 47 #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 2348 # include <algorithm>49 # include <iterator>50 # include <utility>51 #endif52 53Occasionally, private headers may also be included transitively for backwards54compatibility in the same manner. We currently strive to provide backwards55compatibility on the set of declarations provided by a header in all Standard56modes starting with **C++23**. Note that this is very difficult to actually57enforce, so this is done only on a best effort basis.58 59When users define ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES``, libc++ will not include60transitive headers, regardless of the language version. This can be useful for users61to aid the transition to a newer language version, or by users who simply want to62make sure they include what they use in their code. However, note that defining this63macro means that the set of declarations and transitive includes provided by the library64may change from release to release, which can break your code.65 66 67Rationale68---------69 70Removing headers is not only an issue for software developers, but also for71vendors. When a vendor updates libc++ several of their upstream packages might72fail to compile, forcing them to fix these packages or file a bug with their73upstream packages. Usually upgrading software to a new language standard is74done explicitly by software developers. This means they most likely will75discover and fix the missing includes, lessening the burden for the vendors.76