[libcxx-commits] [libcxx] 41dcdfb - [libc++][docs] Major update to the documentation
Louis Dionne via libcxx-commits
libcxx-commits at lists.llvm.org
Thu Aug 22 07:30:16 PDT 2024
Author: Louis Dionne
Date: 2024-08-22T10:30:10-04:00
New Revision: 41dcdfbff12a9bc06af25457d603b6ec26b6b45f
URL: https://github.com/llvm/llvm-project/commit/41dcdfbff12a9bc06af25457d603b6ec26b6b45f
DIFF: https://github.com/llvm/llvm-project/commit/41dcdfbff12a9bc06af25457d603b6ec26b6b45f.diff
LOG: [libc++][docs] Major update to the documentation
- Landing page: add link to the libc++ Discord channel
- Landing page: reorder "Getting Involved" above "Design documents"
- Landing page: remove "Notes and Known Issues" which was completely outdated
- Rename "Using Libc++" to "User Documentation" and update contents
- Rename "Building Libc++" to "Vendor Documentation" and update contents
The "BuildingLibcxx" and "UsingLibcxx" pages have basically been used for
vendor and user documentation respectively. However, they were named in
a way that doesn't really make that clear. Renaming the pages now gives
us a location to clearly document what we target at vendors and what we
target at users, and to do that separately.
Added:
libcxx/docs/UserDocumentation.rst
libcxx/docs/VendorDocumentation.rst
Modified:
libcxx/CMakeLists.txt
libcxx/docs/Contributing.rst
libcxx/docs/TestingLibcxx.rst
libcxx/docs/index.rst
Removed:
libcxx/docs/BuildingLibcxx.rst
libcxx/docs/UsingLibcxx.rst
################################################################################
diff --git a/libcxx/CMakeLists.txt b/libcxx/CMakeLists.txt
index 273b2238f34851..75c926f5432aea 100644
--- a/libcxx/CMakeLists.txt
+++ b/libcxx/CMakeLists.txt
@@ -1,6 +1,3 @@
-# See https://libcxx.llvm.org/docs/BuildingLibcxx.html for instructions on how
-# to build libcxx with CMake.
-
#===============================================================================
# Setup Project
#===============================================================================
diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst
index 90aabc9c4ff6fa..f81c537e00c243 100644
--- a/libcxx/docs/Contributing.rst
+++ b/libcxx/docs/Contributing.rst
@@ -4,9 +4,9 @@
Contributing to libc++
======================
-This file contains notes about various tasks and processes specific to contributing
-to libc++. If this is your first time contributing, please also read `this document
-<https://www.llvm.org/docs/Contributing.html>`__ on general rules for contributing to LLVM.
+This file contains information useful when contributing to libc++. If this is your first time contributing,
+please also read `this document <https://www.llvm.org/docs/Contributing.html>`__ on general rules for
+contributing to LLVM.
If you plan on contributing to libc++, it can be useful to join the ``#libcxx`` channel
on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__.
@@ -24,16 +24,22 @@ RFCs for significant user-affecting changes
===========================================
Before you start working on a change that can have significant impact on users of the library,
-please consider creating a RFC on `libc++'s Discourse forum <https://discourse.llvm.org/c/runtimes/libcxx>`__.
+please consider creating a RFC on the `libc++ forum <https://discourse.llvm.org/c/runtimes/libcxx>`_.
This will ensure that you work in a direction that the project endorses and will ease reviewing your
-contribution as directional questions can be raised early. Including a WIP patch is not mandatory, but
-it can be useful to ground the discussion in something concrete.
+contribution as directional questions can be raised early. Including a WIP patch is not mandatory,
+but it can be useful to ground the discussion in something concrete.
+
+Writing tests and running the test suite
+========================================
+
+Every change in libc++ must come with appropriate tests. Libc++ has an extensive test suite that
+should be run locally by developers before submitting patches and is also run as part of our CI
+infrastructure. The documentation about writing tests and running them is :ref:`here <testing>`.
Coding standards
================
-In general, libc++ follows the
-`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_.
+In general, libc++ follows the `LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_.
There are some deviations from these standards.
Libc++ uses ``__ugly_names``. These names are reserved for implementations, so
diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst
index 65a7e1ec30c962..55f84a312e85c8 100644
--- a/libcxx/docs/TestingLibcxx.rst
+++ b/libcxx/docs/TestingLibcxx.rst
@@ -1,3 +1,5 @@
+.. _testing:
+
==============
Testing libc++
==============
@@ -5,8 +7,6 @@ Testing libc++
.. contents::
:local:
-.. _testing:
-
Getting Started
===============
@@ -459,11 +459,6 @@ This will build all of the benchmarks under ``<libcxx>/test/benchmarks`` to be
built against the just-built libc++. The compiled tests are output into
``build/libcxx/test/benchmarks``.
-Also See:
-
- * :ref:`Building Libc++ <build instructions>`
- * :ref:`CMake Options`
-
Running Benchmarks
------------------
diff --git a/libcxx/docs/UsingLibcxx.rst b/libcxx/docs/UserDocumentation.rst
similarity index 87%
rename from libcxx/docs/UsingLibcxx.rst
rename to libcxx/docs/UserDocumentation.rst
index df08875c13beae..165c3b7b049087 100644
--- a/libcxx/docs/UsingLibcxx.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -1,19 +1,17 @@
-.. _using-libcxx:
+.. _user-documentation:
-============
-Using libc++
-============
+==================
+User documentation
+==================
.. contents::
:local:
-Usually, libc++ is packaged and shipped by a vendor through some delivery vehicle
-(operating system distribution, SDK, toolchain, etc) and users don't need to do
-anything special in order to use the library.
-
This page contains information about configuration knobs that can be used by
users when they know libc++ is used by their toolchain, and how to use libc++
-when it is not the default library used by their toolchain.
+when it is not the default library used by their toolchain. It is aimed at
+users of libc++: a separate page contains documentation aimed at vendors who
+build and ship libc++ as part of their toolchain.
Using a
diff erent version of the C++ Standard
@@ -28,10 +26,29 @@ matches that Standard in the library.
$ clang++ -std=c++17 test.cpp
-.. warning::
- Using ``-std=c++XY`` with a version of the Standard that has not been ratified yet
- is considered unstable. Libc++ reserves the right to make breaking changes to the
- library until the standard has been ratified.
+Note that using ``-std=c++XY`` with a version of the Standard that has not been ratified
+yet is considered unstable. While we strive to maintain stability, libc++ may be forced to
+make breaking changes to features shipped in a Standard that hasn't been ratified yet. Use
+these versions of the Standard at your own risk.
+
+
+Using libc++ when it is not the system default
+==============================================
+
+Usually, libc++ is packaged and shipped by a vendor through some delivery vehicle
+(operating system distribution, SDK, toolchain, etc) and users don't need to do
+anything special in order to use the library.
+
+On systems where libc++ is provided but is not the default, Clang provides a flag
+called ``-stdlib=`` that can be used to decide which standard library is used.
+Using ``-stdlib=libc++`` will select libc++:
+
+.. code-block:: bash
+
+ $ clang++ -stdlib=libc++ test.cpp
+
+On systems where libc++ is the library in use by default such as macOS and FreeBSD,
+this flag is not required.
Enabling experimental C++ Library features
@@ -43,6 +60,11 @@ the Standard but whose implementation is not complete or stable yet in libc++. T
are disabled by default because they are neither API nor ABI stable. However, the
``-fexperimental-library`` compiler flag can be defined to turn those features on.
+On compilers that do not support the ``-fexperimental-library`` flag (such as GCC),
+users can define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against
+the appropriate static library (usually shipped as ``libc++experimental.a``) to get
+access to experimental library features.
+
The following features are currently considered experimental and are only provided
when ``-fexperimental-library`` is passed:
@@ -51,7 +73,7 @@ when ``-fexperimental-library`` is passed:
* ``std::jthread``
* ``std::chrono::tzdb`` and related time zone functionality
-.. warning::
+.. note::
Experimental libraries are experimental.
* The contents of the ``<experimental/...>`` headers and the associated static
library will not remain compatible between versions.
@@ -60,98 +82,18 @@ when ``-fexperimental-library`` is passed:
the experimental feature is removed two releases after the non-experimental
version has shipped. The full policy is explained :ref:`here <experimental features>`.
-.. note::
- On compilers that do not support the ``-fexperimental-library`` flag, users can
- define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against the
- appropriate static library (usually shipped as ``libc++experimental.a``) to get
- access to experimental library features.
-
-
-Using libc++ when it is not the system default
-==============================================
-
-On systems where libc++ is provided but is not the default, Clang provides a flag
-called ``-stdlib=`` that can be used to decide which standard library is used.
-Using ``-stdlib=libc++`` will select libc++:
-
-.. code-block:: bash
-
- $ clang++ -stdlib=libc++ test.cpp
-
-On systems where libc++ is the library in use by default such as macOS and FreeBSD,
-this flag is not required.
-
-
-.. _alternate libcxx:
-
-Using a custom built libc++
-===========================
-
-Most compilers provide a way to disable the default behavior for finding the
-standard library and to override it with custom paths. With Clang, this can
-be done with:
-
-.. code-block:: bash
-
- $ clang++ -nostdinc++ -nostdlib++ \
- -isystem <install>/include/c++/v1 \
- -L <install>/lib \
- -Wl,-rpath,<install>/lib \
- -lc++ \
- test.cpp
-
-The option ``-Wl,-rpath,<install>/lib`` adds a runtime library search path,
-which causes the system's dynamic linker to look for libc++ in ``<install>/lib``
-whenever the program is loaded.
-
-GCC does not support the ``-nostdlib++`` flag, so one must use ``-nodefaultlibs``
-instead. Since that removes all the standard system libraries and not just libc++,
-the system libraries must be re-added manually. For example:
-
-.. code-block:: bash
-
- $ g++ -nostdinc++ -nodefaultlibs \
- -isystem <install>/include/c++/v1 \
- -L <install>/lib \
- -Wl,-rpath,<install>/lib \
- -lc++ -lc++abi -lm -lc -lgcc_s -lgcc \
- test.cpp
-
-
-GDB Pretty printers for libc++
-==============================
-
-GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does
-provide pretty-printers itself. Those can be used as:
-
-.. code-block:: bash
-
- $ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \
- -ex "python register_libcxx_printer_loader()" \
- <args>
-
-.. _include-what-you-use:
-
-include-what-you-use (IWYU)
-===========================
-
-libc++ provides an IWYU `mapping file <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md>`_,
-which drastically improves the accuracy of the tool when using libc++. To use the mapping file with
-IWYU, you should run the tool like so:
-
-.. code-block:: bash
-
- $ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp file.cpp
-
-If you would prefer to not use that flag, then you can replace ``/path/to/include-what-you-use/share/libcxx.imp``
-file with the libc++-provided ``libcxx.imp`` file.
Libc++ Configuration Macros
===========================
-Libc++ provides a number of configuration macros which can be used to enable
-or disable extended libc++ behavior, including enabling hardening or thread
-safety annotations.
+Libc++ provides a number of configuration macros that can be used by developers to
+enable or disable extended libc++ behavior.
+
+.. warning::
+ Configuration macros that are not documented here are not intended to be customized
+ by developers and should not be used. In particular, some configuration macros are
+ only intended to be used by vendors and changing their value from the one provided
+ in your toolchain can lead to unexpected behavior.
**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
This macro is used to enable -Wthread-safety annotations on libc++'s
@@ -193,6 +135,12 @@ safety annotations.
warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
no warning will be emitted. By default, this macro is not defined.
+**_LIBCPP_ENABLE_EXPERIMENTAL**:
+ This macro enables experimental features. This can be used on compilers that do
+ not support the ``-fexperimental-library`` flag. When used, users also need to
+ ensure that the appropriate experimental library (usually ``libc++experimental.a``)
+ is linked into their program.
+
C++17 Specific Configuration Macros
-----------------------------------
**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
@@ -307,7 +255,7 @@ Extensions to the C++23 modules ``std`` and ``std.compat``
----------------------------------------------------------
Like other major implementations, libc++ provides C++23 modules ``std`` and
-``std.compat`` in C++20 as an extension"
+``std.compat`` in C++20 as an extension.
Constant-initialized std::string
--------------------------------
@@ -386,3 +334,38 @@ specific locale is imbued, the IO with the underlying stream happens with
regular ``char`` elements, which are converted to/from wide characters
according to the locale. Note that this doesn't behave as expected if the
stream has been set in Unicode mode.
+
+
+Third-party Integrations
+========================
+
+Libc++ provides integration with a few third-party tools.
+
+GDB Pretty printers for libc++
+------------------------------
+
+GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does
+provide pretty-printers itself. Those can be used as:
+
+.. code-block:: bash
+
+ $ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \
+ -ex "python register_libcxx_printer_loader()" \
+ <args>
+
+
+.. _include-what-you-use:
+
+include-what-you-use (IWYU)
+---------------------------
+
+libc++ provides an IWYU `mapping file <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md>`_,
+which drastically improves the accuracy of the tool when using libc++. To use the mapping file with
+IWYU, you should run the tool like so:
+
+.. code-block:: bash
+
+ $ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp file.cpp
+
+If you would prefer to not use that flag, then you can replace ``/path/to/include-what-you-use/share/libcxx.imp``
+file with the libc++-provided ``libcxx.imp`` file.
diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/VendorDocumentation.rst
similarity index 89%
rename from libcxx/docs/BuildingLibcxx.rst
rename to libcxx/docs/VendorDocumentation.rst
index 5c224689e0f9f8..3a3d1cdb1ea7ff 100644
--- a/libcxx/docs/BuildingLibcxx.rst
+++ b/libcxx/docs/VendorDocumentation.rst
@@ -1,19 +1,17 @@
-.. _BuildingLibcxx:
+.. _VendorDocumentation:
-===============
-Building libc++
-===============
+====================
+Vendor Documentation
+====================
.. contents::
:local:
-.. _build instructions:
-
The instructions on this page are aimed at vendors who ship libc++ as part of an
operating system distribution, a toolchain or similar shipping vehicles. If you
are a user merely trying to use libc++ in your program, you most likely want to
-refer to your vendor's documentation, or to the general documentation for using
-libc++ :ref:`here <using-libcxx>`.
+refer to your vendor's documentation, or to the general user documentation
+:ref:`here <user-documentation>`.
.. warning::
If your operating system already provides libc++, it is important to be careful
@@ -42,21 +40,37 @@ with the following CMake invocation:
$ ninja -C build install-cxx install-cxxabi install-unwind # Install
.. note::
- See :ref:`CMake Options` below for more configuration options.
+ See :ref:`Vendor Configuration Options` below for more configuration options.
After building the various ``install-XXX`` targets, shared libraries for libc++, libc++abi and
libunwind should now be present in ``<CMAKE_INSTALL_PREFIX>/lib``, and headers in
-``<CMAKE_INSTALL_PREFIX>/include/c++/v1``. See :ref:`using an alternate libc++ installation
-<alternate libcxx>` for information on how to use this libc++ over the default one.
+``<CMAKE_INSTALL_PREFIX>/include/c++/v1``. See the instructions below for information on how
+to use this libc++ over the default one.
In the default configuration, the runtimes will be built using the compiler available by default
on your system. Of course, you can change what compiler is being used with the usual CMake
variables. If you wish to build the runtimes from a just-built Clang, the bootstrapping build
explained below makes this task easy.
+Using the just-built libc++
+---------------------------
-Bootstrapping build
-===================
+Most compilers provide a way to disable the default behavior for finding the standard library and
+to override it with custom paths. With Clang, this can be done with:
+
+.. code-block:: bash
+
+ $ clang++ -nostdinc++ -isystem <install>/include/c++/v1 \
+ -nostdlib++ -L <install>/lib -lc++ \
+ -Wl,-rpath,<install>/lib \
+ test.cpp
+
+The option ``-Wl,-rpath,<install>/lib`` adds a runtime library search path, which causes the system's
+dynamic linker to look for libc++ in ``<install>/lib`` whenever the program is loaded.
+
+
+The Bootstrapping build
+=======================
It is possible to build Clang and then build the runtimes using that just-built compiler in a
single CMake invocation. This is usually the correct way to build the runtimes when putting together
@@ -75,123 +89,29 @@ CMake invocation at ``<monorepo>/llvm``:
$ ninja -C build install-runtimes # Install
.. note::
- This type of build is also commonly called a "Runtimes build", but we would like to move
- away from that terminology, which is too confusing.
-
-.. warning::
- Adding the `--fresh` flag to the top-level cmake invocation in a bootstrapping build *will not*
- freshen the cmake cache of any of the enabled runtimes.
-
-Support for Windows
-===================
-
-libcxx supports being built with clang-cl, but not with MSVC's cl.exe, as
-cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or
-newer (19.14) is required.
-
-libcxx also supports being built with clang targeting MinGW environments.
-
-CMake + Visual Studio
----------------------
+ - This type of build is also commonly called a "Runtimes build", but we would like to move
+ away from that terminology, which is too confusing.
-Building with Visual Studio currently does not permit running tests. However,
-it is the simplest way to build.
+ - Adding the `--fresh` flag to the top-level cmake invocation in a bootstrapping build *will not*
+ freshen the cmake cache of any of the enabled runtimes.
-.. code-block:: batch
- > cmake -G "Visual Studio 16 2019" -S runtimes -B build ^
- -T "ClangCL" ^
- -DLLVM_ENABLE_RUNTIMES=libcxx ^
- -DLIBCXX_ENABLE_SHARED=YES ^
- -DLIBCXX_ENABLE_STATIC=NO
- > cmake --build build
+.. _Vendor Configuration Options:
-CMake + ninja (MSVC)
---------------------
+Vendor Configuration Options
+============================
-Building with ninja is required for development to enable tests.
-A couple of tests require Bash to be available, and a couple dozens
-of tests require other posix tools (cp, grep and similar - LLVM's tests
-require the same). Without those tools the vast majority of tests
-can still be ran successfully.
+This section documents configuration options that can be used by vendors when building the library.
+These options provide a great deal of flexibility to customize libc++, such as selecting the ABI in
+use, whether some features are provided, etc.
-If Git for Windows is available, that can be used to provide the bash
-shell by adding the right bin directory to the path, e.g.
-``set PATH=%PATH%;C:\Program Files\Git\usr\bin``.
-
-Alternatively, one can also choose to run the whole build in a MSYS2
-shell. That can be set up e.g. by starting a Visual Studio Tools Command
-Prompt (for getting the environment variables pointing to the headers and
-import libraries), and making sure that clang-cl is available in the
-path. From there, launch an MSYS2 shell via e.g.
-``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier
-environment, allowing the MSVC headers/libraries and clang-cl to be found).
-
-In either case, then run:
-
-.. code-block:: batch
-
- > cmake -G Ninja -S runtimes -B build ^
- -DCMAKE_C_COMPILER=clang-cl ^
- -DCMAKE_CXX_COMPILER=clang-cl ^
- -DLLVM_ENABLE_RUNTIMES=libcxx
- > ninja -C build cxx
- > ninja -C build check-cxx
-
-If you are running in an MSYS2 shell and you have installed the
-MSYS2-provided clang package (which defaults to a non-MSVC target), you
-should add e.g. ``-DCMAKE_CXX_COMPILER_TARGET=x86_64-windows-msvc`` (replacing
-``x86_64`` with the architecture you're targeting) to the ``cmake`` command
-line above. This will instruct ``check-cxx`` to use the right target triple
-when invoking ``clang++``.
-
-CMake + ninja (MinGW)
----------------------
-
-libcxx can also be built in MinGW environments, e.g. with the MinGW
-compilers in MSYS2. This requires clang to be available (installed with
-e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja.
-
-.. code-block:: bash
-
- > cmake -G Ninja -S runtimes -B build \
- -DCMAKE_C_COMPILER=clang \
- -DCMAKE_CXX_COMPILER=clang++ \
- -DLLVM_ENABLE_LLD=ON \
- -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \
- -DLIBCXXABI_ENABLE_SHARED=OFF \
- -DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON
- > ninja -C build cxx
- > ninja -C build check-cxx
-
-.. _`libc++abi`: http://libcxxabi.llvm.org/
-
-
-.. _CMake Options:
-
-CMake Options
-=============
-
-Here are some of the CMake variables that are used often, along with a
-brief explanation and LLVM-specific notes. For full documentation, check the
-CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
-
-**CMAKE_BUILD_TYPE**:STRING
- Sets the build type for ``make`` based generators. Possible values are
- Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
- the user sets the build type with the IDE settings.
-
-**CMAKE_INSTALL_PREFIX**:PATH
- Path where LLVM will be installed if "make install" is invoked or the
- "INSTALL" target is built.
-
-**CMAKE_CXX_COMPILER**:STRING
- The C++ compiler to use when building and testing libc++.
-
-
-.. _libcxx-specific options:
+.. warning::
+ Many of these CMake options are tied to configuration macros with a corresponding name in the source
+ code. However, these configuration macros are not intended to be customized by users directly, since
+ many of them require the library to be built with a matching configuration. If you don't build libc++
+ yourself, you should not use the options documented here.
-libc++ specific options
+General purpose options
-----------------------
.. option:: LIBCXX_INSTALL_LIBRARY:BOOL
@@ -305,65 +225,6 @@ libc++ specific options
Additional libraries libc++ is linked to which can be provided in cache.
-
-.. _ABI Library Specific Options:
-
-ABI Library Specific Options
-----------------------------
-
-.. option:: LIBCXX_CXX_ABI:STRING
-
- **Values**: ``none``, ``libcxxabi``, ``system-libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``, ``vcruntime``.
-
- Select the ABI library to build libc++ against.
-
-.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS
-
- Provide additional search paths for the ABI library headers.
-
-.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH
-
- Provide the path to the ABI library that libc++ should link against. This is only
- useful when linking against an out-of-tree ABI library.
-
-.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL
-
- **Default**: ``OFF``
-
- If this option is enabled, libc++ will try and link the selected ABI library
- statically.
-
-.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL
-
- **Default**: ``ON`` by default on UNIX platforms other than Apple unless
- 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``.
-
- This option generate and installs a linker script as ``libc++.so`` which
- links the correct ABI library.
-
-.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL
-
- **Default**: ``ON``
-
- Build and use the LLVM unwinder. Note: This option can only be used when
- libc++abi is the C++ ABI library used.
-
-.. option:: LIBCXXABI_ADDITIONAL_COMPILE_FLAGS:STRING
-
- **Default**: ``""``
-
- Additional Compile only flags which can be provided in cache.
-
-.. option:: LIBCXXABI_ADDITIONAL_LIBRARIES:STRING
-
- **Default**: ``""``
-
- Additional libraries libc++abi is linked to which can be provided in cache.
-
-
-libc++ Feature Options
-----------------------
-
.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL
**Default**: ``ON``
@@ -409,9 +270,8 @@ libc++ Feature Options
default assertion handler. If this is specified as a relative path, it
is assumed to be relative to ``<monorepo>/libcxx``.
-
-libc++ ABI Feature Options
---------------------------
+ABI Specific Options
+--------------------
The following options allow building libc++ for a
diff erent ABI version.
@@ -437,7 +297,7 @@ The following options allow building libc++ for a
diff erent ABI version.
with other libc++ versions.
.. warning::
- When providing a custom namespace, it's the user's responsibility to ensure the name won't cause
+ When providing a custom namespace, it's the vendor's responsibility to ensure the name won't cause
conflicts with other names defined by libc++, both now and in the future. In particular, inline
namespaces of the form ``__[0-9]+`` could cause conflicts with future versions of the library,
and so should be avoided.
@@ -449,8 +309,54 @@ The following options allow building libc++ for a
diff erent ABI version.
A semicolon-separated list of ABI macros to persist in the site config header.
See ``include/__config`` for the list of ABI macros.
+.. option:: LIBCXX_CXX_ABI:STRING
+
+ **Values**: ``none``, ``libcxxabi``, ``system-libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``, ``vcruntime``.
+
+ Select the ABI library to build libc++ against.
+
+.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS
+
+ Provide additional search paths for the ABI library headers.
+
+.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH
+
+ Provide the path to the ABI library that libc++ should link against. This is only
+ useful when linking against an out-of-tree ABI library.
+
+.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL
+
+ **Default**: ``OFF``
+
+ If this option is enabled, libc++ will try and link the selected ABI library
+ statically.
-.. _LLVM-specific variables:
+.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL
+
+ **Default**: ``ON`` by default on UNIX platforms other than Apple unless
+ 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``.
+
+ This option generate and installs a linker script as ``libc++.so`` which
+ links the correct ABI library.
+
+.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL
+
+ **Default**: ``ON``
+
+ Build and use the LLVM unwinder. Note: This option can only be used when
+ libc++abi is the C++ ABI library used.
+
+.. option:: LIBCXXABI_ADDITIONAL_COMPILE_FLAGS:STRING
+
+ **Default**: ``""``
+
+ Additional Compile only flags which can be provided in cache.
+
+.. option:: LIBCXXABI_ADDITIONAL_LIBRARIES:STRING
+
+ **Default**: ``""``
+
+ Additional libraries libc++abi is linked to which can be provided in cache.
LLVM-specific options
---------------------
@@ -473,6 +379,91 @@ LLVM-specific options
others.
+Support for Windows
+===================
+
+Libc++ supports being built with clang-cl, but not with MSVC's cl.exe, as
+cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or
+newer (19.14) is required.
+
+Libc++ also supports being built with clang targeting MinGW environments.
+
+CMake + Visual Studio
+---------------------
+
+Building with Visual Studio currently does not permit running tests. However,
+it is the simplest way to build.
+
+.. code-block:: batch
+
+ > cmake -G "Visual Studio 16 2019" -S runtimes -B build ^
+ -T "ClangCL" ^
+ -DLLVM_ENABLE_RUNTIMES=libcxx ^
+ -DLIBCXX_ENABLE_SHARED=YES ^
+ -DLIBCXX_ENABLE_STATIC=NO
+ > cmake --build build
+
+CMake + ninja (MSVC)
+--------------------
+
+Building with ninja is required for development to enable tests.
+A couple of tests require Bash to be available, and a couple dozens
+of tests require other posix tools (cp, grep and similar - LLVM's tests
+require the same). Without those tools the vast majority of tests
+can still be ran successfully.
+
+If Git for Windows is available, that can be used to provide the bash
+shell by adding the right bin directory to the path, e.g.
+``set PATH=%PATH%;C:\Program Files\Git\usr\bin``.
+
+Alternatively, one can also choose to run the whole build in a MSYS2
+shell. That can be set up e.g. by starting a Visual Studio Tools Command
+Prompt (for getting the environment variables pointing to the headers and
+import libraries), and making sure that clang-cl is available in the
+path. From there, launch an MSYS2 shell via e.g.
+``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier
+environment, allowing the MSVC headers/libraries and clang-cl to be found).
+
+In either case, then run:
+
+.. code-block:: batch
+
+ > cmake -G Ninja -S runtimes -B build ^
+ -DCMAKE_C_COMPILER=clang-cl ^
+ -DCMAKE_CXX_COMPILER=clang-cl ^
+ -DLLVM_ENABLE_RUNTIMES=libcxx
+ > ninja -C build cxx
+ > ninja -C build check-cxx
+
+If you are running in an MSYS2 shell and you have installed the
+MSYS2-provided clang package (which defaults to a non-MSVC target), you
+should add e.g. ``-DCMAKE_CXX_COMPILER_TARGET=x86_64-windows-msvc`` (replacing
+``x86_64`` with the architecture you're targeting) to the ``cmake`` command
+line above. This will instruct ``check-cxx`` to use the right target triple
+when invoking ``clang++``.
+
+CMake + ninja (MinGW)
+---------------------
+
+libcxx can also be built in MinGW environments, e.g. with the MinGW
+compilers in MSYS2. This requires clang to be available (installed with
+e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja.
+
+.. code-block:: bash
+
+ > cmake -G Ninja -S runtimes -B build \
+ -DCMAKE_C_COMPILER=clang \
+ -DCMAKE_CXX_COMPILER=clang++ \
+ -DLLVM_ENABLE_LLD=ON \
+ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \
+ -DLIBCXXABI_ENABLE_SHARED=OFF \
+ -DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON
+ > ninja -C build cxx
+ > ninja -C build check-cxx
+
+.. _`libc++abi`: http://libcxxabi.llvm.org/
+
+
.. _assertion-handler:
Overriding the default assertion handler
diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst
index 2dc08563358aba..18af347a1217ff 100644
--- a/libcxx/docs/index.rst
+++ b/libcxx/docs/index.rst
@@ -35,10 +35,10 @@ Getting Started with libc++
:maxdepth: 1
ReleaseNotes
- UsingLibcxx
- BuildingLibcxx
- TestingLibcxx
+ UserDocumentation
+ VendorDocumentation
Contributing
+ TestingLibcxx
ImplementationDefinedBehavior
Modules
Hardening
@@ -185,18 +185,25 @@ this release is described in the pages below:
* :ref:`C++ Feature Test Macro Status <feature-status>`
-Notes and Known Issues
-======================
+Getting Involved
+================
+
+First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
+and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
+
+**Bug Reports**
-This list contains known issues with libc++
+If you think you've found a bug in libc++, please report it using the `LLVM bug tracker`_.
+If you're not sure, you can ask for support on the `libc++ forum`_ or in the `libc++ chat`_.
-* Building libc++ with ``-fno-rtti`` is not supported. However
- linking against it with ``-fno-rtti`` is supported.
+**Patches**
+If you want to contribute a patch to libc++, please start by reviewing our
+:ref:`documentation about contributing <ContributingToLibcxx>`.
-A full list of currently open libc++ bugs can be `found here`__.
+**Discussion and Questions**
-.. __: https://github.com/llvm/llvm-project/labels/libc%2B%2B
+Send discussions and questions to the `libc++ forum`_.
Design Documents
@@ -232,33 +239,12 @@ Build Bots and Test Coverage
* :ref:`Adding New CI Jobs <AddingNewCIJobs>`
-Getting Involved
-================
-
-First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
-and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
-
-**Bug Reports**
-
-If you think you've found a bug in libc++, please report it using
-the `LLVM bug tracker`_. If you're not sure, you
-can ask for support on the `libcxx forum`_ or on IRC.
-
-**Patches**
-
-If you want to contribute a patch to libc++, please start by reviewing our
-:ref:`documentation about contributing <ContributingToLibcxx>`.
-
-**Discussion and Questions**
-
-Send discussions and questions to the `libcxx forum`_.
-
-
Quick Links
===========
* `LLVM Homepage <https://llvm.org/>`_
* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
* `LLVM Bug Tracker <https://github.com/llvm/llvm-project/labels/libc++/>`_
* `libcxx-commits Mailing List <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_
-* `libcxx Forum <https://discourse.llvm.org/c/runtimes/libcxx/>`_
+* `libc++ forum <https://discourse.llvm.org/c/runtimes/libcxx/>`_
+* `libc++ chat <https://discord.com/channels/636084430946959380/636732894974312448>`_
* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_
More information about the libcxx-commits
mailing list