forked from OSchip/llvm-project
[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
This commit is contained in:
Mark de Wever
parent
b57819e130
commit
0c111dd86f
|
|
@ -30,6 +30,7 @@
|
|||
<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 @@ Testing Time: 81.52s
|
|||
|
||||
<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>
|
||||
<!--=====================================================================-->
|
||||
|
|
|
|||
|
|
@ -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 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
|
||||
|
||||
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 differs between the
|
||||
``main`` and ``release`` branch, both branches can use different compiler
|
||||
versions.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
=============================
|
||||
|
|
|
|||
Loading…
Reference in New Issue