1===================
2Feature Test Macros
3===================
4
5.. contents::
6   :local:
7
8Overview
9========
10
11Libc++ implements the C++ feature test macros as specified in the C++2a standard,
12and before that in non-normative guiding documents
13(`See cppreference <https://en.cppreference.com/w/User:D41D8CD98F/feature_testing_macros>`_)
14
15
16Design
17======
18
19Feature test macros are tricky to track, implement, test, and document correctly.
20They must be available from a list of headers, they may have different values in
21different dialects, and they may or may not be implemented by libc++. In order to
22track all of these conditions correctly and easily, we want a Single Source of
23Truth (SSoT) that defines each feature test macro, its values, the headers it
24lives in, and whether or not is is implemented by libc++. From this SSoA we
25have enough information to automatically generate the `<version>` header,
26the tests, and the documentation.
27
28Therefore we maintain a SSoA in `libcxx/utils/generate_feature_test_macro_components.py`
29which doubles as a script to generate the following components:
30
31* The `<version>` header.
32* The version tests under `support.limits.general`.
33* Documentation of libc++'s implementation of each macro.
34
35Usage
36=====
37
38The `generate_feature_test_macro_components.py` script is used to track and
39update feature test macros in libc++.
40
41Whenever a feature test macro is added or changed, the table should be updated
42and the script should be re-ran. The script will clobber the existing test files,
43the documentation and the `<version>` header.
44