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