diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/BuildingLibcxx.rst index c44ab9d1fbecd6..629e4c8355ba5b 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 `. -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 -`_ documentation. - -Shared libraries for libc++ and libc++ abi should now be present in -``build/lib``. See :ref:`using an alternate libc++ installation ` 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++ ` 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 ``/lib``, and +headers in ``/include/c++/v1``. See :ref:`using an alternate +libc++ installation ` 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="" + $ 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 `_. -.. _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 \ - + $ 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 \ - - $ 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 b967c986165e8d..863123688e6a95 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/include/c++/v1 \ - -L/lib \ - -Wl,-rpath,/lib \ - test.cpp -The option ``-Wl,-rpath,/lib`` adds a runtime library -search path. Meaning that the systems dynamic linker will look for libc++ in -``/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 different 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/include/c++/v1 - -L/lib \ - test.cpp -o - $ ./a.out # Searches for libc++ in the systems library paths. - $ export LD_LIBRARY_PATH=/lib - $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH - -Using ```` -====================== + $ 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 ```` and ```` -are required to link ``-lc++fs``. Prior to libc++ 7.0, users of -```` 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 ```` is provided in the main -library and nothing special is required to use ````. Using libc++experimental and ```` -===================================================== +=================================================== Libc++ provides implementations of experimental technical specifications in a separate library, ``libc++experimental.a``. Users of ```` -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++ ` and -:ref:`libc++experimental CMake Options `. - -Also see the `Experimental Library Implementation Status `__ -page. + $ clang++ test.cpp -lc++experimental .. warning:: Experimental libraries are Experimental. * The contents of the ```` 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 `. -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 /include/c++/v1 \ + -L /lib \ + -Wl,-rpath,/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,/lib`` adds a runtime library search path, +which causes the system's dynamic linker to look for libc++ in ``/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/include/c++/v1 \ - test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc + $ g++ -nostdinc++ -nodefaultlibs \ + -isystem /include/c++/v1 \ + -L /lib \ + -Wl,-rpath,/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 `_. + $ gdb -ex "source /utils/gdb/libcxx/printers.py" \ + -ex "python register_libcxx_printer_loader()" \ + 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 c9a589baeb81ac..0b27361312b281 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 d076f5fd96d9ca..da4121cb900af5 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