Skip to content

Commit

Permalink
[llvm][docs] Expand HowToAddABuilder with guidance on testing locally (
Browse files Browse the repository at this point in the history
…#115024)

With <llvm/llvm-zorg#289> and <llvm/llvm-zorg#293> landed, it's now reasonable to ask people to test their builder configurations locally. This patch adds documentation on how to do so.
  • Loading branch information
asb authored Nov 12, 2024
1 parent 24a8092 commit 8da61a3
Showing 1 changed file with 81 additions and 0 deletions.
81 changes: 81 additions & 0 deletions llvm/docs/HowToAddABuilder.rst
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,87 @@ 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 is possible to test a builder running against a local version of LLVM's
buildmaster setup. This allows you to test changes to builder, worker, and
buildmaster configuration. A buildmaster launched in this "local testing" mode
will:
* Bind only to local interfaces.
* Use SQLite as the database.
* Use a single fixed password for workers.
* Disable extras like GitHub authentication.

In order to use this "local testing" mode:

* Within a checkout of `llvm-zorg <https://github.com/llvm/llvm-zorg>`_,
create and activate a Python `venv
<https://docs.python.org/3/library/venv.html>`_ 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 ask ``buildbot`` to check the configuration. This step can
be run from any directory.

.. 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/ .
BUILDBOT_TEST=1 buildbot checkconfig
* Start the buildmaster.

.. code-block:: bash
BUILDBOT_TEST=1 buildbot start --nodaemon .
* After waiting a few seconds for startup to complete, you should be able to
open the web UI at ``http://localhost:8011``. If there are any errors or
this isn't working, check ``twistd.log`` (within the current directory) for
more information.

* You can now create and start a buildbot worker. Ensure you pick the correct
name for the worker associated with the build configuration you want to test
in ``buildbot/osuosl/master/config/builders.py``.

.. code-block:: bash
buildbot-worker create-worker <buildbot-worker-root-directory> \
localhost:9990 \
<buildbot-worker-name> \
test
buildbot-worker start --nodaemon <buildbot-worker-root-directory>
* Either wait until the poller sets off a build, or alternatively force a
build to start in the web UI.

* Review the progress and results of the build in the web UI.

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``:

.. code-block:: bash
ssh -N -L 8011:localhost:8011 -L 9990:localhost:9990 username@buildmaster_server_address
Best Practices for Configuring a Fast Builder
=============================================

Expand Down

0 comments on commit 8da61a3

Please sign in to comment.