Author: Mark de Wever Date: 2022-11-10T20:20:17+01:00 New Revision: 0c111dd86fffa91fbca502fd5f8e3db28f89270a
URL: https://github.com/llvm/llvm-project/commit/0c111dd86fffa91fbca502fd5f8e3db28f89270a DIFF: https://github.com/llvm/llvm-project/commit/0c111dd86fffa91fbca502fd5f8e3db28f89270a.diff LOG: [libc++] Documents details of the pre-commit CI. This documentation aims to make it cleare how the libc++ pre-commit CI works. For libc++ developers and other LLVM projects whose changes can affect libc++. This was discusses with @aaron.ballman as a follow on some unclearities for the Clang communitee how the libc++ pre-commit CI works. Note some parts depend on patches under review as commented in the documentation. Reviewed By: ldionne, #libc, philnik Differential Revision: https://reviews.llvm.org/D133249 Added: Modified: clang/www/hacking.html libcxx/docs/Contributing.rst libcxx/docs/index.rst Removed: ################################################################################ diff --git a/clang/www/hacking.html b/clang/www/hacking.html index 1128a5553b82a..55c4f0f9f5cf6 100755 --- a/clang/www/hacking.html +++ b/clang/www/hacking.html @@ -30,6 +30,7 @@ <h1>Hacking on Clang</h1> <li><a href="#testingNonWindows">Testing on Unix-like Systems</a></li> <li><a href="#testingWindows">Testing using Visual Studio on Windows</a></li> <li><a href="#testingCommands">Testing on the Command Line</a></li> + <li><a href="#testingLibc++">Testing changes affecting libc++</a></li> </ul> </li> <li><a href="#patches">Creating Patch Files</a></li> @@ -271,6 +272,41 @@ <h3 id="testingCommands">Testing on the Command Line</h3> <p>The statistic, "Failed" (not shown if all tests pass), is the important one.</p> + <!--=====================================================================--> + <h3 id="testingLibc++">Testing changes affecting libc++</h3> + <!--=====================================================================--> + + <p>Some changes in Clang affect <a href="https://libcxx.llvm.org";>libc++</a>, + for example:</p> + <ul> + <li>Changing the output of Clang's diagnostics.</li> + <li>Changing compiler builtins, especially the builtins used for type traits + or replacements of library functions like <tt>std::move</tt> or + <tt>std::forward</tt>.</li> + </ul> + + <p>After adjusting libc++ to work with the changes, the next revision will be + tested by libc++'s + <a href="https://buildkite.com/llvm-project/libcxx-ci";>pre-commit CI</a>. + + <p>For most configurations, the pre-commit CI uses a recent + <a href="https://apt.llvm.org/";>nightly build</a> of Clang from LLVM's main + branch. These configurations do <em>not</em> use the Clang changes in the + patch. They only use the libc++ changes.</p> + + <p>The "Bootstrapping build" builds Clang and uses it to build and + test libc++. This build <em>does</em> use the Clang changes in the patch.</p> + + <p>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.</p> + + <p>Libc++ has more + <a href="https://libcxx.llvm.org/Contributing.html#pre-commit-ci";> + documentation</a> about the pre-commit CI. For questions regarding + libc++, the best place to ask is the <tt>#libcxx</tt> channel on + <a href="https://discord.gg/jzUbyP26tQ";>LLVM's Discord server</a>.</p> + <!--=====================================================================--> <h2 id="patches">Creating Patch Files</h2> <!--=====================================================================--> diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst index 15c75e8c51681..faa904c4ba1f6 100644 --- a/libcxx/docs/Contributing.rst +++ b/libcxx/docs/Contributing.rst @@ -84,5 +84,136 @@ updated list from the failed build at 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++<version>. +* MacOS X86_64 and MacOS arm64 for the Apple platform. + + +Pre-commit CI +============= + +Introduction +------------ + +Unlike most parts of the LLVM project, libc++ uses a pre-commit CI [#]_. This +CI is hosted on `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__ and +the build results are visible in the review on Phabricator. Please make sure +the CI is green before committing a patch. + +The CI tests libc++ for all :ref:`supported platforms <SupportedPlatforms>`. +The build is started for every diff uploaded to Phabricator. 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 <https://apt.llvm.org>`__ 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 configurations: + +* use a nightly build of the ``main`` branch of Clang, +* execute the tests using the language C++<latest>. This is the version + "developed" by the C++ committee. + +.. note:: Updating the Clang nightly builds in the Docker image is a manual + process and is done at an irregular interval on purpose. When you need to + have the latest nightly build to test recent Clang changes, ask in the + ``#libcxx`` channel on `LLVM's Discord server + <https://discord.gg/jzUbyP26tQ>`__. + +.. [#] There's `LLVM Dev Meeting talk <https://www.youtube.com/watch?v=B7gB6van7Bw>`__ + explaining the benefits of libc++'s pre-commit CI. + +Builds +------ + +Below is 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++<version>`` these build steps test the various C++ versions, making sure all + C++ language versions work with the changes made. +* ``Clang <version>`` 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 a crash occurs in this build, the crash reproducer is available as an + artifact. + +* ``Modular build`` tests libc++ using Clang modules [#]_. +* ``GCC <version>`` 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 focused. This is +the platform used by most of libc++'s Buildkite runners and developers. + +Dockerfile +~~~~~~~~~~ + +Contains the Docker image for the Ubuntu CI. Because 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. + +run-buildbot-container +~~~~~~~~~~~~~~~~~~~~~~ + +Helper script that pulls and runs the Docker image. This image mounts the LLVM +monorepo 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 ``<llvm-root>/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 diff erent 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 + + CC=clang-14 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 diff ers between the +``main`` and ``release`` branch, both branches can use diff erent compiler +versions. diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst index f38d77f896082..b04f421576d33 100644 --- a/libcxx/docs/index.rst +++ b/libcxx/docs/index.rst @@ -93,6 +93,7 @@ reasons, but some of the major ones are: 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 ============================= _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
