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
42
43Current Status
44--------------
45
46After its initial introduction, many people have asked "why start a new
47library instead of contributing to an existing library?" (like Apache's
48libstdcxx, GNU's libstdc++, STLport, etc).  There are many contributing
49reasons, but some of the major ones are:
50
51* From years of experience (including having implemented the standard
52  library before), we've learned many things about implementing
53  the standard containers which require ABI breakage and fundamental changes
54  to how they are implemented.  For example, it is generally accepted that
55  building std::string using the "short string optimization" instead of
56  using Copy On Write (COW) is a superior approach for multicore
57  machines (particularly in C++11, which has rvalue references).  Breaking
58  ABI compatibility with old versions of the library was
59  determined to be critical to achieving the performance goals of
60  libc++.
61
62* Mainline libstdc++ has switched to GPL3, a license which the developers
63  of libc++ cannot use.  libstdc++ 4.2 (the last GPL2 version) could be
64  independently extended to support C++11, but this would be a fork of the
65  codebase (which is often seen as worse for a project than starting a new
66  independent one).  Another problem with libstdc++ is that it is tightly
67  integrated with G++ development, tending to be tied fairly closely to the
68  matching version of G++.
69
70* STLport and the Apache libstdcxx library are two other popular
71  candidates, but both lack C++11 support.  Our experience (and the
72  experience of libstdc++ developers) is that adding support for C++11 (in
73  particular rvalue references and move-only types) requires changes to
74  almost every class and function, essentially amounting to a rewrite.
75  Faced with a rewrite, we decided to start from scratch and evaluate every
76  design decision from first principles based on experience.
77  Further, both projects are apparently abandoned: STLport 5.2.1 was
78  released in Oct'08, and STDCXX 4.2.1 in May'08.
79
80Platform and Compiler Support
81-----------------------------
82
83libc++ is known to work on the following platforms, using gcc and
84clang.
85Note that functionality provided by ``<atomic>`` is only functional with clang
86and GCC.
87
88============ ==================== ============ ========================
89OS           Arch                 Compilers    ABI Library
90============ ==================== ============ ========================
91Mac OS X     i386, x86_64         Clang, GCC   libc++abi
92FreeBSD 10+  i386, x86_64, ARM    Clang, GCC   libcxxrt, libc++abi
93Linux        i386, x86_64         Clang, GCC   libc++abi
94============ ==================== ============ ========================
95
96The following minimum compiler versions are strongly recommended.
97
98* Clang 3.5 and above
99* GCC 4.7 and above.
100
101Anything older *may* work.
102
103C++ Dialect Support
104---------------------
105
106* C++11 - Complete
107* `C++14 - Complete <http://libcxx.llvm.org/cxx1y_status.html>`__
108* `C++17 - In Progress <http://libcxx.llvm.org/cxx1z_status.html>`__
109* `Post C++14 Technical Specifications - In Progress <http://libcxx.llvm.org/ts1z_status.html>`__
110
111Notes and Known Issues
112----------------------
113
114This list contains known issues with libc++
115
116* Building libc++ with ``-fno-rtti`` is not supported. However
117  linking against it with ``-fno-rtti`` is supported.
118* On OS X v10.8 and older the CMake option ``-DLIBCXX_LIBCPPABI_VERSION=""``
119  must be used during configuration.
120
121
122A full list of currently open libc++ bugs can be `found here`__.
123
124.. __:  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
125
126Design Documents
127----------------
128
129.. toctree::
130   :maxdepth: 1
131
132   DesignDocs/AvailabilityMarkup
133   DesignDocs/DebugMode
134   DesignDocs/CapturingConfigInfo
135   DesignDocs/ABIVersioning
136   DesignDocs/VisibilityMacros
137   DesignDocs/ThreadingSupportAPI
138   DesignDocs/FileTimeType
139
140* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
141* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_
142* `Notes by Marshall Clow`__
143
144.. __: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/
145
146Build Bots and Test Coverage
147----------------------------
148
149* `LLVM Buildbot Builders <http://lab.llvm.org:8011/console>`_
150* `Apple Jenkins Builders <http://lab.llvm.org:8080/green/view/Libcxx/>`_
151* `Windows Appveyor Builders <https://ci.appveyor.com/project/llvm-mirror/libcxx>`_
152* `Code Coverage Results <http://efcs.ca/libcxx-coverage>`_
153
154Getting Involved
155================
156
157First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__
158and `Getting started with LLVM <http://llvm.org/docs/GettingStarted.html>`__.
159
160**Bug Reports**
161
162If you think you've found a bug in libc++, please report it using
163the `LLVM Bugzilla`_. If you're not sure, you
164can post a message to the `libcxx-dev mailing list`_ or on IRC.
165
166**Patches**
167
168If you want to contribute a patch to libc++, the best place for that is
169`Phabricator <http://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber.
170Also make sure you are subscribed to the `libcxx-commits mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_.
171
172**Discussion and Questions**
173
174Send discussions and questions to the
175`libcxx-dev mailing list <http://lists.llvm.org/mailman/listinfo/libcxx-dev>`_.
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* `libcxx-commits Mailing List`_
185* `libcxx-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