1 .. _index: 2 3 ============================= 4 "libc++" C++ Standard Library 5 ============================= 6 7 Overview 8 ======== 9 10 libc++ is a new implementation of the C++ standard library, targeting C++11 and 11 above. 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 31 Getting Started with libc++ 32 --------------------------- 33 34 .. toctree:: 35 :maxdepth: 2 36 37 ReleaseNotes 38 UsingLibcxx 39 BuildingLibcxx 40 TestingLibcxx 41 Contributing 42 Cxx1yStatus 43 Cxx1zStatus 44 Cxx2aStatus 45 Cxx2bStatus 46 RangesStatus 47 FormatStatus 48 49 50 .. toctree:: 51 :hidden: 52 53 AddingNewCIJobs 54 FeatureTestMacroTable 55 56 57 Current Status 58 -------------- 59 60 After its initial introduction, many people have asked "why start a new 61 library instead of contributing to an existing library?" (like Apache's 62 libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing 63 reasons, 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 ----------------------------- 96 97 For using the libc++ headers 98 ############################ 99 The libc++ headers are known to work on the following platforms, using GCC and 100 Clang. Note that functionality provided by ``<atomic>`` is only functional with 101 Clang and GCC. 102 103 ============ ==================== ============ 104 OS Arch Compilers 105 ============ ==================== ============ 106 macOS 10.9+ i386, x86_64 Clang, GCC 107 FreeBSD 10+ i386, x86_64, ARM Clang, GCC 108 Linux i386, x86_64 Clang, GCC 109 ============ ==================== ============ 110 111 The following minimum compiler versions are required: 112 113 * Clang 4.0 and above 114 * GCC 5.0 and above. 115 116 The C++03 dialect is only supported with Clang. 117 118 For building the libc++ library 119 ############################### 120 Building the libc++ library (static or shared) requires some features from 121 the operating system. As such, it has its own set of (slightly different) 122 system requirements. 123 124 ============ ==================== ============ ======================== 125 OS Arch Compilers ABI Library 126 ============ ==================== ============ ======================== 127 macOS 10.12+ i386, x86_64 Clang, GCC libc++abi 128 FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi 129 Linux i386, x86_64 Clang, GCC libc++abi 130 ============ ==================== ============ ======================== 131 132 The following minimum compiler versions are required: 133 134 * Clang 4.0 and above 135 * GCC 5.0 and above. 136 137 138 C++ Dialect Support 139 --------------------- 140 141 * C++11 - Complete 142 * :ref:`C++14 - Complete <cxx1y-status>` 143 * :ref:`C++17 - In Progress <cxx1z-status>` 144 * :ref:`C++20 - In Progress <cxx2a-status>` 145 * :ref:`C++2b - In Progress <cxx2b-status>` 146 * `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__ 147 * :ref:`C++ Feature Test Macro Status <feature-status>` 148 149 Notes and Known Issues 150 ---------------------- 151 152 This list contains known issues with libc++ 153 154 * Building libc++ with ``-fno-rtti`` is not supported. However 155 linking against it with ``-fno-rtti`` is supported. 156 157 158 A full list of currently open libc++ bugs can be `found here`__. 159 160 .. __: 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 161 162 Design Documents 163 ---------------- 164 165 .. toctree:: 166 :maxdepth: 1 167 168 DesignDocs/DebugMode 169 DesignDocs/CapturingConfigInfo 170 DesignDocs/ABIVersioning 171 DesignDocs/ExperimentalFeatures 172 DesignDocs/VisibilityMacros 173 DesignDocs/ThreadingSupportAPI 174 DesignDocs/FileTimeType 175 DesignDocs/FeatureTestMacros 176 DesignDocs/ExtendedCXX03Support 177 DesignDocs/UniquePtrTrivialAbi 178 DesignDocs/NoexceptPolicy 179 180 * `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_ 181 * `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_ 182 * `Notes by Marshall Clow`__ 183 184 .. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/ 185 186 Build Bots and Test Coverage 187 ---------------------------- 188 189 * `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_ 190 * `LLVM Buildbot Builders <http://lab.llvm.org:8011>`_ 191 * :ref:`Adding New CI Jobs <AddingNewCIJobs>` 192 193 Getting Involved 194 ================ 195 196 First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__ 197 and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__. 198 199 **Bug Reports** 200 201 If you think you've found a bug in libc++, please report it using 202 the `LLVM Bugzilla`_. If you're not sure, you 203 can post a message to the `libcxx-dev mailing list`_ or on IRC. 204 205 **Patches** 206 207 If 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. 209 Also make sure you are subscribed to the `libcxx-commits mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_. 210 211 **Discussion and Questions** 212 213 Send discussions and questions to the 214 `libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_. 215 216 217 218 Quick Links 219 =========== 220 * `LLVM Homepage <https://llvm.org/>`_ 221 * `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ 222 * `LLVM Bugzilla <https://bugs.llvm.org/>`_ 223 * `libcxx-commits Mailing List`_ 224 * `libcxx-dev Mailing List`_ 225 * `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_ 226
Indexes created Tue Feb 24 01:34:59 UTC 2026