Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Aug 6, 2025
Merged

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

Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
a15e371
[libcxx] Update testing documentation about CI container images.
cmtice Jul 16, 2025
757baec
Fix table format.
cmtice Jul 16, 2025
18f213f
More table format fixes.
cmtice Jul 16, 2025
bf0596a
Fix typos and other wording issues.
cmtice Jul 16, 2025
f37621e
Merge remote-tracking branch 'origin/main' into libc++-documentation
cmtice Jul 28, 2025
f0651fb
Move documentation from TestingLibcxx.rst to Contributing.rst
cmtice Jul 28, 2025
0677c57
Update text to address reviewer comments.
cmtice Jul 29, 2025
8d68e8c
Update text as suggested by reviewer.
cmtice Jul 31, 2025
c2b97d3
Update spaces as requested by reviewer.
cmtice Aug 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions libcxx/docs/TestingLibcxx.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will do.

----------------------------------------

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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
=============

Expand Down
Loading