diff --git a/clang/www/hacking.html b/clang/www/hacking.html --- a/clang/www/hacking.html +++ b/clang/www/hacking.html @@ -30,6 +30,7 @@
  • Testing on Unix-like Systems
  • Testing using Visual Studio on Windows
  • Testing on the Command Line
    • +
  • Testing changes affecting libcxx
  • Creating Patch Files
    • @@ -271,6 +272,51 @@

    The statistic, "Failed" (not shown if all tests pass), is the important one.

    + +

    Testing changes affecting libcxx

    + + +

    Some changes in Clang affect libc++, + for example:

    + + +

    Libc++ has its own + testing guide. A better way to test whether changes work properly in + libc++, is to use libc++'s + pre-commit CI. + This can simply be done by adding a dummy file in the libcxx directory before + submitting or updating a patch in Phabricator. This change in the libxx + directory will cause the update of the diff to start a CI run. This dummy + file will also add the libc++ group to the list of reviewers. The status of + the build will be available in Phabricator.

    + +

    Using the libc++ pre-commit CI is an opt-in, since the pre-commit + CI lacks the resources to build every Clang diff. A single run takes about + one hour. Secondly most changes of Clang won't affect libc++. + +

    For most builds, the pre-commit CI uses a recent + nightly build of Clang from LLVM's main + branch. These builds do not use the Clang changes in the patch. They + only use the libc++ changes.

    + +

    The "Bootstrapping build" builds Clang and uses it to build and + test libc++. This build does use the Clang changes in the patch.

    + +

    Unlike Clang, libc++ supports multiple versions of Clang. Therefore when a + patch changes the diagnostics it might be required to use a regex in the + "expected" tests to make it pass the CI.

    + +

    Libc++ has more + + documentation about the pre-commit CI. When having questions regarding + libc++, best ask them in the #libcxx channel on + LLVM's Discord server.

    +

    Creating Patch Files

    diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst --- a/libcxx/docs/Contributing.rst +++ b/libcxx/docs/Contributing.rst @@ -84,5 +84,158 @@ Look for the failed build and select the ``artifacts`` tab. There, download the abilist for the platform, e.g.: -* C++20 for the Linux platform. -* MacOS C++20 for the Apple platform. +* C++XX for the Linux platform (where XX is the latest C++ version). +* MacOS X86_64 and MacOS arm64 for the Apple platform. + + +.. comments The new part got longer than expected, would it make sense to move + it to its own page? + + +Pre-commit CI +============= + +Introduction +------------ + +Unlike eost parts of the LLVM project, libc++ uses a pre-commit CI [#]_. This +CI is hosted on `Buildkite `__ and +the build results are visible in the review on Phabricator. Before committing a +patch please make sure the CI is green. + + +The CI tests libc++ for all :ref:`supported platforms `. +The build is started for every diff uploaded. A complete CI run takes +approximately one hour. To reduce the load: + +* The build is cancelled when a new diff for the same revision is uploaded. +* The build is done in several stages and cancelled when a stage fails. + +Typically the libc++ jobs use a Ubuntu Docker image. This image contains +recent `nightly builds `__ of all supported versions of +Clang and the current version of the ``main`` branch. These versions of Clang +are used to build libc++ and execute its tests. + +Unless specified otherwise the ``main`` version of Clang is used. + +Unless specified otherwise the tests are executed for the latest C++ +version; this is the version being "developed" by the C++ committee. CI runners +using this language version will produce an artifact with a graphviz dot file +containing the internal dependencies of the Standard headers in libc++. + +.. comments D133127 adds the artifact + + +.. note:: Updating the Clang nightly builds in the Docker image is a manual + process and is done at an irregular interval. When you need to have the + latest nightly build to test recent Clang changes best ask at the + ``#libcxx`` channel on + `LLVM's Discord server `__. + +.. comments ``irregular`` is used on purpose. Committing to a schedule seems + unwanted; people might be unavailable to update the image, the nightly + builds fail and are not uploaded for multiple days (this is not uncommon). + +.. [#] There's `Dev meeting talk `__ + explaining the benefits of libc++'s pre-commit CI. + +Builds +------ + +Below a short description of the most interesting CI builds [#]_: + +* ``Format`` runs ``clang-format`` and uploads its output as an artifact. At the + moment this build is a soft error and doesn't fail the build. +* ``Generated output`` runs the ``libcxx-generate-files`` build target and + tests for non-ASCII characters in libcxx. Some files are excluded since they + use Unicode, mainly tests. The output of these commands are uploaded as + artifact. +* ``Documentation`` builds the documentation. (This is done early in the build + process since it is cheap to run.) +* ``C++XX`` these build steps test the various C++ versions, making sure all + C++ language versions work with the changes made. +* ``Clang XX`` these build steps test whether the changes work with all + supported Clang versions. +* ``Booststrapping build`` builds Clang using the revision of the patch and + uses that Clang version to build and test libc++. This validates the current + Clang and lib++ are compatible. When making changes in Clang that affect + libc++ this is the build to validate all is well. + + When this buld fails with an LLVM assertion, the crash diagnostics are + available as an artifact. + + .. comments D133082 adds the artifact +* ``Modular build`` tests libc++ using Clang modules [#]_. +* ``GCC XX`` tests libc++ with the latest stable GCC version. Only C++11 + and the latest C++ version are tested. +* ``Santitizers`` tests libc++ using the Clang sanitizers. +* ``Parts disabled`` tests libc++ with certain libc++ features disabled. +* ``Windows`` tests libc++ using MinGW and clang-cl. +* ``Apple`` tests libc++ on MacOS. +* ``ARM`` tests libc++ on various Linux ARM platforms. +* ``AIX`` tests libc++ on AIX. + +.. [#] Not all all steps are listed: steps are added and removed when the need + arises. +.. [#] Clang modules are not the same as C++20's modules. + +Infrastructure +-------------- + +All files of the CI infrastructure are in the directory ``libcxx/utils/ci``. +Note that quite a bit of this infrastructure is heavily Linux focussed. This is +the platform used by most of libc++'s Buildkite runners and developers. Patches +for other platforms are welcome. + +Dockerfile +~~~~~~~~~~ + +Contains the Docker image for the Ubuntu CI. Since the same Docker image is +used for the ``main`` and ``release`` branch it should contain no hard-coded +versions [#]_. It contains the used versions of Clang, various clang-tools, +GCC, and CMake. + +.. note:: This image is pulled from Docker hub and not rebuild when changing + the Dockerfile. + +.. [#] Currently it contains hard-coded versions using symlinks. They will be + removed after LLVM 16 has branched. Removing them before that time risks + breaking the CI of the release branch. + +run-buildbot-container +~~~~~~~~~~~~~~~~~~~~~~ + +Helper script that pulls and runs the Docker image. This image mounts the LLVM +monorepository at ``/llvm``. This can be used to test with compilers not +available on your system. + +run-buildbot +~~~~~~~~~~~~ + +Contains the buld script executed on Buildkite. This script can be executed +locally or inside ``run-buildbot-container``. The script must be called with +the target to test. For example, ``run-buildbot generic-cxx20`` will build +libc++ and test it using C++20. + +.. warning:: This script will overwrite the directory ``/build/XX`` + where ``XX`` is the target of ``run-buildbot``. + +This script contains as little version information as possible. This makes it +easy to use the script with a different compiler. This allows testing a +combination not in the libc++ CI. It can be used to add a new (temporary) +job to the CI. For example, testing the C++17 build with Clang-14 can be done +like: + +.. code-block:: bash + + export CC=clang-14 + export CXX=clang++-14 + run-buildbot generic-cxx17 + +buildkite-pipeline.yml +~~~~~~~~~~~~~~~~~~~~~~ + +Contains the jobs executed in the CI. This file contains the version +information of the jobs being executed. Since this script differs between the +``main`` and ``release`` branch, both branches can use different compiler +versions. diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst --- a/libcxx/docs/index.rst +++ b/libcxx/docs/index.rst @@ -93,6 +93,7 @@ Further, both projects are apparently abandoned: STLport 5.2.1 was released in Oct'08, and STDCXX 4.2.1 in May'08. +.. _SupportedPlatforms: Platform and Compiler Support =============================