blob: 20838a5177bd1489275fe7895c29b72bbd94decf [file] [log] [blame]
Eric Fiselierb9f425a2015-08-22 19:40:49 +00001.. _index:
2
3=============================
4"libc++" C++ Standard Library
5=============================
6
7Overview
8========
9
Mehdi Amini8a032c52017-01-25 17:00:30 +000010libc++ is a new implementation of the C++ standard library, targeting C++11 and
11above.
Eric Fiselierb9f425a2015-08-22 19:40:49 +000012
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 UsingLibcxx
38 BuildingLibcxx
39 TestingLibcxx
40
Eric Fiselierbf54da72015-09-05 05:29:23 +000041
Eric Fiselierb9f425a2015-08-22 19:40:49 +000042Current Status
43--------------
44
45After its initial introduction, many people have asked "why start a new
46library instead of contributing to an existing library?" (like Apache's
47libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing
48reasons, but some of the major ones are:
49
Eric Fiselier1aa96e82015-09-05 06:50:03 +000050* 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++.
Eric Fiselierb9f425a2015-08-22 19:40:49 +000060
Eric Fiselier1aa96e82015-09-05 06:50:03 +000061* 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++.
Eric Fiselierb9f425a2015-08-22 19:40:49 +000068
Eric Fiselier1aa96e82015-09-05 06:50:03 +000069* 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.
Eric Fiselierb9f425a2015-08-22 19:40:49 +000078
79Platform and Compiler Support
80-----------------------------
81
82libc++ is known to work on the following platforms, using gcc-4.2 and
83clang (lack of C++11 language support disables some functionality).
84Note that functionality provided by ``<atomic>`` is only functional with clang
85and GCC.
86
87============ ==================== ============ ========================
88OS Arch Compilers ABI Library
89============ ==================== ============ ========================
90Mac OS X i386, x86_64 Clang, GCC libc++abi
91FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi
92Linux i386, x86_64 Clang, GCC libc++abi
93============ ==================== ============ ========================
94
95The following minimum compiler versions are strongly recommended.
96
97* Clang 3.5 and above
98* GCC 4.7 and above.
99
100Anything older *may* work.
101
102C++ Dialect Support
103---------------------
104
105* C++11 - Complete
Eric Fiselier7ec94be2015-09-06 23:09:54 +0000106* `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>`__
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000109
110Notes and Known Issues
111----------------------
112
113This 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
Eric Fiselier5d514c02015-09-06 23:22:02 +0000121A full list of currently open libc++ bugs can be `found here`__.
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000122
Eric Fiselier5d514c02015-09-06 23:22:02 +0000123.. __: 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
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000124
125Design Documents
126----------------
127
Eric Fiselier73ffc782015-10-13 22:12:02 +0000128.. toctree::
129 :maxdepth: 1
130
Eric Fiselier01eb99a2016-12-28 04:58:52 +0000131 DesignDocs/DebugMode
Eric Fiselier73ffc782015-10-13 22:12:02 +0000132 DesignDocs/CapturingConfigInfo
Eric Fiseliera6622792015-10-14 00:22:05 +0000133 DesignDocs/ABIVersioning
Eric Fiselier833d6442016-09-15 22:27:07 +0000134 DesignDocs/VisibilityMacros
Eric Fiselier66134e82017-01-06 20:05:40 +0000135 DesignDocs/ThreadingSupportAPI
Eric Fiselier73ffc782015-10-13 22:12:02 +0000136
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000137* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
138* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_
Eric Fiselier7ec94be2015-09-06 23:09:54 +0000139* `Notes by Marshall Clow`__
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000140
Eric Fiselier7ec94be2015-09-06 23:09:54 +0000141.. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000142
Eric Fiselierb9aebae2015-10-15 03:27:02 +0000143Build Bots and Test Coverage
144----------------------------
Eric Fiselier1aa96e82015-09-05 06:50:03 +0000145
146* `LLVM Buildbot Builders <http://lab.llvm.org:8011/console>`_
147* `Apple Jenkins Builders <http://lab.llvm.org:8080/green/view/Libcxx/>`_
Eric Fiselierb9aebae2015-10-15 03:27:02 +0000148* `EricWF's Nightly Builders <http://ds2.efcs.ca:8080/console>`_
149* `Code Coverage Results <http://efcs.ca/libcxx-coverage>`_
Eric Fiselier1aa96e82015-09-05 06:50:03 +0000150
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000151Getting Involved
152================
153
Eric Fiselier1aa96e82015-09-05 06:50:03 +0000154First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__
155and `Getting started with LLVM <http://llvm.org/docs/GettingStarted.html>`__.
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000156
157**Bug Reports**
158
159If you think you've found a bug in libc++, please report it using
Eric Fiselier1aa96e82015-09-05 06:50:03 +0000160the `LLVM Bugzilla`_. If you're not sure, you
Eric Fiselier7ec94be2015-09-06 23:09:54 +0000161can post a message to the `cfe-dev mailing list`_ or on IRC.
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000162Please include "libc++" in your subject.
163
164**Patches**
165
166If you want to contribute a patch to libc++, the best place for that is
Eric Fiselier7ec94be2015-09-06 23:09:54 +0000167`Phabricator <http://llvm.org/docs/Phabricator.html>`_. Please include [libcxx] in the subject and
Eric Fiselier1aa96e82015-09-05 06:50:03 +0000168add `cfe-commits` as a subscriber. Also make sure you are subscribed to the
Eric Fiselier7ec94be2015-09-06 23:09:54 +0000169`cfe-commits mailing list <http://lists.llvm.org/mailman/listinfo/cfe-commits>`_.
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000170
171**Discussion and Questions**
172
Eric Fiselier7ec94be2015-09-06 23:09:54 +0000173Send discussions and questions to the
174`cfe-dev mailing list <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000175Please include [libcxx] in the subject.
176
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000177
Eric Fiselierb9f425a2015-08-22 19:40:49 +0000178
Eric Fiselier1aa96e82015-09-05 06:50:03 +0000179Quick Links
180===========
Eric Fiselier7ec94be2015-09-06 23:09:54 +0000181* `LLVM Homepage <http://llvm.org/>`_
182* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
183* `LLVM Bugzilla <http://llvm.org/bugs/>`_
184* `cfe-commits Mailing List`_
185* `cfe-dev Mailing List`_
Eric Fiselier1aa96e82015-09-05 06:50:03 +0000186* `Browse libc++ -- SVN <http://llvm.org/svn/llvm-project/libcxx/trunk/>`_
187* `Browse libc++ -- ViewVC <http://llvm.org/viewvc/llvm-project/libcxx/trunk/>`_