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   ReleaseNotes
38   UsingLibcxx
39   BuildingLibcxx
40   TestingLibcxx
41   Contributing
42   Cxx1yStatus
43   Cxx1zStatus
44   Cxx2aStatus
45   Cxx2bStatus
46
47
48.. toctree::
49    :hidden:
50
51    AddingNewCIJobs
52    FeatureTestMacroTable
53
54
55Current Status
56--------------
57
58After its initial introduction, many people have asked "why start a new
59library instead of contributing to an existing library?" (like Apache's
60libstdcxx, GNU's libstdc++, STLport, etc).  There are many contributing
61reasons, but some of the major ones are:
62
63* From years of experience (including having implemented the standard
64  library before), we've learned many things about implementing
65  the standard containers which require ABI breakage and fundamental changes
66  to how they are implemented.  For example, it is generally accepted that
67  building std::string using the "short string optimization" instead of
68  using Copy On Write (COW) is a superior approach for multicore
69  machines (particularly in C++11, which has rvalue references).  Breaking
70  ABI compatibility with old versions of the library was
71  determined to be critical to achieving the performance goals of
72  libc++.
73
74* Mainline libstdc++ has switched to GPL3, a license which the developers
75  of libc++ cannot use.  libstdc++ 4.2 (the last GPL2 version) could be
76  independently extended to support C++11, but this would be a fork of the
77  codebase (which is often seen as worse for a project than starting a new
78  independent one).  Another problem with libstdc++ is that it is tightly
79  integrated with G++ development, tending to be tied fairly closely to the
80  matching version of G++.
81
82* STLport and the Apache libstdcxx library are two other popular
83  candidates, but both lack C++11 support.  Our experience (and the
84  experience of libstdc++ developers) is that adding support for C++11 (in
85  particular rvalue references and move-only types) requires changes to
86  almost every class and function, essentially amounting to a rewrite.
87  Faced with a rewrite, we decided to start from scratch and evaluate every
88  design decision from first principles based on experience.
89  Further, both projects are apparently abandoned: STLport 5.2.1 was
90  released in Oct'08, and STDCXX 4.2.1 in May'08.
91
92Platform and Compiler Support
93-----------------------------
94
95For using the libc++ headers
96############################
97The libc++ headers are known to work on the following platforms, using GCC and
98Clang. Note that functionality provided by ``<atomic>`` is only functional with
99Clang and GCC.
100
101============ ==================== ============
102OS           Arch                 Compilers
103============ ==================== ============
104macOS 10.9+  i386, x86_64         Clang, GCC
105FreeBSD 10+  i386, x86_64, ARM    Clang, GCC
106Linux        i386, x86_64         Clang, GCC
107============ ==================== ============
108
109The following minimum compiler versions are required:
110
111* Clang 4.0 and above
112* GCC 5.0 and above.
113
114The C++03 dialect is only supported with Clang.
115
116For building the libc++ library
117###############################
118Building the libc++ library (static or shared) requires some features from
119the operating system. As such, it has its own set of (slightly different)
120system requirements.
121
122============ ==================== ============ ========================
123OS           Arch                 Compilers    ABI Library
124============ ==================== ============ ========================
125macOS 10.12+ i386, x86_64         Clang, GCC   libc++abi
126FreeBSD 10+  i386, x86_64, ARM    Clang, GCC   libcxxrt, libc++abi
127Linux        i386, x86_64         Clang, GCC   libc++abi
128============ ==================== ============ ========================
129
130The following minimum compiler versions are required:
131
132* Clang 4.0 and above
133* GCC 5.0 and above.
134
135
136C++ Dialect Support
137---------------------
138
139* C++11 - Complete
140* :ref:`C++14 - Complete <cxx1y-status>`
141* :ref:`C++17 - In Progress <cxx1z-status>`
142* :ref:`C++20 - In Progress <cxx2a-status>`
143* :ref:`C++2b - Not Started <cxx2b-status>`
144* `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__
145* :ref:`C++ Feature Test Macro Status <feature-status>`
146
147Notes and Known Issues
148----------------------
149
150This list contains known issues with libc++
151
152* Building libc++ with ``-fno-rtti`` is not supported. However
153  linking against it with ``-fno-rtti`` is supported.
154
155
156A full list of currently open libc++ bugs can be `found here`__.
157
158.. __:  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
159
160Design Documents
161----------------
162
163.. toctree::
164   :maxdepth: 1
165
166   DesignDocs/DebugMode
167   DesignDocs/CapturingConfigInfo
168   DesignDocs/ABIVersioning
169   DesignDocs/ExperimentalFeatures
170   DesignDocs/VisibilityMacros
171   DesignDocs/ThreadingSupportAPI
172   DesignDocs/FileTimeType
173   DesignDocs/FeatureTestMacros
174   DesignDocs/ExtendedCXX03Support
175   DesignDocs/UniquePtrTrivialAbi
176
177* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
178* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_
179* `Notes by Marshall Clow`__
180
181.. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/
182
183Build Bots and Test Coverage
184----------------------------
185
186* `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_
187* `LLVM Buildbot Builders <http://lab.llvm.org:8011>`_
188* :ref:`Adding New CI Jobs <AddingNewCIJobs>`
189
190Getting Involved
191================
192
193First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
194and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
195
196**Bug Reports**
197
198If you think you've found a bug in libc++, please report it using
199the `LLVM Bugzilla`_. If you're not sure, you
200can post a message to the `libcxx-dev mailing list`_ or on IRC.
201
202**Patches**
203
204If you want to contribute a patch to libc++, the best place for that is
205`Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber.
206Also make sure you are subscribed to the `libcxx-commits mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_.
207
208**Discussion and Questions**
209
210Send discussions and questions to the
211`libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_.
212
213
214
215Quick Links
216===========
217* `LLVM Homepage <https://llvm.org/>`_
218* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
219* `LLVM Bugzilla <https://bugs.llvm.org/>`_
220* `libcxx-commits Mailing List`_
221* `libcxx-dev Mailing List`_
222* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/master/libcxx/>`_
223