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: 2 36 37 ReleaseNotes 38 UsingLibcxx 39 BuildingLibcxx 40 TestingLibcxx 41 42 43.. toctree:: 44 :hidden: 45 46 FeatureTestMacroTable 47 48Current Status 49-------------- 50 51After its initial introduction, many people have asked "why start a new 52library instead of contributing to an existing library?" (like Apache's 53libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing 54reasons, but some of the major ones are: 55 56* From years of experience (including having implemented the standard 57 library before), we've learned many things about implementing 58 the standard containers which require ABI breakage and fundamental changes 59 to how they are implemented. For example, it is generally accepted that 60 building std::string using the "short string optimization" instead of 61 using Copy On Write (COW) is a superior approach for multicore 62 machines (particularly in C++11, which has rvalue references). Breaking 63 ABI compatibility with old versions of the library was 64 determined to be critical to achieving the performance goals of 65 libc++. 66 67* Mainline libstdc++ has switched to GPL3, a license which the developers 68 of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be 69 independently extended to support C++11, but this would be a fork of the 70 codebase (which is often seen as worse for a project than starting a new 71 independent one). Another problem with libstdc++ is that it is tightly 72 integrated with G++ development, tending to be tied fairly closely to the 73 matching version of G++. 74 75* STLport and the Apache libstdcxx library are two other popular 76 candidates, but both lack C++11 support. Our experience (and the 77 experience of libstdc++ developers) is that adding support for C++11 (in 78 particular rvalue references and move-only types) requires changes to 79 almost every class and function, essentially amounting to a rewrite. 80 Faced with a rewrite, we decided to start from scratch and evaluate every 81 design decision from first principles based on experience. 82 Further, both projects are apparently abandoned: STLport 5.2.1 was 83 released in Oct'08, and STDCXX 4.2.1 in May'08. 84 85Platform and Compiler Support 86----------------------------- 87 88For using the libc++ headers 89############################ 90The libc++ headers are known to work on the following platforms, using GCC and 91Clang. Note that functionality provided by ``<atomic>`` is only functional with 92Clang and GCC. 93 94============ ==================== ============ 95OS Arch Compilers 96============ ==================== ============ 97macOS 10.9+ i386, x86_64 Clang, GCC 98FreeBSD 10+ i386, x86_64, ARM Clang, GCC 99Linux i386, x86_64 Clang, GCC 100============ ==================== ============ 101 102The following minimum compiler versions are required: 103 104* Clang 4.0 and above 105* GCC 5.0 and above. 106 107The C++03 dialect is only supported with Clang. 108 109For building the libc++ library 110############################### 111Building the libc++ library (static or shared) requires some features from 112the operating system. As such, it has its own set of (slightly different) 113system requirements. 114 115============ ==================== ============ ======================== 116OS Arch Compilers ABI Library 117============ ==================== ============ ======================== 118macOS 10.12+ i386, x86_64 Clang, GCC libc++abi 119FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi 120Linux i386, x86_64 Clang, GCC libc++abi 121============ ==================== ============ ======================== 122 123The following minimum compiler versions are required: 124 125* Clang 4.0 and above 126* GCC 5.0 and above. 127 128 129C++ Dialect Support 130--------------------- 131 132* C++11 - Complete 133* `C++14 - Complete <http://libcxx.llvm.org/cxx1y_status.html>`__ 134* `C++17 - In Progress <http://libcxx.llvm.org/cxx1z_status.html>`__ 135* `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__ 136* :ref:`C++ Feature Test Macro Status <feature-status>` 137 138Notes and Known Issues 139---------------------- 140 141This list contains known issues with libc++ 142 143* Building libc++ with ``-fno-rtti`` is not supported. However 144 linking against it with ``-fno-rtti`` is supported. 145 146 147A full list of currently open libc++ bugs can be `found here`__. 148 149.. __: 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 150 151Design Documents 152---------------- 153 154.. toctree:: 155 :maxdepth: 1 156 157 DesignDocs/AvailabilityMarkup 158 DesignDocs/DebugMode 159 DesignDocs/CapturingConfigInfo 160 DesignDocs/ABIVersioning 161 DesignDocs/ExperimentalFeatures 162 DesignDocs/VisibilityMacros 163 DesignDocs/ThreadingSupportAPI 164 DesignDocs/FileTimeType 165 DesignDocs/FeatureTestMacros 166 DesignDocs/ExtendedCXX03Support 167 168* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_ 169* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_ 170* `Notes by Marshall Clow`__ 171 172.. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/ 173 174Build Bots and Test Coverage 175---------------------------- 176 177* `LLVM Buildbot Builders <http://lab.llvm.org:8011/console>`_ 178* `Apple Jenkins Builders <http://lab.llvm.org:8080/green/view/Libcxx/>`_ 179* `Windows Appveyor Builders <https://ci.appveyor.com/project/llvm-mirror/libcxx>`_ 180* `Code Coverage Results <http://efcs.ca/libcxx-coverage>`_ 181 182Getting Involved 183================ 184 185First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__ 186and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__. 187 188**Bug Reports** 189 190If you think you've found a bug in libc++, please report it using 191the `LLVM Bugzilla`_. If you're not sure, you 192can post a message to the `libcxx-dev mailing list`_ or on IRC. 193 194**Patches** 195 196If you want to contribute a patch to libc++, the best place for that is 197`Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber. 198Also make sure you are subscribed to the `libcxx-commits mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_. 199 200**Discussion and Questions** 201 202Send discussions and questions to the 203`libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_. 204 205 206 207Quick Links 208=========== 209* `LLVM Homepage <https://llvm.org/>`_ 210* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ 211* `LLVM Bugzilla <https://bugs.llvm.org/>`_ 212* `libcxx-commits Mailing List`_ 213* `libcxx-dev Mailing List`_ 214* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/master/libcxx/>`_ 215