[libcxx] Update testing documentation about CI container images. #149192

cmtice · 2025-07-16T21:45:27Z

Add information to the libcxx testing documentation, about the names of the new CI libcxx runner sets, their current values, and how to change the values or the runner set being used.

Add information to the libcxx testing documentation, about the names of the for the new CI libcxx runner sets, their current values, and how to change the values or the runner set being used.

llvmbot · 2025-07-16T22:06:39Z

@llvm/pr-subscribers-libcxx

Author: None (cmtice)

Changes

Add information to the libcxx testing documentation, about the names of the new CI libcxx runner sets, their current values, and how to change the values or the runner set being used.

Full diff: https://github.com/llvm/llvm-project/pull/149192.diff

1 Files Affected:

(modified) libcxx/docs/TestingLibcxx.rst (+37)

diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst
index 56cf4aca236f9..d278e18093e87 100644
--- a/libcxx/docs/TestingLibcxx.rst
+++ b/libcxx/docs/TestingLibcxx.rst
@@ -139,6 +139,43 @@ Also note that the Docker container shares the same filesystem as your local mac
 modifying files on your local machine will also modify what the Docker container sees.
 This is useful for editing source files as you're testing your code in the Docker container.
 
+Updating the CI testing container images
+----------------------------------------
+
+The libcxx linux premerge testing can run on one of three sets of
+runner groups. The three runner group names are
+"llvm-premerge-libcxx-runners", "llvm-premerge-libcxx-release-runners"
+or "llvm-premerge-libcxx-next-runners".  Which runner set to use is
+controlled by the contents of https://github.com/llvm/llvm-project/blob/main/.github/workflows/libcxx-build-and-test.yaml . By default, it uses
+"llvm-premerge-libcxx-runners". To switch to one of the other runner
+sets, just replace all uses of "llvm-premerge-libcxx-runners" in the yaml
+file with the desired runner set.
+
+Which container image is used by these three runner sets is controlled
+and set by the variable values in
+https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf.
+The table below shows the variable names, their current values, and
+the runner sets to which they correspond.
+
++------------------------------------+---------------------------+--------------------------------------------------------------------------+
+|Runner Set                          |Variable                   |Image Value                                                               |
++====================================+===========================+==========================================================================+
+|llvm-premerge-libcxx-runners        |libcxx_runner_image        |ghcr.io/llvm/libcxx-linux-builder:16f046281bf1a11d344eac1bc44d11f3e50e3b5d|
++------------------------------------+---------------------------+--------------------------------------------------------------------------+
+|llvm-premerge-libcxx-release-runners|libcxx_release_runner_image|ghcr.io/llvm/libcxx-linux-builder:16f046281bf1a11d344eac1bc44d11f3e50e3b5d|
++------------------------------------+---------------------------+--------------------------------------------------------------------------+
+|llvm-premerge-libcxx-next-runners   |libcxx_next_runner_image   |ghcr.io/llvm/libcxx-linux-builder:16f046281bf1a11d344eac1bc44d11f3e50e3b5d|
++------------------------------------+---------------------------+--------------------------------------------------------------------------+
+
+Note: The three runner images are (temporarily) all the same, but that
+will not normally be the case.
+
+To change the container image, the variable.tf file in llvm-zorg must
+be changed. Once that change has been merged, an llvm-zorg
+administrator must use terraform to apply the change to the running
+GKE cluster.
+
+
 Writing Tests
 =============

boomanaiden154 · 2025-07-16T22:07:56Z

libcxx/docs/TestingLibcxx.rst

+Which container image is used by these three runner sets is controlled
+and set by the variable values in
+https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf.
+The table below shows the variable names, their current values, and


Do we want to have the current values here or refer the reader to the SoT (variables.tf in llvm-zorg?). Having the duplication, especially across repos I think is going to mean the docs are frequently out of date.

I agree, we should strive to have a single source of truth (and have that source of truth be in the monorepo).

Ok, if we only want a single source of truth, though, it's going to have to be in llvm-zorg. We can put a link to it in the monorepo.

boomanaiden154 · 2025-07-16T22:09:50Z

libcxx/docs/TestingLibcxx.rst

+Note: The three runner images are (temporarily) all the same, but that
+will not normally be the case.
+
+To change the container image, the variable.tf file in llvm-zorg must


