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