[clang] 0c111dd - [libc++] Documents details of the pre-commit CI.
Mark de Wever via cfe-commits
cfe-commits at lists.llvm.org
Thu Nov 10 11:20:23 PST 2022
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
=============================
More information about the cfe-commits
mailing list