1*4d6fc14bSjoerg======================================================= 2*4d6fc14bSjoergCapturing configuration information during installation 3*4d6fc14bSjoerg======================================================= 4*4d6fc14bSjoerg 5*4d6fc14bSjoerg.. contents:: 6*4d6fc14bSjoerg :local: 7*4d6fc14bSjoerg 8*4d6fc14bSjoergThe Problem 9*4d6fc14bSjoerg=========== 10*4d6fc14bSjoerg 11*4d6fc14bSjoergCurrently the libc++ supports building the library with a number of different 12*4d6fc14bSjoergconfiguration options. Unfortunately all of that configuration information is 13*4d6fc14bSjoerglost when libc++ is installed. In order to support "persistent" 14*4d6fc14bSjoergconfigurations libc++ needs a mechanism to capture the configuration options 15*4d6fc14bSjoergin the INSTALLED headers. 16*4d6fc14bSjoerg 17*4d6fc14bSjoerg 18*4d6fc14bSjoergDesign Goals 19*4d6fc14bSjoerg============ 20*4d6fc14bSjoerg 21*4d6fc14bSjoerg* The solution should not INSTALL any additional headers. We don't want an extra 22*4d6fc14bSjoerg #include slowing everybody down. 23*4d6fc14bSjoerg 24*4d6fc14bSjoerg* The solution should not unduly affect libc++ developers. The problem is limited 25*4d6fc14bSjoerg to installed versions of libc++ and the solution should be as well. 26*4d6fc14bSjoerg 27*4d6fc14bSjoerg* The solution should not modify any existing headers EXCEPT during installation. 28*4d6fc14bSjoerg It makes developers lives harder if they have to regenerate the libc++ headers 29*4d6fc14bSjoerg every time they are modified. 30*4d6fc14bSjoerg 31*4d6fc14bSjoerg* The solution should not make any of the libc++ headers dependent on 32*4d6fc14bSjoerg files generated by the build system. The headers should be able to compile 33*4d6fc14bSjoerg out of the box without any modification. 34*4d6fc14bSjoerg 35*4d6fc14bSjoerg* The solution should not have ANY effect on users who don't need special 36*4d6fc14bSjoerg configuration options. The vast majority of users will never need this so it 37*4d6fc14bSjoerg shouldn't cost them. 38*4d6fc14bSjoerg 39*4d6fc14bSjoerg 40*4d6fc14bSjoergThe Solution 41*4d6fc14bSjoerg============ 42*4d6fc14bSjoerg 43*4d6fc14bSjoergWhen you first configure libc++ using CMake we check to see if we need to 44*4d6fc14bSjoergcapture any options. If we haven't been given any "persistent" options then 45*4d6fc14bSjoergwe do NOTHING. 46*4d6fc14bSjoerg 47*4d6fc14bSjoergOtherwise we create a custom installation rule that modifies the installed __config 48*4d6fc14bSjoergheader. The rule first generates a dummy "__config_site" header containing the required 49*4d6fc14bSjoerg#defines. The contents of the dummy header are then prepended to the installed 50*4d6fc14bSjoerg__config header. By manually prepending the files we avoid the cost of an 51*4d6fc14bSjoergextra #include and we allow the __config header to be ignorant of the extra 52*4d6fc14bSjoergconfiguration all together. An example "__config" header generated when 53*4d6fc14bSjoerg-DLIBCXX_ENABLE_THREADS=OFF is given to CMake would look something like: 54*4d6fc14bSjoerg 55*4d6fc14bSjoerg.. code-block:: cpp 56*4d6fc14bSjoerg 57*4d6fc14bSjoerg //===----------------------------------------------------------------------===// 58*4d6fc14bSjoerg // 59*4d6fc14bSjoerg // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 60*4d6fc14bSjoerg // See https://llvm.org/LICENSE.txt for license information. 61*4d6fc14bSjoerg // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 62*4d6fc14bSjoerg // 63*4d6fc14bSjoerg //===----------------------------------------------------------------------===// 64*4d6fc14bSjoerg 65*4d6fc14bSjoerg #ifndef _LIBCPP_CONFIG_SITE 66*4d6fc14bSjoerg #define _LIBCPP_CONFIG_SITE 67*4d6fc14bSjoerg 68*4d6fc14bSjoerg /* #undef _LIBCPP_HAS_NO_GLOBAL_FILESYSTEM_NAMESPACE */ 69*4d6fc14bSjoerg /* #undef _LIBCPP_HAS_NO_STDIN */ 70*4d6fc14bSjoerg /* #undef _LIBCPP_HAS_NO_STDOUT */ 71*4d6fc14bSjoerg #define _LIBCPP_HAS_NO_THREADS 72*4d6fc14bSjoerg /* #undef _LIBCPP_HAS_NO_MONOTONIC_CLOCK */ 73*4d6fc14bSjoerg /* #undef _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS */ 74*4d6fc14bSjoerg 75*4d6fc14bSjoerg #endif 76*4d6fc14bSjoerg // -*- C++ -*- 77*4d6fc14bSjoerg //===--------------------------- __config ---------------------------------===// 78*4d6fc14bSjoerg // 79*4d6fc14bSjoerg // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 80*4d6fc14bSjoerg // See https://llvm.org/LICENSE.txt for license information. 81*4d6fc14bSjoerg // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 82*4d6fc14bSjoerg // 83*4d6fc14bSjoerg //===----------------------------------------------------------------------===// 84*4d6fc14bSjoerg 85*4d6fc14bSjoerg #ifndef _LIBCPP_CONFIG 86*4d6fc14bSjoerg #define _LIBCPP_CONFIG 87