From a15e371d74248aae2e422eee4c3b794673894616 Mon Sep 17 00:00:00 2001 From: Caroline Tice Date: Wed, 16 Jul 2025 14:41:51 -0700 Subject: [PATCH 1/7] [libcxx] Update testing documentation about CI container images. 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. --- libcxx/docs/TestingLibcxx.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst index 56cf4aca236f9..2be6739e6f4a6 100644 --- a/libcxx/docs/TestingLibcxx.rst +++ b/libcxx/docs/TestingLibcxx.rst @@ -139,6 +139,37 @@ 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-permerge-libcxx-runners", "llvm-premerge-libcxx-release-runners" +or "llvm-premerge-libcxx-next-runners". Which one of these sets is +used, is controled 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". + +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 ============= From 757baec2b2952caa3f5e8da092a9a5ff305811a6 Mon Sep 17 00:00:00 2001 From: Caroline Tice Date: Wed, 16 Jul 2025 14:54:18 -0700 Subject: [PATCH 2/7] Fix table format. --- libcxx/docs/TestingLibcxx.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst index 2be6739e6f4a6..b944889614b51 100644 --- a/libcxx/docs/TestingLibcxx.rst +++ b/libcxx/docs/TestingLibcxx.rst @@ -155,11 +155,13 @@ https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variable . 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| ++------------------------------------+---------------------------+--------------------------------------------------------------------------+ +|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| +|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. From 18f213fa4cc423e99fddfa64fa7862abaaf09bfd Mon Sep 17 00:00:00 2001 From: Caroline Tice Date: Wed, 16 Jul 2025 14:57:13 -0700 Subject: [PATCH 3/7] More table format fixes. --- libcxx/docs/TestingLibcxx.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst index b944889614b51..1ef2be81fdea5 100644 --- a/libcxx/docs/TestingLibcxx.rst +++ b/libcxx/docs/TestingLibcxx.rst @@ -159,7 +159,9 @@ 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| +------------------------------------+---------------------------+--------------------------------------------------------------------------+ From bf0596a473cd82ae40d6679e5081e867ef8f259e Mon Sep 17 00:00:00 2001 From: Caroline Tice Date: Wed, 16 Jul 2025 15:02:55 -0700 Subject: [PATCH 4/7] Fix typos and other wording issues. --- libcxx/docs/TestingLibcxx.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst index 1ef2be81fdea5..d278e18093e87 100644 --- a/libcxx/docs/TestingLibcxx.rst +++ b/libcxx/docs/TestingLibcxx.rst @@ -144,15 +144,17 @@ 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-permerge-libcxx-runners", "llvm-premerge-libcxx-release-runners" -or "llvm-premerge-libcxx-next-runners". Which one of these sets is -used, is controled 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". +"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 +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. +------------------------------------+---------------------------+--------------------------------------------------------------------------+ From f0651fb40c47e29b0d58a4b4a19af9d9ec744d4a Mon Sep 17 00:00:00 2001 From: Caroline Tice Date: Mon, 28 Jul 2025 15:59:27 -0700 Subject: [PATCH 5/7] Move documentation from TestingLibcxx.rst to Contributing.rst Also update & correct some of the documentation. --- libcxx/docs/Contributing.rst | 76 ++++++++++++++++++++++++++++++++--- libcxx/docs/TestingLibcxx.rst | 37 ----------------- 2 files changed, 70 insertions(+), 43 deletions(-) diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst index 6aaa70764c2fa..09d7f5020e96b 100644 --- a/libcxx/docs/Contributing.rst +++ b/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 `__ and +CI used to be hosted on `Buildkite `__, but has migrated to the LLVM CI infrastrcuture, and the build results are visible in the review on GitHub. Please make sure the CI is green before committing a patch. @@ -246,12 +246,15 @@ Below is a short description of the most interesting CI builds [#]_: 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. +The files for the CI infrastructure are split between the llvm-project +and the llvm-zorg repositories. All files of the CI infrastructure in +the llvm-project 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 -~~~~~~~~~~ +Dockerfile/Container Images +~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 @@ -261,6 +264,67 @@ GCC, and CMake. .. note:: This image is pulled from Docker hub and not rebuild when changing the Dockerfile. +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 and +the runner sets to which they correspond. To see their values, follow the +link above (to variables.tf in llvm-zorg). + ++------------------------------------+---------------------------+ +|Runner Set |Variable | ++====================================+===========================+ +|llvm-premerge-libcxx-runners |libcxx_runner_image | ++------------------------------------+---------------------------+ +|llvm-premerge-libcxx-release-runners|libcxx_release_runner_image| ++------------------------------------+---------------------------+ +|llvm-premerge-libcxx-next-runners |libcxx_next_runner_image | ++------------------------------------+---------------------------+ + + +When updating the container image you can either update just the +runner binary (the part the connects to Github), or you can update +everything (tools, etc.). Whether to update just the runner or to update +everything is controlled by the value of ``ACTIONS_BASE_IMAGE``, under +``actions-builder`` in ``libcxx/utils/ci/docker-compose.yml``. + +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. + +To update the entire container image, set the value of ``ACTIONS_BASE_IMAGE`` +to ``builder-base``. If the value is already ``builder-base`` (there +have been no just-the-runner updates since the last complete update), then +you need to find the line containing +``RUN echo "Last forced update executed on`` in +``libcxx/utils/ci/Dockerfile`` and update the date to be the current date. + +Once you have created and merged a PR with those changes, a new image +will be created, and a link to it can be found at +https://github.com/llvm/llvm-project/pkgs/container/libcxx-linux-builder., +where the actual image name should be +``ghcr.io/llvm/libcxx-linux-builder:``. + +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 +change to the running GKE cluster. + + run-buildbot-container ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst index d278e18093e87..56cf4aca236f9 100644 --- a/libcxx/docs/TestingLibcxx.rst +++ b/libcxx/docs/TestingLibcxx.rst @@ -139,43 +139,6 @@ 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 ============= From 0677c57c55ebb79767b7e79521336e6bb17c699a Mon Sep 17 00:00:00 2001 From: Caroline Tice Date: Tue, 29 Jul 2025 09:20:39 -0700 Subject: [PATCH 6/7] Update text to address reviewer comments. --- libcxx/docs/Contributing.rst | 51 ++++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 23 deletions(-) diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst index 09d7f5020e96b..994b343d8d939 100644 --- a/libcxx/docs/Contributing.rst +++ b/libcxx/docs/Contributing.rst @@ -174,10 +174,11 @@ Pre-commit CI Introduction ------------ -Unlike most parts of the LLVM project, libc++ uses a pre-commit CI [#]_. This -CI used to be hosted on `Buildkite `__, but has migrated to the LLVM CI infrastrcuture, and -the build results are visible in the review on GitHub. Please make sure -the CI is green before committing a patch. +Unlike most parts of the LLVM project, libc++ uses a pre-commit CI [#]_. Some of +this CI is hosted on `Buildkite`__, +but some has migrated to the LLVM CI infrastructure. The build results are +visible in the review on GitHub. Please make sure the CI is green before +committing a patch. The CI tests libc++ for all :ref:`supported platforms `. The build is started for every commit added to a Pull Request. A complete CI @@ -267,14 +268,14 @@ GCC, and CMake. 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. +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 @@ -300,17 +301,20 @@ everything (tools, etc.). Whether to update just the runner or to update everything is controlled by the value of ``ACTIONS_BASE_IMAGE``, under ``actions-builder`` in ``libcxx/utils/ci/docker-compose.yml``. -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. +To update just the runner binary, change the value of ``ACTIONS_BASE_IMAGE`` +to be a modified version of one of the libcxx runner variable images from +https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf, +as follows: Find the libcxx runner image name you want to use from the +variables.tf file. The name will be something like +``ghcr.io/llvm/libcxx-linux-builder:``. Replace +``libcxx-linux-builder`` with ``libcxx-linux-builder-base``. Use this new image +name as the value you assign to ``ACTIONS_BASE_IMAGE``. To update the entire container image, set the value of ``ACTIONS_BASE_IMAGE`` to ``builder-base``. If the value is already ``builder-base`` (there -have been no just-the-runner updates since the last complete update), then -you need to find the line containing -``RUN echo "Last forced update executed on`` in -``libcxx/utils/ci/Dockerfile`` and update the date to be the current date. +have been no just-the-runner updates since the last complete update), then you +need to find the line containing ``RUN echo "Last forced update executed on`` +in ``libcxx/utils/ci/Dockerfile`` and update the date to be the current date. Once you have created and merged a PR with those changes, a new image will be created, and a link to it can be found at @@ -320,9 +324,10 @@ where the actual image name should be 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 -change to the running GKE cluster. +the variables.tf file mentioned above to the name of your newly created +image (see above paragraph about finding the image name). Once that change +has been merged, the LLVM premerge maintainer (a Google employee) must use +terraform to apply the change to the running GKE cluster. run-buildbot-container From 8d68e8cdba0b781813e57b36c2fd12bbd6484e52 Mon Sep 17 00:00:00 2001 From: Caroline Tice Date: Wed, 30 Jul 2025 20:09:19 -0700 Subject: [PATCH 7/7] Update text as suggested by reviewer. --- libcxx/docs/Contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst index 994b343d8d939..0d779ff03929d 100644 --- a/libcxx/docs/Contributing.rst +++ b/libcxx/docs/Contributing.rst @@ -270,7 +270,7 @@ 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". +"llvm-premerge-libcxx-release-runners" and "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 @@ -326,7 +326,7 @@ 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 to the name of your newly created image (see above paragraph about finding the image name). Once that change -has been merged, the LLVM premerge maintainer (a Google employee) must use +has been merged, an LLVM premerge maintainer (a Google employee) must use terraform to apply the change to the running GKE cluster.