248 lines · plain
1.. _index:2 3=============================4"libc++" C++ Standard Library5=============================6 7Overview8========9 10libc++ is a new implementation of the C++ standard library, targeting C++11 and11above.12 13* Features and Goals14 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 features20 such as exception objects, rtti and memory allocation.21 * Extensive unit tests.22 23* Design and Implementation:24 25 * Extensive unit tests26 * Internal linker model can be dumped/read to textual format27 * Additional linking features can be plugged in as "passes"28 * OS specific and CPU specific code factored out29 30 31Getting Started with libc++32===========================33 34.. toctree::35 :maxdepth: 136 37 ReleaseNotes38 UserDocumentation39 VendorDocumentation40 ABIGuarantees41 Contributing42 CodingGuidelines43 TestingLibcxx44 ImplementationDefinedBehavior45 Modules46 Hardening47 ReleaseProcedure48 Status/Cxx1749 Status/Cxx2050 Status/Cxx2351 Status/Cxx2c52 Status/Format53 Status/Parallelism54 Status/PSTL55 56 57.. toctree::58 :hidden:59 60 AddingNewCIJobs61 FeatureTestMacroTable62 63 64Current Status65==============66 67libc++ has become the default C++ Standard Library implementation for many major platforms, including Apple's macOS,68iOS, watchOS, and tvOS, Google Search, the Android operating system, and FreeBSD. As a result, libc++ has an estimated69user base of over 1 billion daily active users.70 71Since its inception, libc++ has focused on delivering high performance, standards-conformance, and portability. It has72been extensively tested and optimized, making it robust and production ready. libc++ fully implements C++11 and C++14,73with C++17, C++20, C++23, and C++26 features being actively developed and making steady progress.74 75libc++ is continuously integrated and tested on a wide range of platforms and configurations, ensuring its reliability76and compatibility across various systems. The library's extensive test suite and rigorous quality assurance process have77made it a top choice for platform providers looking to offer their users a robust and efficient C++ Standard Library.78 79As an open-source project, libc++ benefits from a vibrant community of contributors who work together to improve the80library and add new features. This ongoing development and support ensure that libc++ remains at the forefront of81C++ standardization efforts and continues to meet the evolving needs of C++ developers worldwide.82 83 84History85-------86After its initial introduction, many people have asked "why start a new87library instead of contributing to an existing library?" (like Apache's88libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing89reasons, but some of the major ones are:90 91* From years of experience (including having implemented the standard92 library before), we've learned many things about implementing93 the standard containers which require ABI breakage and fundamental changes94 to how they are implemented. For example, it is generally accepted that95 building std::string using the "short string optimization" instead of96 using Copy On Write (COW) is a superior approach for multicore97 machines (particularly in C++11, which has rvalue references). Breaking98 ABI compatibility with old versions of the library was99 determined to be critical to achieving the performance goals of100 libc++.101 102* Mainline libstdc++ has switched to GPL3, a license which the developers103 of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be104 independently extended to support C++11, but this would be a fork of the105 codebase (which is often seen as worse for a project than starting a new106 independent one). Another problem with libstdc++ is that it is tightly107 integrated with G++ development, tending to be tied fairly closely to the108 matching version of G++.109 110* STLport and the Apache libstdcxx library are two other popular111 candidates, but both lack C++11 support. Our experience (and the112 experience of libstdc++ developers) is that adding support for C++11 (in113 particular rvalue references and move-only types) requires changes to114 almost every class and function, essentially amounting to a rewrite.115 Faced with a rewrite, we decided to start from scratch and evaluate every116 design decision from first principles based on experience.117 Further, both projects are apparently abandoned: STLport 5.2.1 was118 released in Oct'08, and STDCXX 4.2.1 in May'08.119 120..121 LLVM RELEASE bump version122 123.. _SupportedPlatforms:124 125Platform and Compiler Support126=============================127 128Libc++ aims to support common compilers that implement the C++11 Standard. In order to strike a129good balance between stability for users and maintenance cost, testing coverage and development130velocity, libc++ drops support for older compilers as newer ones are released.131 132============ =================== ========================== =====================133Compiler Versions Restrictions Support policy134============ =================== ========================== =====================135Clang 20, 21, 22-git latest two stable releases per `LLVM's release page <https://releases.llvm.org>`_ and the development version136AppleClang 26.0 latest stable release per `Xcode's release page <https://developer.apple.com/documentation/xcode-release-notes>`_137Open XL 17.1.3 (AIX) latest stable release per `Open XL's documentation page <https://www.ibm.com/docs/en/openxl-c-and-cpp-aix>`_138GCC 15 In C++11 or later only latest stable release per `GCC's release page <https://gcc.gnu.org/releases.html>`_139============ =================== ========================== =====================140 141Libc++ also supports common platforms and architectures:142 143===================== ========================= ============================144Target platform Target architecture Notes145===================== ========================= ============================146macOS 10.13+ i386, x86_64, arm64147FreeBSD 12+ i386, x86_64, arm148Linux i386, x86_64, arm, arm64 Only glibc-2.24 and later and no other libc is officially supported149Android 5.0+ i386, x86_64, arm, arm64150Windows 7+ i386, x86_64, arm64 Both MSVC and MinGW style environments, ABI in MSVC environments is :doc:`unstable <DesignDocs/ABIVersioning>`151AIX 7.2TL5+ powerpc, powerpc64152Embedded (picolibc) arm153===================== ========================= ============================154 155Generally speaking, libc++ should work on any platform that provides a fairly complete156C Standard Library. It is also possible to turn off parts of the library for use on157systems that provide incomplete support.158 159However, libc++ aims to provide a high-quality implementation of the C++ Standard160Library, especially when it comes to correctness. As such, we aim to have test coverage161for all the platforms and compilers that we claim to support. If a platform or compiler162is not listed here, it is not officially supported. It may happen to work, and163in practice the library is known to work on some platforms not listed here, but164we don't make any guarantees. If you would like your compiler and/or platform165to be formally supported and listed here, please work with the libc++ team to set166up testing for your configuration.167 168 169C++ Standards Conformance170=========================171 172Libc++ provides full support for C++11 and C++14, and provides most of newer standards173with a few omissions. The conformance status of the library's tip is tracked in real-time174using `this page <https://github.com/orgs/llvm/projects/31>`_. The conformance status of175this release is described in the pages below:176 177* C++11 - Complete178* C++14 - Complete179* :ref:`C++17 - In Progress <cxx17-status>`180* :ref:`C++20 - In Progress <cxx20-status>`181* :ref:`C++23 - In Progress <cxx23-status>`182* :ref:`C++2c - In Progress <cxx2c-status>`183* :ref:`C++ Feature Test Macro Status <feature-status>`184 185 186Getting Involved187================188 189First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__190and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.191 192**Bug Reports**193 194If you think you've found a bug in libc++, please report it using the `LLVM bug tracker`_.195If you're not sure, you can ask for support on the `libc++ forum`_ or in the `libc++ chat`_.196 197**Patches**198 199If you want to contribute a patch to libc++, please start by reviewing our200:ref:`documentation about contributing <ContributingToLibcxx>`.201 202**Discussion and Questions**203 204Send discussions and questions to the `libc++ forum`_.205 206 207Design Documents208================209 210.. toctree::211 :maxdepth: 1212 213 DesignDocs/ABIVersioning214 DesignDocs/AtomicDesign215 DesignDocs/CapturingConfigInfo216 DesignDocs/ExperimentalFeatures217 DesignDocs/ExtendedCXX03Support218 DesignDocs/FeatureTestMacros219 DesignDocs/FileTimeType220 DesignDocs/HeaderRemovalPolicy221 DesignDocs/NoexceptPolicy222 DesignDocs/PSTLIntegration223 DesignDocs/ThreadingSupportAPI224 DesignDocs/UniquePtrTrivialAbi225 DesignDocs/UnspecifiedBehaviorRandomization226 DesignDocs/VisibilityMacros227 DesignDocs/TimeZone228 229 230Build Bots and Test Coverage231============================232 233* `Github Actions CI pipeline <https://github.com/llvm/llvm-project/actions/workflows/libcxx-build-and-test.yaml>`_234* `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_235* `LLVM Buildbot Builders <https://lab.llvm.org/buildbot>`_236* :ref:`Adding New CI Jobs <AddingNewCIJobs>`237 238 239Quick Links240===========241* `LLVM Homepage <https://llvm.org/>`_242* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_243* `LLVM Bug Tracker <https://github.com/llvm/llvm-project/labels/libc++/>`_244* `libcxx-commits Mailing List <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_245* `libc++ forum <https://discourse.llvm.org/c/runtimes/libcxx/>`_246* `libc++ chat <https://discord.com/channels/636084430946959380/636732894974312448>`_ (`invite link <https://discord.gg/xS7Z362>`_)247* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_248