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