[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.
This commit is contained in:
Louis Dionne
parent
32679e10a9
commit
41dcdfbff1
@ -1,6 +1,3 @@
|
||||
# See https://libcxx.llvm.org/docs/BuildingLibcxx.html for instructions on how
|
||||
# to build libcxx with CMake.
|
||||
|
||||
#===============================================================================
|
||||
# Setup Project
|
||||
#===============================================================================
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
------------------
|
||||
|
||||
|
||||
@ -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 different version of the C++ Standard
|
||||
@ -28,48 +26,19 @@ 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.
|
||||
|
||||
|
||||
Enabling experimental C++ Library features
|
||||
==========================================
|
||||
|
||||
Libc++ provides implementations of some experimental features. Experimental features
|
||||
are either Technical Specifications (TSes) or official features that were voted to
|
||||
the Standard but whose implementation is not complete or stable yet in libc++. Those
|
||||
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.
|
||||
|
||||
The following features are currently considered experimental and are only provided
|
||||
when ``-fexperimental-library`` is passed:
|
||||
|
||||
* The parallel algorithms library (``<execution>`` and the associated algorithms)
|
||||
* ``std::stop_token``, ``std::stop_source`` and ``std::stop_callback``
|
||||
* ``std::jthread``
|
||||
* ``std::chrono::tzdb`` and related time zone functionality
|
||||
|
||||
.. warning::
|
||||
Experimental libraries are experimental.
|
||||
* The contents of the ``<experimental/...>`` headers and the associated static
|
||||
library will not remain compatible between versions.
|
||||
* No guarantees of API or ABI stability are provided.
|
||||
* When the standardized version of an experimental feature is implemented,
|
||||
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.
|
||||
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++:
|
||||
@ -82,76 +51,49 @@ On systems where libc++ is the library in use by default such as macOS and FreeB
|
||||
this flag is not required.
|
||||
|
||||
|
||||
.. _alternate libcxx:
|
||||
Enabling experimental C++ Library features
|
||||
==========================================
|
||||
|
||||
Using a custom built libc++
|
||||
===========================
|
||||
Libc++ provides implementations of some experimental features. Experimental features
|
||||
are either Technical Specifications (TSes) or official features that were voted to
|
||||
the Standard but whose implementation is not complete or stable yet in libc++. Those
|
||||
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.
|
||||
|
||||
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:
|
||||
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.
|
||||
|
||||
.. code-block:: bash
|
||||
The following features are currently considered experimental and are only provided
|
||||
when ``-fexperimental-library`` is passed:
|
||||
|
||||
$ clang++ -nostdinc++ -nostdlib++ \
|
||||
-isystem <install>/include/c++/v1 \
|
||||
-L <install>/lib \
|
||||
-Wl,-rpath,<install>/lib \
|
||||
-lc++ \
|
||||
test.cpp
|
||||
* The parallel algorithms library (``<execution>`` and the associated algorithms)
|
||||
* ``std::stop_token``, ``std::stop_source`` and ``std::stop_callback``
|
||||
* ``std::jthread``
|
||||
* ``std::chrono::tzdb`` and related time zone functionality
|
||||
|
||||
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.
|
||||
.. note::
|
||||
Experimental libraries are experimental.
|
||||
* The contents of the ``<experimental/...>`` headers and the associated static
|
||||
library will not remain compatible between versions.
|
||||
* No guarantees of API or ABI stability are provided.
|
||||
* When the standardized version of an experimental feature is implemented,
|
||||
the experimental feature is removed two releases after the non-experimental
|
||||
version has shipped. The full policy is explained :ref:`here <experimental features>`.
|
||||
|
||||
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.
|
||||
@ -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.
|
||||
- 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.
|
||||
|
||||
- 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.
|
||||
|
||||
|
||||
.. _Vendor Configuration Options:
|
||||
|
||||
Vendor Configuration Options
|
||||
============================
|
||||
|
||||
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.
|
||||
|
||||
.. 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.
|
||||
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.
|
||||
|
||||
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
|
||||
---------------------
|
||||
|
||||
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/
|
||||
|
||||
|
||||
.. _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:
|
||||
|
||||
libc++ specific options
|
||||
General purpose options
|
||||
-----------------------
|
||||
|
||||
.. option:: LIBCXX_INSTALL_LIBRARY:BOOL
|
||||
@ -305,11 +225,89 @@ libc++ specific options
|
||||
|
||||
Additional libraries libc++ is linked to which can be provided in cache.
|
||||
|
||||
.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL
|
||||
|
||||
.. _ABI Library Specific Options:
|
||||
**Default**: ``ON``
|
||||
|
||||
ABI Library Specific Options
|
||||
----------------------------
|
||||
Build libc++ with exception support.
|
||||
|
||||
.. option:: LIBCXX_ENABLE_RTTI:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Build libc++ with run time type information.
|
||||
This option may only be set to OFF when LIBCXX_ENABLE_EXCEPTIONS=OFF.
|
||||
|
||||
.. option:: LIBCXX_INCLUDE_TESTS:BOOL
|
||||
|
||||
**Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``)
|
||||
|
||||
Build the libc++ tests.
|
||||
|
||||
.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Build the libc++ benchmark tests and the Google Benchmark library needed
|
||||
to support them.
|
||||
|
||||
.. option:: LIBCXX_BENCHMARK_TEST_ARGS:STRING
|
||||
|
||||
**Default**: ``--benchmark_min_time=0.01``
|
||||
|
||||
A semicolon list of arguments to pass when running the libc++ benchmarks using the
|
||||
``check-cxx-benchmarks`` rule. By default we run the benchmarks for a very short amount of time,
|
||||
since the primary use of ``check-cxx-benchmarks`` is to get test and sanitizer coverage, not to
|
||||
get accurate measurements.
|
||||
|
||||
.. option:: LIBCXX_ASSERTION_HANDLER_FILE:PATH
|
||||
|
||||
**Default**:: ``"${CMAKE_CURRENT_SOURCE_DIR}/vendor/llvm/default_assertion_handler.in"``
|
||||
|
||||
Specify the path to a header that contains a custom implementation of the
|
||||
assertion handler that gets invoked when a hardening assertion fails. If
|
||||
provided, this header will be included by the library, replacing the
|
||||
default assertion handler. If this is specified as a relative path, it
|
||||
is assumed to be relative to ``<monorepo>/libcxx``.
|
||||
|
||||
ABI Specific Options
|
||||
--------------------
|
||||
|
||||
The following options allow building libc++ for a different ABI version.
|
||||
|
||||
.. option:: LIBCXX_ABI_VERSION:STRING
|
||||
|
||||
**Default**: ``1``
|
||||
|
||||
Defines the target ABI version of libc++.
|
||||
|
||||
.. option:: LIBCXX_ABI_UNSTABLE:BOOL
|
||||
|
||||
**Default**: ``OFF``
|
||||
|
||||
Build the "unstable" ABI version of libc++. Includes all ABI changing features
|
||||
on top of the current stable version.
|
||||
|
||||
.. option:: LIBCXX_ABI_NAMESPACE:STRING
|
||||
|
||||
**Default**: ``__n`` where ``n`` is the current ABI version.
|
||||
|
||||
This option defines the name of the inline ABI versioning namespace. It can be used for building
|
||||
custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues
|
||||
with other libc++ versions.
|
||||
|
||||
.. warning::
|
||||
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.
|
||||
|
||||
.. option:: LIBCXX_ABI_DEFINES:STRING
|
||||
|
||||
**Default**: ``""``
|
||||
|
||||
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
|
||||
|
||||
@ -360,98 +358,6 @@ ABI Library Specific Options
|
||||
|
||||
Additional libraries libc++abi is linked to which can be provided in cache.
|
||||
|
||||
|
||||
libc++ Feature Options
|
||||
----------------------
|
||||
|
||||
.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Build libc++ with exception support.
|
||||
|
||||
.. option:: LIBCXX_ENABLE_RTTI:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Build libc++ with run time type information.
|
||||
This option may only be set to OFF when LIBCXX_ENABLE_EXCEPTIONS=OFF.
|
||||
|
||||
.. option:: LIBCXX_INCLUDE_TESTS:BOOL
|
||||
|
||||
**Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``)
|
||||
|
||||
Build the libc++ tests.
|
||||
|
||||
.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL
|
||||
|
||||
**Default**: ``ON``
|
||||
|
||||
Build the libc++ benchmark tests and the Google Benchmark library needed
|
||||
to support them.
|
||||
|
||||
.. option:: LIBCXX_BENCHMARK_TEST_ARGS:STRING
|
||||
|
||||
**Default**: ``--benchmark_min_time=0.01``
|
||||
|
||||
A semicolon list of arguments to pass when running the libc++ benchmarks using the
|
||||
``check-cxx-benchmarks`` rule. By default we run the benchmarks for a very short amount of time,
|
||||
since the primary use of ``check-cxx-benchmarks`` is to get test and sanitizer coverage, not to
|
||||
get accurate measurements.
|
||||
|
||||
.. option:: LIBCXX_ASSERTION_HANDLER_FILE:PATH
|
||||
|
||||
**Default**:: ``"${CMAKE_CURRENT_SOURCE_DIR}/vendor/llvm/default_assertion_handler.in"``
|
||||
|
||||
Specify the path to a header that contains a custom implementation of the
|
||||
assertion handler that gets invoked when a hardening assertion fails. If
|
||||
provided, this header will be included by the library, replacing the
|
||||
default assertion handler. If this is specified as a relative path, it
|
||||
is assumed to be relative to ``<monorepo>/libcxx``.
|
||||
|
||||
|
||||
libc++ ABI Feature Options
|
||||
--------------------------
|
||||
|
||||
The following options allow building libc++ for a different ABI version.
|
||||
|
||||
.. option:: LIBCXX_ABI_VERSION:STRING
|
||||
|
||||
**Default**: ``1``
|
||||
|
||||
Defines the target ABI version of libc++.
|
||||
|
||||
.. option:: LIBCXX_ABI_UNSTABLE:BOOL
|
||||
|
||||
**Default**: ``OFF``
|
||||
|
||||
Build the "unstable" ABI version of libc++. Includes all ABI changing features
|
||||
on top of the current stable version.
|
||||
|
||||
.. option:: LIBCXX_ABI_NAMESPACE:STRING
|
||||
|
||||
**Default**: ``__n`` where ``n`` is the current ABI version.
|
||||
|
||||
This option defines the name of the inline ABI versioning namespace. It can be used for building
|
||||
custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues
|
||||
with other libc++ versions.
|
||||
|
||||
.. warning::
|
||||
When providing a custom namespace, it's the user'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.
|
||||
|
||||
.. option:: LIBCXX_ABI_DEFINES:STRING
|
||||
|
||||
**Default**: ``""``
|
||||
|
||||
A semicolon-separated list of ABI macros to persist in the site config header.
|
||||
See ``include/__config`` for the list of ABI macros.
|
||||
|
||||
|
||||
.. _LLVM-specific variables:
|
||||
|
||||
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
|
||||
@ -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
|
||||
================
|
||||
|
||||
This list contains known issues with libc++
|
||||
First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
|
||||
and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
|
||||
|
||||
* Building libc++ with ``-fno-rtti`` is not supported. However
|
||||
linking against it with ``-fno-rtti`` is supported.
|
||||
**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 `libc++ forum`_ or in the `libc++ chat`_.
|
||||
|
||||
A full list of currently open libc++ bugs can be `found here`__.
|
||||
**Patches**
|
||||
|
||||
.. __: https://github.com/llvm/llvm-project/labels/libc%2B%2B
|
||||
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 `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/>`_
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user