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