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. 11 12 * Features and Goals 13 14 * Correctness as defined by the C++11 standard. 15 * Fast execution. 16 * Minimal memory use. 17 * Fast compile times. 18 * ABI compatibility with gcc's libstdc++ for some low-level features 19 such as exception objects, rtti and memory allocation. 20 * Extensive unit tests. 21 22 * Design and Implementation: 23 24 * Extensive unit tests 25 * Internal linker model can be dumped/read to textual format 26 * Additional linking features can be plugged in as "passes" 27 * OS specific and CPU specific code factored out 28 29 30 Getting Started with libc++ 31 --------------------------- 32 33 .. toctree:: 34 :maxdepth: 2 35 36 UsingLibcxx 37 BuildingLibcxx 38 TestingLibcxx 39 40 41 Current Status 42 -------------- 43 44 After its initial introduction, many people have asked "why start a new 45 library instead of contributing to an existing library?" (like Apache's 46 libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing 47 reasons, but some of the major ones are: 48 49 * From years of experience (including having implemented the standard 50 library before), we've learned many things about implementing 51 the standard containers which require ABI breakage and fundamental changes 52 to how they are implemented. For example, it is generally accepted that 53 building std::string using the "short string optimization" instead of 54 using Copy On Write (COW) is a superior approach for multicore 55 machines (particularly in C++11, which has rvalue references). Breaking 56 ABI compatibility with old versions of the library was 57 determined to be critical to achieving the performance goals of 58 libc++. 59 60 * Mainline libstdc++ has switched to GPL3, a license which the developers 61 of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be 62 independently extended to support C++11, but this would be a fork of the 63 codebase (which is often seen as worse for a project than starting a new 64 independent one). Another problem with libstdc++ is that it is tightly 65 integrated with G++ development, tending to be tied fairly closely to the 66 matching version of G++. 67 68 * STLport and the Apache libstdcxx library are two other popular 69 candidates, but both lack C++11 support. Our experience (and the 70 experience of libstdc++ developers) is that adding support for C++11 (in 71 particular rvalue references and move-only types) requires changes to 72 almost every class and function, essentially amounting to a rewrite. 73 Faced with a rewrite, we decided to start from scratch and evaluate every 74 design decision from first principles based on experience. 75 Further, both projects are apparently abandoned: STLport 5.2.1 was 76 released in Oct'08, and STDCXX 4.2.1 in May'08. 77 78 Platform and Compiler Support 79 ----------------------------- 80 81 libc++ is known to work on the following platforms, using gcc-4.2 and 82 clang (lack of C++11 language support disables some functionality). 83 Note that functionality provided by ``<atomic>`` is only functional with clang 84 and GCC. 85 86 ============ ==================== ============ ======================== 87 OS Arch Compilers ABI Library 88 ============ ==================== ============ ======================== 89 Mac OS X i386, x86_64 Clang, GCC libc++abi 90 FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi 91 Linux i386, x86_64 Clang, GCC libc++abi 92 ============ ==================== ============ ======================== 93 94 The following minimum compiler versions are strongly recommended. 95 96 * Clang 3.5 and above 97 * GCC 4.7 and above. 98 99 Anything older *may* work. 100 101 C++ Dialect Support 102 --------------------- 103 104 * C++11 - Complete 105 * `C++14 - Complete <http://libcxx.llvm.org/cxx1y_status.html>`__ 106 * `C++1z - In Progress <http://libcxx.llvm.org/cxx1z_status.html>`__ 107 * `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__ 108 109 Notes and Known Issues 110 ---------------------- 111 112 This list contains known issues with libc++ 113 114 * Building libc++ with ``-fno-rtti`` is not supported. However 115 linking against it with ``-fno-rtti`` is supported. 116 * On OS X v10.8 and older the CMake option ``-DLIBCXX_LIBCPPABI_VERSION=""`` 117 must be used during configuration. 118 119 120 A full list of currently open libc++ bugs can be `found here`__. 121 122 .. __: https://llvm.org/bugs/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 123 124 Design Documents 125 ---------------- 126 127 .. toctree:: 128 :maxdepth: 1 129 130 DesignDocs/CapturingConfigInfo 131 DesignDocs/ABIVersioning 132 133 134 * `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_ 135 * `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_ 136 * `Status of debug mode <http://libcxx.llvm.org/debug_mode.html>`_ 137 * `Notes by Marshall Clow`__ 138 139 .. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/ 140 141 Build Bots and Test Coverage 142 ---------------------------- 143 144 * `LLVM Buildbot Builders <http://lab.llvm.org:8011/console>`_ 145 * `Apple Jenkins Builders <http://lab.llvm.org:8080/green/view/Libcxx/>`_ 146 * `EricWF's Nightly Builders <http://ds2.efcs.ca:8080/console>`_ 147 * `Code Coverage Results <http://efcs.ca/libcxx-coverage>`_ 148 149 Getting Involved 150 ================ 151 152 First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__ 153 and `Getting started with LLVM <http://llvm.org/docs/GettingStarted.html>`__. 154 155 **Bug Reports** 156 157 If you think you've found a bug in libc++, please report it using 158 the `LLVM Bugzilla`_. If you're not sure, you 159 can post a message to the `cfe-dev mailing list`_ or on IRC. 160 Please include "libc++" in your subject. 161 162 **Patches** 163 164 If you want to contribute a patch to libc++, the best place for that is 165 `Phabricator <http://llvm.org/docs/Phabricator.html>`_. Please include [libcxx] in the subject and 166 add `cfe-commits` as a subscriber. Also make sure you are subscribed to the 167 `cfe-commits mailing list <http://lists.llvm.org/mailman/listinfo/cfe-commits>`_. 168 169 **Discussion and Questions** 170 171 Send discussions and questions to the 172 `cfe-dev mailing list <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_. 173 Please include [libcxx] in the subject. 174 175 176 177 Quick Links 178 =========== 179 * `LLVM Homepage <http://llvm.org/>`_ 180 * `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ 181 * `LLVM Bugzilla <http://llvm.org/bugs/>`_ 182 * `cfe-commits Mailing List`_ 183 * `cfe-dev Mailing List`_ 184 * `Browse libc++ -- SVN <http://llvm.org/svn/llvm-project/libcxx/trunk/>`_ 185 * `Browse libc++ -- ViewVC <http://llvm.org/viewvc/llvm-project/libcxx/trunk/>`_ 186
