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