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