diff options
Diffstat (limited to 'lib/libcxx/docs/DesignDocs')
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/ABIVersioning.rst | 17 | ||||
| -rw-r--r-- | lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst | 88 |
2 files changed, 105 insertions, 0 deletions
diff --git a/lib/libcxx/docs/DesignDocs/ABIVersioning.rst b/lib/libcxx/docs/DesignDocs/ABIVersioning.rst new file mode 100644 index 00000000000..5960dd18610 --- /dev/null +++ b/lib/libcxx/docs/DesignDocs/ABIVersioning.rst @@ -0,0 +1,17 @@ + +==================== +Libc++ ABI stability +==================== + +Libc++ aims to preserve stable ABI to avoid subtle bugs when code built to the old ABI +is linked with the code build to the new ABI. At the same time, libc++ allows ABI-breaking +improvements and bugfixes for the scenarios when ABI change is not a issue. + +To support both cases, libc++ allows specifying the ABI version at the +build time. The version is defined with a cmake option +LIBCXX_ABI_VERSION. Another option LIBCXX_ABI_UNSTABLE can be used to +include all present ABI breaking features. These options translate +into C++ macro definitions _LIBCPP_ABI_VERSION, _LIBCPP_ABI_UNSTABLE. + +Any ABI-changing feature is placed under it's own macro, _LIBCPP_ABI_XXX, which is enabled +based on the value of _LIBCPP_ABI_VERSION. _LIBCPP_ABI_UNSTABLE, if set, enables all features at once. diff --git a/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst b/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst new file mode 100644 index 00000000000..73378a21c0a --- /dev/null +++ b/lib/libcxx/docs/DesignDocs/CapturingConfigInfo.rst @@ -0,0 +1,88 @@ +======================================================= +Capturing configuration information during installation +======================================================= + +.. contents:: + :local: + +The Problem +=========== + +Currently the libc++ supports building the library with a number of different +configuration options. Unfortunately all of that configuration information is +lost when libc++ is installed. In order to support "persistent" +configurations libc++ needs a mechanism to capture the configuration options +in the INSTALLED headers. + + +Design Goals +============ + +* The solution should not INSTALL any additional headers. We don't want an extra + #include slowing everybody down. + +* The solution should not unduly affect libc++ developers. The problem is limited + to installed versions of libc++ and the solution should be as well. + +* The solution should not modify any existing headers EXCEPT during installation. + It makes developers lives harder if they have to regenerate the libc++ headers + every time they are modified. + +* The solution should not make any of the libc++ headers dependant on + files generated by the build system. The headers should be able to compile + out of the box without any modification. + +* The solution should not have ANY effect on users who don't need special + configuration options. The vast majority of users will never need this so it + shouldn't cost them. + + +The Solution +============ + +When you first configure libc++ using CMake we check to see if we need to +capture any options. If we haven't been given any "persistent" options then +we do NOTHING. + +Otherwise we create a custom installation rule that modifies the installed __config +header. The rule first generates a dummy "__config_site" header containing the required +#defines. The contents of the dummy header are then prependend to the installed +__config header. By manually prepending the files we avoid the cost of an +extra #include and we allow the __config header to be ignorant of the extra +configuration all together. An example "__config" header generated when +-DLIBCXX_ENABLE_THREADS=OFF is given to CMake would look something like: + +.. code-block:: cpp + + //===----------------------------------------------------------------------===// + // + // The LLVM Compiler Infrastructure + // + // This file is dual licensed under the MIT and the University of Illinois Open + // Source Licenses. See LICENSE.TXT for details. + // + //===----------------------------------------------------------------------===// + + #ifndef _LIBCPP_CONFIG_SITE + #define _LIBCPP_CONFIG_SITE + + /* #undef _LIBCPP_HAS_NO_GLOBAL_FILESYSTEM_NAMESPACE */ + /* #undef _LIBCPP_HAS_NO_STDIN */ + /* #undef _LIBCPP_HAS_NO_STDOUT */ + #define _LIBCPP_HAS_NO_THREADS + /* #undef _LIBCPP_HAS_NO_MONOTONIC_CLOCK */ + /* #undef _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS */ + + #endif + // -*- C++ -*- + //===--------------------------- __config ---------------------------------===// + // + // The LLVM Compiler Infrastructure + // + // This file is dual licensed under the MIT and the University of Illinois Open + // Source Licenses. See LICENSE.TXT for details. + // + //===----------------------------------------------------------------------===// + + #ifndef _LIBCPP_CONFIG + #define _LIBCPP_CONFIG |