[libcxx-commits] [libcxx] 2ce0df4 - [libc++][docs] Overhaul the documentation for building and using libc++
Louis Dionne via libcxx-commits
libcxx-commits at lists.llvm.org
Tue Jul 6 11:09:19 PDT 2021
Author: Louis Dionne
Date: 2021-07-06T14:09:14-04:00
New Revision: 2ce0df4dfbead9eb0a91861c529910940c87593b
URL: https://github.com/llvm/llvm-project/commit/2ce0df4dfbead9eb0a91861c529910940c87593b
DIFF: https://github.com/llvm/llvm-project/commit/2ce0df4dfbead9eb0a91861c529910940c87593b.diff
LOG: [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.
Added:
Modified:
libcxx/docs/BuildingLibcxx.rst
libcxx/docs/UsingLibcxx.rst
libcxx/docs/index.rst
libcxx/utils/ci/run-buildbot
Removed:
################################################################################
diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/BuildingLibcxx.rst
index c44ab9d1fbecd..629e4c8355ba5 100644
--- a/libcxx/docs/BuildingLibcxx.rst
+++ b/libcxx/docs/BuildingLibcxx.rst
@@ -9,68 +9,69 @@ Building libc++
.. _build instructions:
-Getting Started
-===============
+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>`.
-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.
+.. warning::
+ 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 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 default build
+=================
-.. 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``.
+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
-
-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.
-
-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++.
-
-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.
-
-It is possible to build libc++ standalone (i.e. without building other LLVM
-projects). A standalone build would look like this:
+ $ 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
+
+.. note::
+ See :ref:`CMake Options` below for more configuration options.
+
+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.
+
+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.
+
+
+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
diff --git a/libcxx/docs/UsingLibcxx.rst b/libcxx/docs/UsingLibcxx.rst
index b967c986165e8..863123688e6a9 100644
--- a/libcxx/docs/UsingLibcxx.rst
+++ b/libcxx/docs/UsingLibcxx.rst
@@ -1,3 +1,5 @@
+.. _using-libcxx:
+
============
Using libc++
============
@@ -5,138 +7,118 @@ Using libc++
.. contents::
:local:
-Getting Started
-===============
-
-If you already have libc++ installed you can use it with clang.
-
-.. code-block:: bash
-
- $ clang++ -stdlib=libc++ test.cpp
- $ clang++ -std=c++11 -stdlib=libc++ test.cpp
-
-On macOS and FreeBSD libc++ is the default standard library
-and the ``-stdlib=libc++`` is not required.
+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.
-.. _alternate libcxx:
-
-If you want to select an alternate installation of libc++ you
-can use the following options.
-
-.. code-block:: bash
+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.
- $ 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.
+Using a
diff erent version of the C++ Standard
+=============================================
-An example of using ``LD_LIBRARY_PATH``:
+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++ -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>``
-======================
+ $ clang++ -std=c++17 test.cpp
-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.
+.. 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.
-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.
-.. code-block:: bash
- $ clang++ -stdlib=libc++ test.cpp -lc++abi
+.. _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:
-Using libc++ with GCC
----------------------
+.. code-block:: bash
-GCC does not provide a way to switch from libstdc++ to libc++. You must manually
-configure the compile and link commands.
+ $ clang++ -nostdinc++ -nostdlib++ \
+ -isystem <install>/include/c++/v1 \
+ -L <install>/lib \
+ -Wl,-rpath,<install>/lib \
+ -lc++ \
+ test.cpp
-In particular, you must tell GCC to remove the libstdc++ include directories
-using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``.
+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 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
=================
diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst
index c9a589baeb81a..0b27361312b28 100644
--- a/libcxx/docs/index.rst
+++ b/libcxx/docs/index.rst
@@ -32,7 +32,7 @@ Getting Started with libc++
---------------------------
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
ReleaseNotes
UsingLibcxx
diff --git a/libcxx/utils/ci/run-buildbot b/libcxx/utils/ci/run-buildbot
index d076f5fd96d9c..da4121cb900af 100755
--- a/libcxx/utils/ci/run-buildbot
+++ b/libcxx/utils/ci/run-buildbot
@@ -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
More information about the libcxx-commits
mailing list