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