1 ======================================================= 2 Capturing configuration information during installation 3 ======================================================= 4 5 .. contents:: 6 :local: 7 8 The Problem 9 =========== 10 11 Currently the libc++ supports building the library with a number of different 12 configuration options. Unfortunately all of that configuration information is 13 lost when libc++ is installed. In order to support "persistent" 14 configurations libc++ needs a mechanism to capture the configuration options 15 in the INSTALLED headers. 16 17 18 Design 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 dependant 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 40 The Solution 41 ============ 42 43 When you first configure libc++ using CMake we check to see if we need to 44 capture any options. If we haven't been given any "persistent" options then 45 we do NOTHING. 46 47 Otherwise we create a custom installation rule that modifies the installed __config 48 header. The rule first generates a dummy "__config_site" header containing the required 49 #defines. The contents of the dummy header are then prependend to the installed 50 __config header. By manually prepending the files we avoid the cost of an 51 extra #include and we allow the __config header to be ignorant of the extra 52 configuration 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
