1*4bdff4beSrobert================================================== 2*4bdff4beSrobertCapturing configuration information in the headers 3*4bdff4beSrobert================================================== 446035553Spatrick 546035553Spatrick.. contents:: 646035553Spatrick :local: 746035553Spatrick 846035553SpatrickThe Problem 946035553Spatrick=========== 1046035553Spatrick 11*4bdff4beSrobertlibc++ supports building the library with a number of different configuration options. 12*4bdff4beSrobertIn order to support persistent configurations and reduce arbitrary preprocessor logic 13*4bdff4beSrobertin the headers, libc++ has a mechanism to capture configuration options in the 14*4bdff4beSrobertinstalled headers so they can be used in the rest of the code. 1546035553Spatrick 1646035553Spatrick 1746035553SpatrickDesign Goals 1846035553Spatrick============ 1946035553Spatrick 20*4bdff4beSrobert* The solution should be simple, consistent and robust to avoid subtle bugs. 2146035553Spatrick 22*4bdff4beSrobert* Developers should test the code the same way it will be deployed -- in other words, 23*4bdff4beSrobert the headers used to run tests should be the same that we install in order 24*4bdff4beSrobert to avoid bugs creeping up. 2546035553Spatrick 26*4bdff4beSrobert* It should allow different targets or flavors of the library to use a different 27*4bdff4beSrobert configuration without having to duplicate all the libc++ headers. 2846035553Spatrick 2946035553Spatrick 3046035553SpatrickThe Solution 3146035553Spatrick============ 3246035553Spatrick 33*4bdff4beSrobertWhen you first configure libc++ using CMake, a ``__config_site`` file is generated 34*4bdff4beSrobertto capture the various configuration options you selected. The ``__config`` header 35*4bdff4beSrobertused by all other headers includes this ``__config_site`` header first in order to 36*4bdff4beSrobertget the correct configuration. 3746035553Spatrick 38*4bdff4beSrobertThe ``__config_site`` header is hence the only place where persistent configuration 39*4bdff4beSrobertis stored in the library. That header essentially reflects how the vendor configured 40*4bdff4beSrobertthe library. As we evolve the library, we can lift configuration options into that 41*4bdff4beSrobertheader in order to reduce arbitrary hardcoded choices elsewhere in the code. For 42*4bdff4beSrobertexample, instead of assuming that a specific platform doesn't provide some functionality, 43*4bdff4beSrobertwe can create a generic macro to guard it and vendors can define the macro when 44*4bdff4beSrobertconfiguring the library on that platform. This makes the "carve off" reusable in 45*4bdff4beSrobertother circumstances instead of tying it tightly to a single platform. 4646035553Spatrick 47*4bdff4beSrobertFurthermore, the Clang driver now looks for headers in a target-specific directory 48*4bdff4beSrobertfor libc++. By installing the ``__config_site`` header (and only that header) to 49*4bdff4beSrobertthis target-specific directory, it is possible to share the libc++ headers for 50*4bdff4beSrobertmultiple targets, and only duplicate the persistent information located in the 51*4bdff4beSrobert``__config_site`` header. For example: 5246035553Spatrick 53*4bdff4beSrobert.. code-block:: bash 5446035553Spatrick 55*4bdff4beSrobert include/c++/v1/ 56*4bdff4beSrobert vector 57*4bdff4beSrobert map 58*4bdff4beSrobert etc... 5946035553Spatrick 60*4bdff4beSrobert include/<targetA>/c++/v1/ 61*4bdff4beSrobert __config_site 6246035553Spatrick 63*4bdff4beSrobert include/<targetB>/c++/v1/ 64*4bdff4beSrobert __config_site 6546035553Spatrick 66*4bdff4beSrobertWhen compiling for ``targetA``, Clang will use the ``__config_site`` inside 67*4bdff4beSrobert``include/<targetA>/c++/v1/``, and the corresponding ``__config_site`` for 68*4bdff4beSrobert``targetB``. 69