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