libcxx/docs/index.rst

   1 .. _index:
   2
   3 =============================
   4 "libc++" C++ Standard Library
   5 =============================
   6
   7 Overview
   8 ========
   9
  10 libc++ is a new implementation of the C++ standard library, targeting C++11 and
  11 above.
  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
  31 Getting Started with libc++
  32 ===========================
  33
  34 .. toctree::
  35    :maxdepth: 1
  36
  37    ReleaseNotes/17
  38    ReleaseNotes/18
  39    UsingLibcxx
  40    BuildingLibcxx
  41    TestingLibcxx
  42    Contributing
  43    ImplementationDefinedBehavior
  44    Modules
  45    Hardening
  46    ReleaseProcedure
  47    Status/Cxx14
  48    Status/Cxx17
  49    Status/Cxx20
  50    Status/Cxx23
  51    Status/Cxx2c
  52    Status/Format
  53    Status/Parallelism
  54    Status/PSTL
  55    Status/Ranges
  56    Status/Spaceship
  57    Status/Zip
  58
  59
  60 .. toctree::
  61     :hidden:
  62
  63     AddingNewCIJobs
  64     FeatureTestMacroTable
  65
  66
  67 Current Status
  68 ==============
  69
  70 After its initial introduction, many people have asked "why start a new
  71 library instead of contributing to an existing library?" (like Apache's
  72 libstdcxx, GNU's libstdc++, STLport, etc).  There are many contributing
  73 reasons, but some of the major ones are:
  74
  75 * From years of experience (including having implemented the standard
  76   library before), we've learned many things about implementing
  77   the standard containers which require ABI breakage and fundamental changes
  78   to how they are implemented.  For example, it is generally accepted that
  79   building std::string using the "short string optimization" instead of
  80   using Copy On Write (COW) is a superior approach for multicore
  81   machines (particularly in C++11, which has rvalue references).  Breaking
  82   ABI compatibility with old versions of the library was
  83   determined to be critical to achieving the performance goals of
  84   libc++.
  85
  86 * Mainline libstdc++ has switched to GPL3, a license which the developers
  87   of libc++ cannot use.  libstdc++ 4.2 (the last GPL2 version) could be
  88   independently extended to support C++11, but this would be a fork of the
  89   codebase (which is often seen as worse for a project than starting a new
  90   independent one).  Another problem with libstdc++ is that it is tightly
  91   integrated with G++ development, tending to be tied fairly closely to the
  92   matching version of G++.
  93
  94 * STLport and the Apache libstdcxx library are two other popular
  95   candidates, but both lack C++11 support.  Our experience (and the
  96   experience of libstdc++ developers) is that adding support for C++11 (in
  97   particular rvalue references and move-only types) requires changes to
  98   almost every class and function, essentially amounting to a rewrite.
  99   Faced with a rewrite, we decided to start from scratch and evaluate every
 100   design decision from first principles based on experience.
 101   Further, both projects are apparently abandoned: STLport 5.2.1 was
 102   released in Oct'08, and STDCXX 4.2.1 in May'08.
 103
 104 ..
 105   LLVM RELEASE bump version
 106
 107 .. _SupportedPlatforms:
 108
 109 Platform and Compiler Support
 110 =============================
 111
 112 Libc++ aims to support common compilers that implement the C++11 Standard. In order to strike a
 113 good balance between stability for users and maintenance cost, testing coverage and development
 114 velocity, libc++ drops support for older compilers as newer ones are released.
 115
 116 ============ =============== ========================== =====================
 117 Compiler     Versions        Restrictions               Support policy
 118 ============ =============== ========================== =====================
 119 Clang        16, 17, 18-git                             latest two stable releases per `LLVM's release page <https://releases.llvm.org>`_ and the development version
 120 AppleClang   15                                         latest stable release per `Xcode's release page <https://developer.apple.com/documentation/xcode-release-notes>`_
 121 Open XL      17.1 (AIX)                                 latest stable release per `Open XL's documentation page <https://www.ibm.com/docs/en/openxl-c-and-cpp-aix>`_
 122 GCC          12              In C++11 or later only     latest stable release per `GCC's release page <https://gcc.gnu.org/releases.html>`_
 123 ============ =============== ========================== =====================
 124
 125 Libc++ also supports common platforms and architectures:
 126
 127 =============== ========================= ============================
 128 Target platform Target architecture       Notes
 129 =============== ========================= ============================
 130 macOS 10.9+     i386, x86_64, arm64       Building the shared library itself requires targetting macOS 10.13+
 131 FreeBSD 12+     i386, x86_64, arm
 132 Linux           i386, x86_64, arm, arm64  Only glibc-2.24 and later and no other libc is officially supported
 133 Android 5.0+    i386, x86_64, arm, arm64
 134 Windows         i386, x86_64              Both MSVC and MinGW style environments, ABI in MSVC environments is :doc:`unstable <DesignDocs/ABIVersioning>`
 135 AIX 7.2TL5+     powerpc, powerpc64
 136 =============== ========================= ============================
 137
 138 Generally speaking, libc++ should work on any platform that provides a fairly complete
 139 C Standard Library. It is also possible to turn off parts of the library for use on
 140 systems that provide incomplete support.
 141
 142 However, libc++ aims to provide a high-quality implementation of the C++ Standard
 143 Library, especially when it comes to correctness. As such, we aim to have test coverage
 144 for all the platforms and compilers that we claim to support. If a platform or compiler
 145 is not listed here, it is not officially supported. It may happen to work, and
 146 in practice the library is known to work on some platforms not listed here, but
 147 we don't make any guarantees. If you would like your compiler and/or platform
 148 to be formally supported and listed here, please work with the libc++ team to set
 149 up testing for your configuration.
 150
 151
 152 C++ Dialect Support
 153 ===================
 154
 155 * C++11 - Complete
 156 * :ref:`C++14 - Complete <cxx14-status>`
 157 * :ref:`C++17 - In Progress <cxx17-status>`
 158 * :ref:`C++20 - In Progress <cxx20-status>`
 159 * :ref:`C++23 - In Progress <cxx23-status>`
 160 * :ref:`C++2c - In Progress <cxx2c-status>`
 161 * :ref:`C++ Feature Test Macro Status <feature-status>`
 162
 163
 164 Notes and Known Issues
 165 ======================
 166
 167 This list contains known issues with libc++
 168
 169 * Building libc++ with ``-fno-rtti`` is not supported. However
 170   linking against it with ``-fno-rtti`` is supported.
 171
 172
 173 A full list of currently open libc++ bugs can be `found here`__.
 174
 175 .. __:  https://github.com/llvm/llvm-project/labels/libc%2B%2B
 176
 177
 178 Design Documents
 179 ================
 180
 181 .. toctree::
 182    :maxdepth: 1
 183
 184    DesignDocs/ABIVersioning
 185    DesignDocs/AtomicDesign
 186    DesignDocs/CapturingConfigInfo
 187    DesignDocs/ExperimentalFeatures
 188    DesignDocs/ExtendedCXX03Support
 189    DesignDocs/FeatureTestMacros
 190    DesignDocs/FileTimeType
 191    DesignDocs/HeaderRemovalPolicy
 192    DesignDocs/NoexceptPolicy
 193    DesignDocs/PSTLIntegration
 194    DesignDocs/ThreadingSupportAPI
 195    DesignDocs/UniquePtrTrivialAbi
 196    DesignDocs/UnspecifiedBehaviorRandomization
 197    DesignDocs/VisibilityMacros
 198    DesignDocs/TimeZone
 199
 200
 201 Build Bots and Test Coverage
 202 ============================
 203
 204 * `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_
 205 * `LLVM Buildbot Builders <https://lab.llvm.org/buildbot>`_
 206 * :ref:`Adding New CI Jobs <AddingNewCIJobs>`
 207
 208
 209 Getting Involved
 210 ================
 211
 212 First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
 213 and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
 214
 215 **Bug Reports**
 216
 217 If you think you've found a bug in libc++, please report it using
 218 the `LLVM bug tracker`_. If you're not sure, you
 219 can ask for support on the `libcxx forum`_ or on IRC.
 220
 221 **Patches**
 222
 223 If you want to contribute a patch to libc++, the best place for that is
 224 `Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please add `libcxx-commits` as a subscriber.
 225 Also make sure you are subscribed to the `libcxx-commits mailing list`_.
 226
 227 **Discussion and Questions**
 228
 229 Send discussions and questions to the `libcxx forum`_.
 230
 231
 232 Quick Links
 233 ===========
 234 * `LLVM Homepage <https://llvm.org/>`_
 235 * `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
 236 * `LLVM Bug Tracker <https://github.com/llvm/llvm-project/labels/libc++/>`_
 237 * `libcxx-commits Mailing List <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_
 238 * `libcxx Forum <https://discourse.llvm.org/c/runtimes/libcxx/>`_
 239 * `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_