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