blob: a150232e00b1de403f3a2bf1093c3c33fe806c8b [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++
Louis Dionnef5cd4c72021-07-06 15:47:29 -040032===========================
Eric Fiselierd720d1f2015-08-22 19:40:49 +000033
34.. toctree::
Louis Dionne4b1b70d2021-07-06 10:39:01 -040035 :maxdepth: 1
Eric Fiselierd720d1f2015-08-22 19:40:49 +000036
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
Louis Dionnee96350d2021-07-06 09:46:29 -040042 Status/Cxx14
43 Status/Cxx17
44 Status/Cxx20
45 Status/Cxx2b
Louis Dionnee96350d2021-07-06 09:46:29 -040046 Status/Format
Kent Ross3b4b6c92021-08-19 23:10:47 +000047 Status/Ranges
48 Status/Spaceship
Eric Fiselierd720d1f2015-08-22 19:40:49 +000049
Eric Fiseliera28db902015-09-05 05:29:23 +000050
Eric Fiselier4e860492019-01-16 01:37:43 +000051.. toctree::
52 :hidden:
53
Louis Dionnef34ac042020-11-19 14:22:28 -050054 AddingNewCIJobs
Eric Fiselier4e860492019-01-16 01:37:43 +000055 FeatureTestMacroTable
56
Louis Dionnef34ac042020-11-19 14:22:28 -050057
Eric Fiselierd720d1f2015-08-22 19:40:49 +000058Current Status
Louis Dionnef5cd4c72021-07-06 15:47:29 -040059==============
Eric Fiselierd720d1f2015-08-22 19:40:49 +000060
61After its initial introduction, many people have asked "why start a new
62library instead of contributing to an existing library?" (like Apache's
63libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing
64reasons, but some of the major ones are:
65
Eric Fiselier98596ba2015-09-05 06:50:03 +000066* From years of experience (including having implemented the standard
67 library before), we've learned many things about implementing
68 the standard containers which require ABI breakage and fundamental changes
69 to how they are implemented. For example, it is generally accepted that
70 building std::string using the "short string optimization" instead of
71 using Copy On Write (COW) is a superior approach for multicore
72 machines (particularly in C++11, which has rvalue references). Breaking
73 ABI compatibility with old versions of the library was
74 determined to be critical to achieving the performance goals of
75 libc++.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000076
Eric Fiselier98596ba2015-09-05 06:50:03 +000077* Mainline libstdc++ has switched to GPL3, a license which the developers
78 of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be
79 independently extended to support C++11, but this would be a fork of the
80 codebase (which is often seen as worse for a project than starting a new
81 independent one). Another problem with libstdc++ is that it is tightly
82 integrated with G++ development, tending to be tied fairly closely to the
83 matching version of G++.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000084
Eric Fiselier98596ba2015-09-05 06:50:03 +000085* STLport and the Apache libstdcxx library are two other popular
86 candidates, but both lack C++11 support. Our experience (and the
87 experience of libstdc++ developers) is that adding support for C++11 (in
88 particular rvalue references and move-only types) requires changes to
89 almost every class and function, essentially amounting to a rewrite.
90 Faced with a rewrite, we decided to start from scratch and evaluate every
91 design decision from first principles based on experience.
92 Further, both projects are apparently abandoned: STLport 5.2.1 was
93 released in Oct'08, and STDCXX 4.2.1 in May'08.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000094
Louis Dionnef5cd4c72021-07-06 15:47:29 -040095
Eric Fiselierd720d1f2015-08-22 19:40:49 +000096Platform and Compiler Support
Louis Dionnef5cd4c72021-07-06 15:47:29 -040097=============================
Eric Fiselierd720d1f2015-08-22 19:40:49 +000098
Louis Dionnef5cd4c72021-07-06 15:47:29 -040099Libc++ aims to support common compilers that implement the C++11 Standard. In order to strike a
100good balance between stability for users and maintenance cost, testing coverage and development
101velocity, libc++ drops support for older compilers as newer ones are released.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000102
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400103============ =============== ========================== =====================
104Compiler Versions Restrictions Support policy
105============ =============== ========================== =====================
Mark de Weverd5352992021-10-23 13:08:01 +0200106Clang 12, 13 latest two stable releases per `LLVM's release page <https://releases.llvm.org>`_
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400107AppleClang 12 latest stable release per `Xcode's release page <https://developer.apple.com/documentation/xcode-release-notes>`_
David Tenty77235932021-10-19 14:09:46 -0400108Open XL 17.1 (AIX) latest stable release per `Open XL's documentation page <https://www.ibm.com/docs/en/openxl-c-and-cpp-aix>`_
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400109GCC 11 In C++11 or later only latest stable release per `GCC's release page <https://gcc.gnu.org/releases.html>`_
110============ =============== ========================== =====================
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000111
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400112Libc++ also supports common platforms and architectures:
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000113
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400114=============== ========================= ============================
115Target platform Target architecture Notes
116=============== ========================= ============================
117macOS 10.9+ i386, x86_64, arm64 Building the shared library itself requires targetting macOS 10.11+
118FreeBSD 10+ i386, x86_64, arm
119Linux i386, x86_64, arm, arm64
120Windows x86_64
David Tenty77235932021-10-19 14:09:46 -0400121AIX powerpc, powerpc64
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400122=============== ========================= ============================
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000123
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400124Generally speaking, libc++ should work on any platform that provides a fairly complete
125C Standard Library. It is also possible to turn off parts of the library for use on
126systems that provide incomplete support.
Louis Dionne678dc852020-02-12 17:01:19 +0100127
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400128However, libc++ aims to provide a high-quality implementation of the C++ Standard
129Library, especially when it comes to correctness. As such, we aim to have test coverage
130for all the platforms and compilers that we claim to support. If a platform or compiler
Martin Storsjöe9747ef2021-07-13 14:24:51 +0300131is not listed here, it is not officially supported. It may happen to work, and
132in practice the library is known to work on some platforms not listed here, but
133we don't make any guarantees. If you would like your compiler and/or platform
Louis Dionne49696152021-08-17 10:52:12 -0400134to be formally supported and listed here, please work with the libc++ team to set
135up testing for your configuration.
Louis Dionne678dc852020-02-12 17:01:19 +0100136
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000137
138C++ Dialect Support
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400139===================
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000140
141* C++11 - Complete
Louis Dionnee96350d2021-07-06 09:46:29 -0400142* :ref:`C++14 - Complete <cxx14-status>`
143* :ref:`C++17 - In Progress <cxx17-status>`
144* :ref:`C++20 - In Progress <cxx20-status>`
Mark de Wever8b38f962021-01-22 19:03:14 +0100145* :ref:`C++2b - In Progress <cxx2b-status>`
Eric Fiselier4e860492019-01-16 01:37:43 +0000146* :ref:`C++ Feature Test Macro Status <feature-status>`
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000147
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400148
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000149Notes and Known Issues
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400150======================
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000151
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
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400162
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000163Design Documents
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400164================
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000165
Eric Fiselier5cf9a822015-10-13 22:12:02 +0000166.. toctree::
167 :maxdepth: 1
168
Eric Fiselier1a1c74b2015-10-14 00:22:05 +0000169 DesignDocs/ABIVersioning
Louis Dionne0df08db2021-06-08 11:15:27 -0400170 DesignDocs/AtomicDesign
171 DesignDocs/CapturingConfigInfo
172 DesignDocs/DebugMode
Louis Dionne37677132019-06-11 14:48:40 +0000173 DesignDocs/ExperimentalFeatures
Eric Fiselierf9954532019-06-11 22:53:49 +0000174 DesignDocs/ExtendedCXX03Support
Louis Dionne0df08db2021-06-08 11:15:27 -0400175 DesignDocs/FeatureTestMacros
176 DesignDocs/FileTimeType
zoecarver08de8162021-02-05 11:24:38 -0800177 DesignDocs/NoexceptPolicy
Louis Dionne0df08db2021-06-08 11:15:27 -0400178 DesignDocs/ThreadingSupportAPI
179 DesignDocs/UniquePtrTrivialAbi
Danila Kutenina9cbea12021-11-16 15:48:59 -0500180 DesignDocs/UnspecifiedBehaviorRandomization
Louis Dionne0df08db2021-06-08 11:15:27 -0400181 DesignDocs/VisibilityMacros
Eric Fiselier5cf9a822015-10-13 22:12:02 +0000182
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400183
Eric Fiselier44451cb2015-10-15 03:27:02 +0000184Build Bots and Test Coverage
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400185============================
Eric Fiselier98596ba2015-09-05 06:50:03 +0000186
Louis Dionnef34ac042020-11-19 14:22:28 -0500187* `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_
188* `LLVM Buildbot Builders <http://lab.llvm.org:8011>`_
189* :ref:`Adding New CI Jobs <AddingNewCIJobs>`
Eric Fiselier98596ba2015-09-05 06:50:03 +0000190
Louis Dionnef5cd4c72021-07-06 15:47:29 -0400191
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000192Getting Involved
193================
194
Sylvestre Ledrub09c9382020-03-22 22:42:03 +0100195First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
196and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000197
198**Bug Reports**
199
200If you think you've found a bug in libc++, please report it using
Eric Fiselier98596ba2015-09-05 06:50:03 +0000201the `LLVM Bugzilla`_. If you're not sure, you
Eric Fiselierfa90b7f2018-09-22 19:49:29 +0000202can post a message to the `libcxx-dev mailing list`_ or on IRC.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000203
204**Patches**
205
206If you want to contribute a patch to libc++, the best place for that is
Sylvestre Ledrub09c9382020-03-22 22:42:03 +0100207`Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber.
Eric Fiselierfa90b7f2018-09-22 19:49:29 +0000208Also 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 +0000209
210**Discussion and Questions**
211
Eric Fiselier4f9062a2015-09-06 23:09:54 +0000212Send discussions and questions to the
Eric Fiselierfa90b7f2018-09-22 19:49:29 +0000213`libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000214
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000215
Eric Fiselier98596ba2015-09-05 06:50:03 +0000216Quick Links
217===========
Sylvestre Ledrub09c9382020-03-22 22:42:03 +0100218* `LLVM Homepage <https://llvm.org/>`_
Eric Fiselier4f9062a2015-09-06 23:09:54 +0000219* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
Eric Fiselier5d604012017-02-17 08:37:03 +0000220* `LLVM Bugzilla <https://bugs.llvm.org/>`_
Eric Fiselierfa90b7f2018-09-22 19:49:29 +0000221* `libcxx-commits Mailing List`_
222* `libcxx-dev Mailing List`_
xgupta482d5872021-02-01 12:54:21 +0530223* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_