maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

[libc++][docs] Overhaul the documentation for building and using libc++ 

This patch overhauls the documentation around building libc++
for vendors, and using libc++ for end-users. It also:

- Removes mention of the standalone build, which we've been trying to
  get rid of for a long time.
- Removes mention of using a local ABI installation, which we don't do
  and is documented as "not recommended".
- Removes mention of the separate libc++filesystem.a library, which isn't
  relevant anymore since filesystem support is in the main library.
- Adds mention of the GDB pretty printers and how to use them.
This commit is contained in:
Louis Dionne 2021-07-06 10:39:01 -04:00
parent 7b6b15e010
commit 2ce0df4dfb
4 changed files with 156 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
libcxx/docs/BuildingLibcxx.rst
View File

@ -9,68 +9,69 @@ Building libc++
.. _build instructions:
Getting Started
===============
On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install
Xcode 4.2 or later. However if you want to install tip-of-trunk from here
(getting the bleeding edge), read on.
The following instructions describe how to checkout, build, test and
(optionally) install libc++ and libc++abi.
If your system already provides a libc++ installation it is important to be
careful not to replace it. Remember Use the CMake option
``CMAKE_INSTALL_PREFIX`` to select a safe place to install libc++.
The instructions on this page are aimed at vendors who ship libc++ as part of an
operating system distribution, a toolchain or similar shipping vehicules. 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>`.
.. warning::
* Replacing your systems libc++ installation could render the system non-functional.
* macOS will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``.
If your operating system already provides libc++, it is important to be careful
not to replace it. Replacing your system's libc++ installation could render it
non-functional. Use the CMake option ``CMAKE_INSTALL_PREFIX`` to select a safe
place to install libc++.
The default build
=================
By default, libc++ and libc++abi are built as sub-projects of the LLVM project.
This can be achieved with the usual CMake invocation:
.. code-block:: bash
$ git clone https://github.com/llvm/llvm-project.git
$ cd llvm-project
$ mkdir build && cd build
$ cmake -DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
-DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" \
../llvm
$ make # Build
$ make check-cxx # Test
$ make install-cxx install-cxxabi # Install
$ mkdir build
$ cmake -G Ninja -S llvm -B build -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" # Configure
$ ninja -C build cxx cxxabi # Build
$ ninja -C build check-cxx check-cxxabi # Test
$ ninja -C build install-cxx install-cxxabi # Install
For more information about configuring libc++ see :ref:`CMake Options`. You may
also want to read the `LLVM getting started
<https://llvm.org/docs/GettingStarted.html>`_ documentation.
.. note::
See :ref:`CMake Options` below for more configuration options.
Shared libraries for libc++ and libc++ abi should now be present in
``build/lib``. See :ref:`using an alternate libc++ installation <alternate
libcxx>` for information on how to use this libc++.
After building the ``install-cxx`` and ``install-cxxabi`` targets, shared libraries
for libc++ and libc++abi 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.
The instructions are for building libc++ on
FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library.
On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt.
In the default configuration, libc++ and libc++abi will be built using the compiler available
by default on your system. It is also possible to bootstrap Clang and build libc++ with it.
It is possible to build libc++ standalone (i.e. without building other LLVM
projects). A standalone build would look like this:
Bootstrapping build
===================
It is also possible to build Clang and then build libc++ and libc++abi using that
just-built compiler. This is the correct way to build libc++ when putting together
a toolchain, or when the system compiler is not adequate to build libc++ (too old,
unsupported, etc.). This type of build is also commonly called a "Runtimes build":
.. code-block:: bash
$ git clone https://github.com/llvm/llvm-project.git llvm-project
$ cd llvm-project
$ mkdir build && cd build
$ cmake -DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
-DLIBCXX_CXX_ABI=libcxxabi \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/separate/libcxxabi/include \
../libcxx
$ make
$ make check-cxx # optional
$ mkdir build
$ cmake -G Ninja -S llvm -B build -DLLVM_ENABLE_PROJECTS="clang" \ # Configure
-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \
-DLLVM_RUNTIME_TARGETS="<target-triple>"
$ ninja -C build runtimes # Build
$ ninja -C build check-runtimes # Test
$ ninja -C build install-runtimes # Install
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
@ -79,23 +80,22 @@ 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" ^
-T "ClangCL" ^
-DLIBCXX_ENABLE_SHARED=YES ^
-DLIBCXX_ENABLE_STATIC=NO ^
-DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^
\path\to\libcxx
> cmake --build .
> cmake -G "Visual Studio 16 2019" -S libcxx -B build ^
-T "ClangCL" ^
-DLIBCXX_ENABLE_SHARED=YES ^
-DLIBCXX_ENABLE_STATIC=NO ^
-DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=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
@ -119,14 +119,12 @@ In either case, then run:
.. code-block:: batch
> cmake -G Ninja ^
-DCMAKE_BUILD_TYPE=Release ^
> cmake -G Ninja -S libcxx -B build ^
-DCMAKE_C_COMPILER=clang-cl ^
-DCMAKE_CXX_COMPILER=clang-cl ^
-DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^
path/to/libcxx
> ninja cxx
> ninja check-cxx
-DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO
> 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
@ -139,7 +137,7 @@ Also note that if not building in Release mode, a failed assert in the tests
pops up a blocking dialog box, making it hard to run a larger number of tests.
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
@ -147,16 +145,15 @@ e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja.
.. code-block:: bash
> cmake -G Ninja \
> cmake -G Ninja -S libcxx -B build \
-DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
-DLIBCXX_HAS_WIN32_THREAD_API=ON \
-DLIBCXX_CXX_ABI=libstdc++ \
-DLIBCXX_TARGET_INFO="libcxx.test.target_info.MingwLocalTI" \
path/to/libcxx
> ninja cxx
-DLIBCXX_TARGET_INFO="libcxx.test.target_info.MingwLocalTI"
> ninja -C build cxx
> cp /mingw64/bin/{libstdc++-6,libgcc_s_seh-1,libwinpthread-1}.dll lib
> ninja check-cxx
> ninja -C build check-cxx
As this build configuration ends up depending on a couple other DLLs that
aren't available in path while running tests, copy them into the same
@ -443,8 +440,12 @@ LLVM-specific options
Using Alternate ABI libraries
=============================
In order to implement various features like exceptions, RTTI, ``dynamic_cast`` and
more, libc++ requires what we refer to as an ABI library. Typically, that library
implements the `Itanium C++ ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_.
.. _libsupcxx:
By default, libc++ uses libc++abi as an ABI library. However, it is possible to use
other ABI libraries too.
Using libsupc++ on Linux
------------------------
@ -474,17 +475,17 @@ You can also figure this out by running
End of search list.
Note that the first two entries happen to be what we are looking for. This
may not be correct on other platforms.
may not be correct on all platforms.
We can now run CMake:
.. code-block:: bash
$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \
-DLIBCXX_CXX_ABI=libstdc++ \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \
-DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \
<libc++-source-dir>
$ cmake -G Ninja -S llvm -B build \
-DLLVM_ENABLE_PROJECTS="libcxx" \
-DLIBCXX_CXX_ABI=libstdc++ \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
$ ninja -C build install-cxx
You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++``
@ -495,16 +496,6 @@ GCC ships libsupc++ separately but only as a static library. If a
program also needs to link against libstdc++, it will provide its
own copy of libsupc++ and this can lead to subtle problems.
.. code-block:: bash
$ make cxx
$ make install
You can now run clang with -stdlib=libc++.
.. _libcxxrt_ref:
Using libcxxrt on Linux
------------------------
@ -516,14 +507,11 @@ We can now run CMake like:
.. code-block:: bash
$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \
-DLIBCXX_CXX_ABI=libcxxrt \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
<libc++-source-directory>
$ make cxx
$ make install
$ cmake -G Ninja -S llvm -B build \
-DLLVM_ENABLE_PROJECTS="libcxx" \
-DLIBCXX_CXX_ABI=libcxxrt \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src
$ ninja -C build install-cxx
Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as
clang is set up to link for libc++ linked to libsupc++. To get around this
@ -541,32 +529,4 @@ situations will give the same result:
$ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt
.. _`libcxxrt`: https://github.com/pathscale/libcxxrt/
Using a local ABI library installation
---------------------------------------
.. warning::
This is not recommended in almost all cases.
These instructions should only be used when you can't install your ABI library.
Normally you must link libc++ against a ABI shared library that the
linker can find. If you want to build and test libc++ against an ABI
library not in the linker's path you need to set
``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake.
An example build using libc++abi would look like:
.. code-block:: bash
$ CC=clang CXX=clang++ cmake \
-DLIBCXX_CXX_ABI=libc++abi \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \
-DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \
path/to/libcxx
$ make
When testing libc++ LIT will automatically link against the proper ABI
library.
.. _`libcxxrt`: https://github.com/libcxxrt/libcxxrt

165
libcxx/docs/UsingLibcxx.rst
View File

@ -1,3 +1,5 @@
.. _using-libcxx:
============
Using libc++
============
@ -5,138 +7,118 @@ Using libc++
.. contents::
:local:
Getting Started
===============
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.
If you already have libc++ installed you can use it with clang.
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.
Using a different version of the C++ Standard
=============================================
Libc++ implements the various versions of the C++ Standard. Changing the version of
the standard can be done by passing ``-std=c++XY`` to the compiler. Libc++ will
automatically detect what Standard is being used and will provide functionality that
matches that Standard in the library.
.. code-block:: bash
$ clang++ -stdlib=libc++ test.cpp
$ clang++ -std=c++11 -stdlib=libc++ test.cpp
$ clang++ -std=c++17 test.cpp
On macOS and FreeBSD libc++ is the default standard library
and the ``-stdlib=libc++`` is not required.
.. 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.
.. _alternate libcxx:
If you want to select an alternate installation of libc++ you
can use the following options.
.. code-block:: bash
$ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \
-I<libcxx-install-prefix>/include/c++/v1 \
-L<libcxx-install-prefix>/lib \
-Wl,-rpath,<libcxx-install-prefix>/lib \
test.cpp
The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library
search path. Meaning that the systems dynamic linker will look for libc++ in
``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the
environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on macOS) can
be used to change the dynamic linkers search paths after a program is compiled.
An example of using ``LD_LIBRARY_PATH``:
.. code-block:: bash
$ clang++ -stdlib=libc++ -nostdinc++ \
-I<libcxx-install-prefix>/include/c++/v1
-L<libcxx-install-prefix>/lib \
test.cpp -o
$ ./a.out # Searches for libc++ in the systems library paths.
$ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib
$ ./a.out # Searches for libc++ along LD_LIBRARY_PATH
Using ``<filesystem>``
======================
Prior to LLVM 9.0, libc++ provides the implementation of the filesystem library
in a separate static library. Users of ``<filesystem>`` and ``<experimental/filesystem>``
are required to link ``-lc++fs``. Prior to libc++ 7.0, users of
``<experimental/filesystem>`` were required to link libc++experimental.
Starting with LLVM 9.0, support for ``<filesystem>`` is provided in the main
library and nothing special is required to use ``<filesystem>``.
Using libc++experimental and ``<experimental/...>``
=====================================================
===================================================
Libc++ provides implementations of experimental technical specifications
in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>``
headers may be required to link ``-lc++experimental``.
headers may be required to link ``-lc++experimental``. Note that not all
vendors ship ``libc++experimental.a``, and as a result, you may not be
able to use those experimental features.
.. code-block:: bash
$ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental
Libc++experimental.a may not always be available, even when libc++ is already
installed. For information on building libc++experimental from source see
:ref:`Building Libc++ <build instructions>` and
:ref:`libc++experimental CMake Options <libc++experimental options>`.
Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__
page.
$ clang++ test.cpp -lc++experimental
.. warning::
Experimental libraries are Experimental.
* The contents of the ``<experimental/...>`` headers and ``libc++experimental.a``
library will not remain compatible between versions.
* No guarantees of API or ABI stability are provided.
* When we implement the standardized version of an experimental feature,
* 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>`.
Using libc++ on Linux
=====================
On Linux libc++ can typically be used with only '-stdlib=libc++'. However
some libc++ installations require the user manually link libc++abi themselves.
If you are running into linker errors when using libc++ try adding '-lc++abi'
to the link line. For example:
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 -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
$ clang++ -stdlib=libc++ test.cpp
Alternately, you could just add libc++abi to your libraries list, which in
most situations will give the same result:
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++ -stdlib=libc++ test.cpp -lc++abi
$ 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.
Using libc++ with GCC
---------------------
GCC does not provide a way to switch from libstdc++ to libc++. You must manually
configure the compile and link commands.
In particular, you must tell GCC to remove the libstdc++ include directories
using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``.
Note that ``-nodefaultlibs`` removes all the standard system libraries and
not just libstdc++ so they must be manually linked. For example:
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++ -I<libcxx-install-prefix>/include/c++/v1 \
test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
$ 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. Unfortunately
libc++ does not provide pretty-printers itself. However there are 3rd
party implementations available and although they are not officially
supported by libc++ they may be useful to users.
GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does
provide pretty-printers itself. Those can be used as:
Known 3rd Party Implementations Include:
.. code-block:: bash
* `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_.
$ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \
-ex "python register_libcxx_printer_loader()" \
<args>
Libc++ Configuration Macros
@ -267,9 +249,10 @@ C++20 Specific Configuration Macros:
This macro is used to re-enable `raw_storage_iterator`.
**_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**:
This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,
This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,
`result_of` and `result_of_t`.
Libc++ Extensions
=================

2
libcxx/docs/index.rst
View File

@ -32,7 +32,7 @@ Getting Started with libc++
---------------------------
.. toctree::
:maxdepth: 2
:maxdepth: 1
ReleaseNotes
UsingLibcxx

2
libcxx/utils/ci/run-buildbot
View File

@ -469,7 +469,7 @@ runtimes-build)
${NINJA} -C "${BUILD_DIR}" check-runtimes
echo "--- Installing libc++ and libc++abi to a fake location"
${NINJA} -C "${BUILD_DIR}" install-cxx install-cxxabi
${NINJA} -C "${BUILD_DIR}" install-runtimes
;;
legacy-test-config)
export CC=clang