Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 1 | .. _index: |
| 2 | |
| 3 | ============================= |
| 4 | "libc++" C++ Standard Library |
| 5 | ============================= |
| 6 | |
| 7 | Overview |
| 8 | ======== |
| 9 | |
Mehdi Amini | 8a032c5 | 2017-01-25 17:00:30 +0000 | [diff] [blame] | 10 | libc++ is a new implementation of the C++ standard library, targeting C++11 and |
| 11 | above. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
Louis Dionne | 6969dc1 | 2018-09-06 15:05:43 +0000 | [diff] [blame] | 37 | ReleaseNotes |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 38 | UsingLibcxx |
| 39 | BuildingLibcxx |
| 40 | TestingLibcxx |
| 41 | |
Eric Fiselier | bf54da7 | 2015-09-05 05:29:23 +0000 | [diff] [blame] | 42 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 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++. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 61 | |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 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++. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 69 | |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 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. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 79 | |
| 80 | Platform and Compiler Support |
| 81 | ----------------------------- |
| 82 | |
Sylvestre Ledru | ac2b570 | 2018-09-20 07:57:31 +0000 | [diff] [blame] | 83 | libc++ is known to work on the following platforms, using gcc and |
| 84 | clang. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 |
Eric Fiselier | 7ec94be | 2015-09-06 23:09:54 +0000 | [diff] [blame] | 107 | * `C++14 - Complete <http://libcxx.llvm.org/cxx1y_status.html>`__ |
Sylvestre Ledru | ac2b570 | 2018-09-20 07:57:31 +0000 | [diff] [blame] | 108 | * `C++17 - In Progress <http://libcxx.llvm.org/cxx1z_status.html>`__ |
Eric Fiselier | 7ec94be | 2015-09-06 23:09:54 +0000 | [diff] [blame] | 109 | * `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__ |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | 5d514c0 | 2015-09-06 23:22:02 +0000 | [diff] [blame] | 122 | A full list of currently open libc++ bugs can be `found here`__. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 123 | |
Eric Fiselier | b7fd0be | 2017-02-17 08:37:03 +0000 | [diff] [blame] | 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 |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 125 | |
| 126 | Design Documents |
| 127 | ---------------- |
| 128 | |
Eric Fiselier | 73ffc78 | 2015-10-13 22:12:02 +0000 | [diff] [blame] | 129 | .. toctree:: |
| 130 | :maxdepth: 1 |
| 131 | |
Mehdi Amini | 907c119 | 2017-05-04 17:08:54 +0000 | [diff] [blame] | 132 | DesignDocs/AvailabilityMarkup |
Eric Fiselier | 01eb99a | 2016-12-28 04:58:52 +0000 | [diff] [blame] | 133 | DesignDocs/DebugMode |
Eric Fiselier | 73ffc78 | 2015-10-13 22:12:02 +0000 | [diff] [blame] | 134 | DesignDocs/CapturingConfigInfo |
Eric Fiselier | a662279 | 2015-10-14 00:22:05 +0000 | [diff] [blame] | 135 | DesignDocs/ABIVersioning |
Eric Fiselier | 833d644 | 2016-09-15 22:27:07 +0000 | [diff] [blame] | 136 | DesignDocs/VisibilityMacros |
Eric Fiselier | 66134e8 | 2017-01-06 20:05:40 +0000 | [diff] [blame] | 137 | DesignDocs/ThreadingSupportAPI |
Eric Fiselier | 88dfb6d | 2018-07-25 02:53:53 +0000 | [diff] [blame] | 138 | DesignDocs/FileTimeType |
Eric Fiselier | 73ffc78 | 2015-10-13 22:12:02 +0000 | [diff] [blame] | 139 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 140 | * `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_ |
| 141 | * `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_ |
Eric Fiselier | 7ec94be | 2015-09-06 23:09:54 +0000 | [diff] [blame] | 142 | * `Notes by Marshall Clow`__ |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 143 | |
Eric Fiselier | 7ec94be | 2015-09-06 23:09:54 +0000 | [diff] [blame] | 144 | .. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/ |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 145 | |
Eric Fiselier | b9aebae | 2015-10-15 03:27:02 +0000 | [diff] [blame] | 146 | Build Bots and Test Coverage |
| 147 | ---------------------------- |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 148 | |
| 149 | * `LLVM Buildbot Builders <http://lab.llvm.org:8011/console>`_ |
| 150 | * `Apple Jenkins Builders <http://lab.llvm.org:8080/green/view/Libcxx/>`_ |
Eric Fiselier | b857743 | 2017-05-04 07:40:23 +0000 | [diff] [blame] | 151 | * `Windows Appveyor Builders <https://ci.appveyor.com/project/llvm-mirror/libcxx>`_ |
Eric Fiselier | b9aebae | 2015-10-15 03:27:02 +0000 | [diff] [blame] | 152 | * `Code Coverage Results <http://efcs.ca/libcxx-coverage>`_ |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 153 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 154 | Getting Involved |
| 155 | ================ |
| 156 | |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 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>`__. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 159 | |
| 160 | **Bug Reports** |
| 161 | |
| 162 | If you think you've found a bug in libc++, please report it using |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 163 | the `LLVM Bugzilla`_. If you're not sure, you |
Eric Fiselier | 3cea452 | 2018-09-22 19:49:29 +0000 | [diff] [blame] | 164 | can post a message to the `libcxx-dev mailing list`_ or on IRC. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 165 | |
| 166 | **Patches** |
| 167 | |
| 168 | If you want to contribute a patch to libc++, the best place for that is |
Eric Fiselier | 3cea452 | 2018-09-22 19:49:29 +0000 | [diff] [blame] | 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>`_. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 171 | |
| 172 | **Discussion and Questions** |
| 173 | |
Eric Fiselier | 7ec94be | 2015-09-06 23:09:54 +0000 | [diff] [blame] | 174 | Send discussions and questions to the |
Eric Fiselier | 3cea452 | 2018-09-22 19:49:29 +0000 | [diff] [blame] | 175 | `libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 176 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 177 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 178 | |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 179 | Quick Links |
| 180 | =========== |
Eric Fiselier | 7ec94be | 2015-09-06 23:09:54 +0000 | [diff] [blame] | 181 | * `LLVM Homepage <http://llvm.org/>`_ |
| 182 | * `libc++abi Homepage <http://libcxxabi.llvm.org/>`_ |
Eric Fiselier | b7fd0be | 2017-02-17 08:37:03 +0000 | [diff] [blame] | 183 | * `LLVM Bugzilla <https://bugs.llvm.org/>`_ |
Eric Fiselier | 3cea452 | 2018-09-22 19:49:29 +0000 | [diff] [blame] | 184 | * `libcxx-commits Mailing List`_ |
| 185 | * `libcxx-dev Mailing List`_ |
Eric Fiselier | 1aa96e8 | 2015-09-05 06:50:03 +0000 | [diff] [blame] | 186 | * `Browse libc++ -- SVN <http://llvm.org/svn/llvm-project/libcxx/trunk/>`_ |
| 187 | * `Browse libc++ -- ViewVC <http://llvm.org/viewvc/llvm-project/libcxx/trunk/>`_ |