1.. _index: 2 3============================= 4"libc++" C++ Standard Library 5============================= 6 7Overview 8======== 9 10libc++ is a new implementation of the C++ standard library, targeting C++11 and 11above. 12 13* Features and Goals 14 15 * Correctness as defined by the C++11 standard. 16 * Fast execution. 17 * Minimal memory use. 18 * Fast compile times. 19 * ABI compatibility with gcc's libstdc++ for some low-level features 20 such as exception objects, rtti and memory allocation. 21 * Extensive unit tests. 22 23* Design and Implementation: 24 25 * Extensive unit tests 26 * Internal linker model can be dumped/read to textual format 27 * Additional linking features can be plugged in as "passes" 28 * OS specific and CPU specific code factored out 29 30 31Getting Started with libc++ 32=========================== 33 34.. toctree:: 35 :maxdepth: 1 36 37 ReleaseNotes 38 UsingLibcxx 39 BuildingLibcxx 40 TestingLibcxx 41 Contributing 42 Status/Cxx14 43 Status/Cxx17 44 Status/Cxx20 45 Status/Cxx2b 46 Status/Format 47 Status/Parallelism 48 Status/Ranges 49 Status/Spaceship 50 Status/Zip 51 52 53.. toctree:: 54 :hidden: 55 56 AddingNewCIJobs 57 FeatureTestMacroTable 58 59 60Current Status 61============== 62 63After its initial introduction, many people have asked "why start a new 64library instead of contributing to an existing library?" (like Apache's 65libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing 66reasons, but some of the major ones are: 67 68* From years of experience (including having implemented the standard 69 library before), we've learned many things about implementing 70 the standard containers which require ABI breakage and fundamental changes 71 to how they are implemented. For example, it is generally accepted that 72 building std::string using the "short string optimization" instead of 73 using Copy On Write (COW) is a superior approach for multicore 74 machines (particularly in C++11, which has rvalue references). Breaking 75 ABI compatibility with old versions of the library was 76 determined to be critical to achieving the performance goals of 77 libc++. 78 79* Mainline libstdc++ has switched to GPL3, a license which the developers 80 of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be 81 independently extended to support C++11, but this would be a fork of the 82 codebase (which is often seen as worse for a project than starting a new 83 independent one). Another problem with libstdc++ is that it is tightly 84 integrated with G++ development, tending to be tied fairly closely to the 85 matching version of G++. 86 87* STLport and the Apache libstdcxx library are two other popular 88 candidates, but both lack C++11 support. Our experience (and the 89 experience of libstdc++ developers) is that adding support for C++11 (in 90 particular rvalue references and move-only types) requires changes to 91 almost every class and function, essentially amounting to a rewrite. 92 Faced with a rewrite, we decided to start from scratch and evaluate every 93 design decision from first principles based on experience. 94 Further, both projects are apparently abandoned: STLport 5.2.1 was 95 released in Oct'08, and STDCXX 4.2.1 in May'08. 96 97.. _SupportedPlatforms: 98 99Platform and Compiler Support 100============================= 101 102Libc++ aims to support common compilers that implement the C++11 Standard. In order to strike a 103good balance between stability for users and maintenance cost, testing coverage and development 104velocity, libc++ drops support for older compilers as newer ones are released. 105 106============ =============== ========================== ===================== 107Compiler Versions Restrictions Support policy 108============ =============== ========================== ===================== 109Clang 15, 16, 17-git latest two stable releases per `LLVM's release page <https://releases.llvm.org>`_ and the development version 110AppleClang 14 latest stable release per `Xcode's release page <https://developer.apple.com/documentation/xcode-release-notes>`_ 111Open XL 17.1 (AIX) latest stable release per `Open XL's documentation page <https://www.ibm.com/docs/en/openxl-c-and-cpp-aix>`_ 112GCC 12 In C++11 or later only latest stable release per `GCC's release page <https://gcc.gnu.org/releases.html>`_ 113============ =============== ========================== ===================== 114 115Libc++ also supports common platforms and architectures: 116 117=============== ========================= ============================ 118Target platform Target architecture Notes 119=============== ========================= ============================ 120macOS 10.9+ i386, x86_64, arm64 Building the shared library itself requires targetting macOS 10.13+ 121FreeBSD 12+ i386, x86_64, arm 122Linux i386, x86_64, arm, arm64 Only glibc-2.24 and later and no other libc is officially supported 123Windows i386, x86_64 Both MSVC and MinGW style environments 124AIX 7.2TL5+ powerpc, powerpc64 125=============== ========================= ============================ 126 127Generally speaking, libc++ should work on any platform that provides a fairly complete 128C Standard Library. It is also possible to turn off parts of the library for use on 129systems that provide incomplete support. 130 131However, libc++ aims to provide a high-quality implementation of the C++ Standard 132Library, especially when it comes to correctness. As such, we aim to have test coverage 133for all the platforms and compilers that we claim to support. If a platform or compiler 134is not listed here, it is not officially supported. It may happen to work, and 135in practice the library is known to work on some platforms not listed here, but 136we don't make any guarantees. If you would like your compiler and/or platform 137to be formally supported and listed here, please work with the libc++ team to set 138up testing for your configuration. 139 140 141C++ Dialect Support 142=================== 143 144* C++11 - Complete 145* :ref:`C++14 - Complete <cxx14-status>` 146* :ref:`C++17 - In Progress <cxx17-status>` 147* :ref:`C++20 - In Progress <cxx20-status>` 148* :ref:`C++2b - In Progress <cxx2b-status>` 149* :ref:`C++ Feature Test Macro Status <feature-status>` 150 151 152Notes and Known Issues 153====================== 154 155This list contains known issues with libc++ 156 157* Building libc++ with ``-fno-rtti`` is not supported. However 158 linking against it with ``-fno-rtti`` is supported. 159 160 161A full list of currently open libc++ bugs can be `found here`__. 162 163.. __: https://github.com/llvm/llvm-project/labels/libc%2B%2B 164 165 166Design Documents 167================ 168 169.. toctree:: 170 :maxdepth: 1 171 172 DesignDocs/ABIVersioning 173 DesignDocs/AtomicDesign 174 DesignDocs/CapturingConfigInfo 175 DesignDocs/DebugMode 176 DesignDocs/ExperimentalFeatures 177 DesignDocs/ExtendedCXX03Support 178 DesignDocs/FeatureTestMacros 179 DesignDocs/FileTimeType 180 DesignDocs/HeaderRemovalPolicy 181 DesignDocs/NoexceptPolicy 182 DesignDocs/ThreadingSupportAPI 183 DesignDocs/UniquePtrTrivialAbi 184 DesignDocs/UnspecifiedBehaviorRandomization 185 DesignDocs/VisibilityMacros 186 187 188Build Bots and Test Coverage 189============================ 190 191* `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_ 192* `LLVM Buildbot Builders <https://lab.llvm.org/buildbot>`_ 193* :ref:`Adding New CI Jobs <AddingNewCIJobs>` 194 195 196Getting Involved 197================ 198 199First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__ 200and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__. 201 202**Bug Reports** 203 204If you think you've found a bug in libc++, please report it using 205the `LLVM bug tracker`_. If you're not sure, you 206can ask for support on the `libcxx forum`_ or on IRC. 207 208**Patches** 209 210If you want to contribute a patch to libc++, the best place for that is 211`Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber. 212Also make sure you are subscribed to the `libcxx-commits mailing list`_. 213 214**Discussion and Questions** 215 216Send discussions and questions to the `libcxx forum`_. 217 218 219Quick Links 220=========== 221* `LLVM Homepage <https://llvm.org/>`_ 222* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ 223* `LLVM Bug Tracker <https://github.com/llvm/llvm-project/labels/libc++/>`_ 224* `libcxx-commits Mailing List <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_ 225* `libcxx Forum <https://discourse.llvm.org/c/runtimes/libcxx/>`_ 226* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_ 227