We probably want instructions here on how to modify libcxx/utils/ci/docker-compose.yml (maybe post #148073) to bump the container version along with how the runner binary can be bumped separately.

ldionne · 2025-07-18T15:05:37Z

libcxx/docs/TestingLibcxx.rst

@@ -139,6 +139,43 @@ Also note that the Docker container shares the same filesystem as your local mac
 modifying files on your local machine will also modify what the Docker container sees.
 This is useful for editing source files as you're testing your code in the Docker container.

+Updating the CI testing container images


Thanks a lot for the documentation updates! I think this would fit better if integrated into https://github.com/llvm/llvm-project/blob/main/libcxx/docs/Contributing.rst#pre-commit-ci, what do you think?

ldionne · 2025-07-18T15:06:05Z

libcxx/docs/TestingLibcxx.rst

+Which container image is used by these three runner sets is controlled
+and set by the variable values in
+https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf.
+The table below shows the variable names, their current values, and


I agree, we should strive to have a single source of truth (and have that source of truth be in the monorepo).

Also update & correct some of the documentation.

cmtice · 2025-07-28T23:02:47Z

I apologize for the long delay. I think this is ready to review again.

boomanaiden154 · 2025-07-29T13:44:05Z

libcxx/docs/Contributing.rst

@@ -175,7 +175,7 @@ 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
+CI used to be hosted on `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__, but has migrated to the LLVM CI infrastrcuture, and


There's still some CI running on the libc++ Buildkite, mainly platforms that are difficult to run through Github Actions as far as I'm aware.

Also, reflow this text to respect the line length limit if possible.

boomanaiden154 · 2025-07-29T13:45:08Z

libcxx/docs/Contributing.rst

+runner groups. The three runner group names are
+"llvm-premerge-libcxx-runners", "llvm-premerge-libcxx-release-runners"
+or "llvm-premerge-libcxx-next-runners".  Which runner set to use is
+controlled by the contents of https://github.com/llvm/llvm-project/blob/main/.github/workflows/libcxx-build-and-test.yaml . By default, it uses


Reflow this text.

boomanaiden154 · 2025-07-29T13:47:22Z

libcxx/docs/Contributing.rst

+To update just the runner binary, change the value of
+``ACTIONS_BASE_IMAGE`` to be one of the libcxx runner variable images
+from
+https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf.


Maybe a bit more specific than this, you'll want the builder-base image at the same commit SHA.

So if you have ghcr.io/llvm/libcxx-linux-builder:16f046281bf1a11d344eac1bc44d11f3e50e3b5d currently, you would want to set ACTIONS_BASE_IMAGE to ghcr.io/llvm/libcxx-linux-builder-base:16f046281bf1a11d344eac1bc44d11f3e50e3b5d

boomanaiden154 · 2025-07-29T13:48:34Z

libcxx/docs/Contributing.rst

+Lastly you need to create a PR in the llvm-zorg repository,
+updating the the value of the appropriate libcxx runner variable in
+the variables.tf file mentioned above. Once that change has been
+merged, an llvm-zorg administrator must use terraform to apply the


Maybe change llvm-zorg administrator to something like Googler/LLVM Premerge maintainer?

In my mind llvm-zorg administrator means Galina, and she doesn't have access to make changes to the premerge infra.

cmtice added 4 commits July 16, 2025 14:41

[libcxx] Update testing documentation about CI container images.

a15e371

Add information to the libcxx testing documentation, about the names of the for the new CI libcxx runner sets, their current values, and how to change the values or the runner set being used.

Fix table format.

757baec

More table format fixes.

18f213f

Fix typos and other wording issues.

bf0596a

cmtice requested review from ldionne, EricWF and boomanaiden154 July 16, 2025 22:05

cmtice marked this pull request as ready for review July 16, 2025 22:06

cmtice requested a review from a team as a code owner July 16, 2025 22:06

llvmbot added the libc++ libc++ C++ Standard Library. Not GNU libstdc++. Not libc++abi. label Jul 16, 2025

boomanaiden154 reviewed Jul 16, 2025

View reviewed changes

ldionne reviewed Jul 18, 2025

View reviewed changes

cmtice added 2 commits July 28, 2025 14:52

Merge remote-tracking branch 'origin/main' into libc++-documentation

f37621e

Move documentation from TestingLibcxx.rst to Contributing.rst

f0651fb

Also update & correct some of the documentation.

boomanaiden154 reviewed Jul 29, 2025

View reviewed changes

Update text to address reviewer comments.

0677c57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[libcxx] Update testing documentation about CI container images. #149192

[libcxx] Update testing documentation about CI container images. #149192

cmtice commented Jul 16, 2025 •

edited

Loading

Uh oh!

llvmbot commented Jul 16, 2025

Uh oh!

boomanaiden154 Jul 16, 2025

Uh oh!

ldionne Jul 18, 2025

Uh oh!

cmtice Jul 28, 2025

Uh oh!

boomanaiden154 Jul 16, 2025

Uh oh!

ldionne Jul 18, 2025

Uh oh!

cmtice Jul 28, 2025

Uh oh!

ldionne Jul 18, 2025

Uh oh!

cmtice commented Jul 28, 2025

Uh oh!

boomanaiden154 Jul 29, 2025

Uh oh!

boomanaiden154 Jul 29, 2025

Uh oh!

boomanaiden154 Jul 29, 2025

Uh oh!

boomanaiden154 Jul 29, 2025

Uh oh!

boomanaiden154 Jul 29, 2025

Uh oh!

Uh oh!

[libcxx] Update testing documentation about CI container images. #149192

Are you sure you want to change the base?

[libcxx] Update testing documentation about CI container images. #149192

Conversation

cmtice commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

llvmbot commented Jul 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmtice commented Jul 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cmtice commented Jul 16, 2025 •

edited

Loading