From f31341c9e26e39e5646f8c46799496d0a83da6b3 Mon Sep 17 00:00:00 2001 From: Alex Bradbury Date: Tue, 5 Nov 2024 16:59:06 +0000 Subject: [PATCH] [docs] Expand HowToAddABuilder with guidance on testing locally Once and land, it's quite reasonable to ask people to test their builder configurations locally. This patch adds documentation on how to do so. I think review at this stage is useful, but of course if there's more review feedback on it's possible some details may change. This won't be committed until those llvm-zorg PRs land of course. --- llvm/docs/HowToAddABuilder.rst | 68 ++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/llvm/docs/HowToAddABuilder.rst b/llvm/docs/HowToAddABuilder.rst index f07640f6627cf1..060c3104b062fe 100644 --- a/llvm/docs/HowToAddABuilder.rst +++ b/llvm/docs/HowToAddABuilder.rst @@ -179,6 +179,74 @@ Here are the steps you can follow to do so: buildbot.tac file to change the port number from 9994 to 9990 and start it again. +Testing a Builder Config Locally +================================ + +It's possible to test a builder running against a local version of LLVM's +buildmaster configuration. This can be helpful to allow quickly identifying +and iterating over fixes to any issues in either the changes that introduce +the new builder, or the machine configuration for your worker (preinstalled +packages etc). A buildmaster launched in this "local testing" mode will bind +only to local interfaces, use SQLite as the database, use a fixed password for +workers, and disable things like GitHub authentication. + +* Within a checkout of `llvm-zorg `_, + create and activate a Python `venv + `_ and install the necessary + dependencies. + + .. code-block:: bash + + python -m venv bbenv + source bbenv/bin/activate + pip install buildbot{,-console-view,-grid-view,-waterfall-view,-worker,-www}==3.11.7 urllib3 + +* Initialise the necessary buildmaster files, link to the configuration in + ``llvm-zorg`` and run a litmus check (run in the directory of your choice): + + .. code-block:: bash + + buildbot create-master llvm-testbbmaster + cd llvm-testbbmaster + ln -s /path/to/checkout/of/llvm-zorg/buildbot/osuosl/master/master.cfg . + ln -s /path/to/checkout/of/llvm-zorg/buildbot/osuosl/master/config/ . + ln -s /path/to/checkout/of/llvm-zorg/zorg/ . + BUILDMASTER_TEST=1 buildbot checkconfig + +* Start the buildmaster using the command below. After a few seconds to + startup, you should be able to open the web UI at ``http://localhost:8011``. + If there are any errors or this isn't working, be sure to check + ``twistd.log`` for more information. + + .. code-block:: bash + + BUILDMASTER_TEST=1 buildbot start --nodaemon . + +* With the above in place, you can now create and start a buildbot worker. + Ensure you pick the correct name for the worker attached to the build + configuration you want to test in + ``buildbot/osuosl/master/config/builders.py``. After doing the below, either + wait until the poller sets off a build, or you can force a build to start in + the web UI (which is also the best place to review the build results). + + .. code-block:: bash + + buildbot-worker create-worker \ + localhost:9990 \ + \ + test + buildbot-worker start --nodaemon + +This local testing configuration defaults to binding only to the loopback +interface for security reasons. If you want to run the test worker on a +different machine, or to run the buildmaster on a remote server, ssh port +forwarding can be used to make connection possible. For instance, if running +the buildmaster on a remote server the following command will suffice to make +the web UI accessible via ``http://localhost:8011`` and make it possible for a +local worker to connect to the remote buildmaster by connecting to +``localhost:9900``: ``ssh -N -L 8011:localhost:8011 -L 9990:localhost:9990 +username@server_address``. + Best Practices for Configuring a Fast Builder =============================================