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