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