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 97Platform and Compiler Support 98============================= 99 100Libc++ aims to support common compilers that implement the C++11 Standard. In order to strike a 101good balance between stability for users and maintenance cost, testing coverage and development 102velocity, libc++ drops support for older compilers as newer ones are released. 103 104============ =============== ========================== ===================== 105Compiler Versions Restrictions Support policy 106============ =============== ========================== ===================== 107Clang 13, 14 latest two stable releases per `LLVM's release page <https://releases.llvm.org>`_ 108AppleClang 13 latest stable release per `Xcode's release page <https://developer.apple.com/documentation/xcode-release-notes>`_ 109Open XL 17.1 (AIX) latest stable release per `Open XL's documentation page <https://www.ibm.com/docs/en/openxl-c-and-cpp-aix>`_ 110GCC 12 In C++11 or later only latest stable release per `GCC's release page <https://gcc.gnu.org/releases.html>`_ 111============ =============== ========================== ===================== 112 113Libc++ also supports common platforms and architectures: 114 115=============== ========================= ============================ 116Target platform Target architecture Notes 117=============== ========================= ============================ 118macOS 10.9+ i386, x86_64, arm64 Building the shared library itself requires targetting macOS 10.11+ 119FreeBSD 10+ i386, x86_64, arm 120Linux i386, x86_64, arm, arm64 121Windows i386, x86_64 Both MSVC and MinGW style environments 122AIX powerpc, powerpc64 123=============== ========================= ============================ 124 125Generally speaking, libc++ should work on any platform that provides a fairly complete 126C Standard Library. It is also possible to turn off parts of the library for use on 127systems that provide incomplete support. 128 129However, libc++ aims to provide a high-quality implementation of the C++ Standard 130Library, especially when it comes to correctness. As such, we aim to have test coverage 131for all the platforms and compilers that we claim to support. If a platform or compiler 132is not listed here, it is not officially supported. It may happen to work, and 133in practice the library is known to work on some platforms not listed here, but 134we don't make any guarantees. If you would like your compiler and/or platform 135to be formally supported and listed here, please work with the libc++ team to set 136up testing for your configuration. 137 138 139C++ Dialect Support 140=================== 141 142* C++11 - Complete 143* :ref:`C++14 - Complete <cxx14-status>` 144* :ref:`C++17 - In Progress <cxx17-status>` 145* :ref:`C++20 - In Progress <cxx20-status>` 146* :ref:`C++2b - In Progress <cxx2b-status>` 147* :ref:`C++ Feature Test Macro Status <feature-status>` 148 149 150Notes and Known Issues 151====================== 152 153This list contains known issues with libc++ 154 155* Building libc++ with ``-fno-rtti`` is not supported. However 156 linking against it with ``-fno-rtti`` is supported. 157 158 159A full list of currently open libc++ bugs can be `found here`__. 160 161.. __: https://github.com/llvm/llvm-project/labels/libc%2B%2B 162 163 164Design Documents 165================ 166 167.. toctree:: 168 :maxdepth: 1 169 170 DesignDocs/ABIVersioning 171 DesignDocs/AtomicDesign 172 DesignDocs/CapturingConfigInfo 173 DesignDocs/DebugMode 174 DesignDocs/ExperimentalFeatures 175 DesignDocs/ExtendedCXX03Support 176 DesignDocs/FeatureTestMacros 177 DesignDocs/FileTimeType 178 DesignDocs/NoexceptPolicy 179 DesignDocs/ThreadingSupportAPI 180 DesignDocs/UniquePtrTrivialAbi 181 DesignDocs/UnspecifiedBehaviorRandomization 182 DesignDocs/VisibilityMacros 183 184 185Build Bots and Test Coverage 186============================ 187 188* `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_ 189* `LLVM Buildbot Builders <http://lab.llvm.org:8011>`_ 190* :ref:`Adding New CI Jobs <AddingNewCIJobs>` 191 192 193Getting Involved 194================ 195 196First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__ 197and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__. 198 199**Bug Reports** 200 201If you think you've found a bug in libc++, please report it using 202the `LLVM bug tracker`_. If you're not sure, you 203can ask for support on the `libcxx forum`_ or on IRC. 204 205**Patches** 206 207If you want to contribute a patch to libc++, the best place for that is 208`Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber. 209Also make sure you are subscribed to the `libcxx-commits mailing list`_. 210 211**Discussion and Questions** 212 213Send discussions and questions to the `libcxx forum`_. 214 215 216Quick Links 217=========== 218* `LLVM Homepage <https://llvm.org/>`_ 219* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ 220* `LLVM Bug Tracker <https://github.com/llvm/llvm-project/labels/libc++/>`_ 221* `libcxx-commits Mailing List <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_ 222* `libcxx Forum <https://discourse.llvm.org/c/runtimes/libcxx/>`_ 223* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_ 224