[libcxx-commits] [libcxx] [libcxxabi] [libc++] Introduce the notion of a minimum header version (PR #166074)

[Louis Dionne via libcxx-commits]

================
@@ -638,3 +638,15 @@ if it is unavailable on the deployment target.
 Note that this mechanism is disabled by default in the "upstream" libc++. Availability annotations are only meaningful
 when shipping libc++ inside a platform (i.e. as a system library), and so vendors that want them should turn those
 annotations on at CMake configuration time.
+
+Minimum header Version
+======================
+
+In libc++ we add new functions and remove the use of other functions in the built library on a regular basis. To
+avoid breaking programs, we keep old functions in the built library indefinitely. However, there are platforms where
+some of these functions could never be referenced, because that platform never provided headers which referenced these
+functions. To reduce the size of the built library on these platforms, libc++ provides the notion of a minimum header
+version. The minimum header version describes the earliest version of the libc++ headers that can be used in a program
+linking against the library currently being built. Functions which have never been referenced in headers since the
+minimum header version are removed from the library. The minimum header version can be set with the CMake variables
+``LIBCXX_AVAILABILITY_MINIMUM_HEADER_VERSION`` and ``LIBCXXABI_AVAILABILITY_MINIMUM_HEADER_VERSION``.
----------------
ldionne wrote:

```suggestion
In libc++ we add new functions and remove the use of other functions in the built library on a regular basis. To
avoid breaking programs, we keep old functions in the built library as documented in our header support policy <INSERT LINK>. However, there are platforms where
some of these functions could never be referenced, because that platform never provided headers which referenced these
functions. To reduce the size of the built library on these platforms, libc++ provides the notion of a minimum header
version. The minimum header version describes the earliest version of the libc++ headers that can be used in a program
linking against the library currently being built. Functions which have never been referenced in headers since the
minimum header version are removed from the library. The minimum header version can be set with the CMake variables
``LIBCXX_AVAILABILITY_MINIMUM_HEADER_VERSION`` and ``LIBCXXABI_AVAILABILITY_MINIMUM_HEADER_VERSION``.
```

https://github.com/llvm/llvm-project/pull/166074