1.. _index:
2
3=============================
4"libc++" C++ Standard Library
5=============================
6
7Overview
8========
9
10libc++ is a new implementation of the C++ standard library, targeting C++11 and
11above.
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
31Getting Started with libc++
32---------------------------
33
34.. toctree::
35   :maxdepth: 2
36
37   UsingLibcxx
38   BuildingLibcxx
39   TestingLibcxx
40
41
42Current 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
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
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
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
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
121A 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
125Design 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
143Build 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
151Getting Involved
152================
153
154First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__
155and `Getting started with LLVM <http://llvm.org/docs/GettingStarted.html>`__.
156
157**Bug Reports**
158
159If you think you've found a bug in libc++, please report it using
160the `LLVM Bugzilla`_. If you're not sure, you
161can post a message to the `cfe-dev mailing list`_ or on IRC.
162Please include "libc++" in your subject.
163
164**Patches**
165
166If 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
168add `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
173Send discussions and questions to the
174`cfe-dev mailing list <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
175Please include [libcxx] in the subject.
176
177
178
179Quick 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