blob: 7e5cb089ba8e15aec5c7fe713c890f69ac631bb2 [file] [log] [blame]
Eric Fiselierd720d1f2015-08-22 19:40:49 +00001.. _index:
2
3=============================
4"libc++" C++ Standard Library
5=============================
6
7Overview
8========
9
Mehdi Amini032f15a2017-01-25 17:00:30 +000010libc++ is a new implementation of the C++ standard library, targeting C++11 and
11above.
Eric Fiselierd720d1f2015-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
Louis Dionne743b1c02018-09-06 15:05:43 +000037 ReleaseNotes
Eric Fiselierd720d1f2015-08-22 19:40:49 +000038 UsingLibcxx
39 BuildingLibcxx
40 TestingLibcxx
Marek Kurdejd5bc4d92020-12-02 08:52:35 +010041 Contributing
Marek Kurdej906116e2020-11-26 09:03:50 +010042 Cxx1yStatus
43 Cxx1zStatus
44 Cxx2aStatus
Marek Kurdej176140d2020-12-03 09:17:14 +010045 Cxx2bStatus
Zoe Carvera720e2c2021-04-13 17:56:55 -070046 RangesStatus
Mark de Weverfffa08e2021-04-17 18:49:37 +020047 FormatStatus
Eric Fiselierd720d1f2015-08-22 19:40:49 +000048
Eric Fiseliera28db902015-09-05 05:29:23 +000049
Eric Fiselier4e860492019-01-16 01:37:43 +000050.. toctree::
51 :hidden:
52
Louis Dionnef34ac042020-11-19 14:22:28 -050053 AddingNewCIJobs
Eric Fiselier4e860492019-01-16 01:37:43 +000054 FeatureTestMacroTable
55
Louis Dionnef34ac042020-11-19 14:22:28 -050056
Eric Fiselierd720d1f2015-08-22 19:40:49 +000057Current Status
58--------------
59
60After its initial introduction, many people have asked "why start a new
61library instead of contributing to an existing library?" (like Apache's
62libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing
63reasons, but some of the major ones are:
64
Eric Fiselier98596ba2015-09-05 06:50:03 +000065* From years of experience (including having implemented the standard
66 library before), we've learned many things about implementing
67 the standard containers which require ABI breakage and fundamental changes
68 to how they are implemented. For example, it is generally accepted that
69 building std::string using the "short string optimization" instead of
70 using Copy On Write (COW) is a superior approach for multicore
71 machines (particularly in C++11, which has rvalue references). Breaking
72 ABI compatibility with old versions of the library was
73 determined to be critical to achieving the performance goals of
74 libc++.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000075
Eric Fiselier98596ba2015-09-05 06:50:03 +000076* Mainline libstdc++ has switched to GPL3, a license which the developers
77 of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be
78 independently extended to support C++11, but this would be a fork of the
79 codebase (which is often seen as worse for a project than starting a new
80 independent one). Another problem with libstdc++ is that it is tightly
81 integrated with G++ development, tending to be tied fairly closely to the
82 matching version of G++.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000083
Eric Fiselier98596ba2015-09-05 06:50:03 +000084* STLport and the Apache libstdcxx library are two other popular
85 candidates, but both lack C++11 support. Our experience (and the
86 experience of libstdc++ developers) is that adding support for C++11 (in
87 particular rvalue references and move-only types) requires changes to
88 almost every class and function, essentially amounting to a rewrite.
89 Faced with a rewrite, we decided to start from scratch and evaluate every
90 design decision from first principles based on experience.
91 Further, both projects are apparently abandoned: STLport 5.2.1 was
92 released in Oct'08, and STDCXX 4.2.1 in May'08.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000093
94Platform and Compiler Support
95-----------------------------
96
Louis Dionne678dc852020-02-12 17:01:19 +010097For using the libc++ headers
98############################
99The libc++ headers are known to work on the following platforms, using GCC and
100Clang. Note that functionality provided by ``<atomic>`` is only functional with
101Clang and GCC.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000102
Louis Dionne678dc852020-02-12 17:01:19 +0100103============ ==================== ============
104OS Arch Compilers
105============ ==================== ============
106macOS 10.9+ i386, x86_64 Clang, GCC
107FreeBSD 10+ i386, x86_64, ARM Clang, GCC
108Linux i386, x86_64 Clang, GCC
109============ ==================== ============
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000110
Louis Dionne678dc852020-02-12 17:01:19 +0100111The following minimum compiler versions are required:
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000112
Louis Dionne60481d62020-03-23 11:37:40 -0400113* Clang 4.0 and above
Eric Fiselier75c05562019-06-13 00:37:25 +0000114* GCC 5.0 and above.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000115
Louis Dionne678dc852020-02-12 17:01:19 +0100116The C++03 dialect is only supported with Clang.
117
118For building the libc++ library
119###############################
120Building the libc++ library (static or shared) requires some features from
121the operating system. As such, it has its own set of (slightly different)
122system requirements.
123
124============ ==================== ============ ========================
125OS Arch Compilers ABI Library
126============ ==================== ============ ========================
127macOS 10.12+ i386, x86_64 Clang, GCC libc++abi
128FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi
129Linux i386, x86_64 Clang, GCC libc++abi
130============ ==================== ============ ========================
131
132The following minimum compiler versions are required:
133
134* Clang 4.0 and above
135* GCC 5.0 and above.
136
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000137
138C++ Dialect Support
139---------------------
140
141* C++11 - Complete
Marek Kurdej906116e2020-11-26 09:03:50 +0100142* :ref:`C++14 - Complete <cxx1y-status>`
143* :ref:`C++17 - In Progress <cxx1z-status>`
144* :ref:`C++20 - In Progress <cxx2a-status>`
Mark de Wever8b38f962021-01-22 19:03:14 +0100145* :ref:`C++2b - In Progress <cxx2b-status>`
Eric Fiselier4f9062a2015-09-06 23:09:54 +0000146* `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__
Eric Fiselier4e860492019-01-16 01:37:43 +0000147* :ref:`C++ Feature Test Macro Status <feature-status>`
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000148
149Notes and Known Issues
150----------------------
151
152This list contains known issues with libc++
153
154* Building libc++ with ``-fno-rtti`` is not supported. However
155 linking against it with ``-fno-rtti`` is supported.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000156
157
Eric Fiseliera72fd802015-09-06 23:22:02 +0000158A full list of currently open libc++ bugs can be `found here`__.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000159
Eric Fiselier5d604012017-02-17 08:37:03 +0000160.. __: 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 Fiselierd720d1f2015-08-22 19:40:49 +0000161
162Design Documents
163----------------
164
Eric Fiselier5cf9a822015-10-13 22:12:02 +0000165.. toctree::
166 :maxdepth: 1
167
Eric Fiselier1a1c74b2015-10-14 00:22:05 +0000168 DesignDocs/ABIVersioning
Louis Dionne0df08db2021-06-08 11:15:27 -0400169 DesignDocs/AtomicDesign
170 DesignDocs/CapturingConfigInfo
171 DesignDocs/DebugMode
Louis Dionne37677132019-06-11 14:48:40 +0000172 DesignDocs/ExperimentalFeatures
Eric Fiselierf9954532019-06-11 22:53:49 +0000173 DesignDocs/ExtendedCXX03Support
Louis Dionne0df08db2021-06-08 11:15:27 -0400174 DesignDocs/FeatureTestMacros
175 DesignDocs/FileTimeType
zoecarver08de8162021-02-05 11:24:38 -0800176 DesignDocs/NoexceptPolicy
Louis Dionne0df08db2021-06-08 11:15:27 -0400177 DesignDocs/ThreadingSupportAPI
178 DesignDocs/UniquePtrTrivialAbi
179 DesignDocs/VisibilityMacros
Eric Fiselier5cf9a822015-10-13 22:12:02 +0000180
Eric Fiselier44451cb2015-10-15 03:27:02 +0000181Build Bots and Test Coverage
182----------------------------
Eric Fiselier98596ba2015-09-05 06:50:03 +0000183
Louis Dionnef34ac042020-11-19 14:22:28 -0500184* `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_
185* `LLVM Buildbot Builders <http://lab.llvm.org:8011>`_
186* :ref:`Adding New CI Jobs <AddingNewCIJobs>`
Eric Fiselier98596ba2015-09-05 06:50:03 +0000187
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000188Getting Involved
189================
190
Sylvestre Ledrub09c9382020-03-22 22:42:03 +0100191First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
192and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000193
194**Bug Reports**
195
196If you think you've found a bug in libc++, please report it using
Eric Fiselier98596ba2015-09-05 06:50:03 +0000197the `LLVM Bugzilla`_. If you're not sure, you
Eric Fiselierfa90b7f2018-09-22 19:49:29 +0000198can post a message to the `libcxx-dev mailing list`_ or on IRC.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000199
200**Patches**
201
202If you want to contribute a patch to libc++, the best place for that is
Sylvestre Ledrub09c9382020-03-22 22:42:03 +0100203`Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber.
Eric Fiselierfa90b7f2018-09-22 19:49:29 +0000204Also make sure you are subscribed to the `libcxx-commits mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000205
206**Discussion and Questions**
207
Eric Fiselier4f9062a2015-09-06 23:09:54 +0000208Send discussions and questions to the
Eric Fiselierfa90b7f2018-09-22 19:49:29 +0000209`libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000210
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000211
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000212
Eric Fiselier98596ba2015-09-05 06:50:03 +0000213Quick Links
214===========
Sylvestre Ledrub09c9382020-03-22 22:42:03 +0100215* `LLVM Homepage <https://llvm.org/>`_
Eric Fiselier4f9062a2015-09-06 23:09:54 +0000216* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
Eric Fiselier5d604012017-02-17 08:37:03 +0000217* `LLVM Bugzilla <https://bugs.llvm.org/>`_
Eric Fiselierfa90b7f2018-09-22 19:49:29 +0000218* `libcxx-commits Mailing List`_
219* `libcxx-dev Mailing List`_
xgupta482d5872021-02-01 12:54:21 +0530220* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_