crosvm/infra/README.md

Luci Infrastructure

This directory contains the configuration and build recipes run by our luci infrastructure for CI and presubmit testing.

Note: Luci applies config and recipes changes asynchronously. Do not submit changes to this directory in the same commit as changes to other crosvm source.

Recipes

Recipe Documentation

A few links to relevant documentation needed to write recipes:

• Recipe Engine
• Depot Tools Recipes)
• ChromiumOS Recipes

Luci also provides a User Guide and Walkthrough for getting started with recipes.

For writing tests, documentation can be found in the Recipe test API and Post Process API

Running recipe tests

Recipes must have 100% code coverage to have tests pass. Tests can be run with:

cd infra && ./recipes.py test run

Most tests execute a few example invocations, record the commands that would be executed and compare them to the json files in *.expected. This allows developers to catch unwanted side-effects of their changes.

To regenerate the expectation files, run:

cd infra && ./recipes.py test train

Then verify the git diff to make sure all changes to outcomes are intentional.

Testing recipes locally

We try to build our recipes to work well locally, so for example build_linux.py can be invoked in the recipe engine via:

cd infra && ./recipes.py run build_linux

When run locally, recipes that check out crosvm, will run against the current HEAD of the main branch.

The recipe will run in the local infra/.recipe_deps/recipe_engine/workdir directory and is preserved between runs in the same way data is preserved on bots, so incremental builds or the use of cached files can be tested.

Testing recipes on a bot (Googlers only)

Note: See internal crosvm/infra documentation on access control.

Some things cannot be tested locally and need to be run on one of our build bots. This can be done with the led tool.

Commonly used led commands are:

• led get-builder $NAME will download and output the job template for that builder.
• led get-build $BBID will download the job definition of a previous build.
• led edit-recipe-bundle will update the job to use your local version recipes
• led edit-cr-cl will update the job to run on a gerrit change
• led launch launches a new job using the input job definition.

Important: Changes to recipes are applied separately from changes to crosvm code.

Testing recipe changes on post-submit builders

To test a local recipe change, you can launch a post-submit build using led. First git commit your recipe changes locally, then combine the led commands to:

led get-builder luci.crosvm.ci:linux_x86_64
 | led-edit-recipe-bundle
 | led launch

This will run the linux_x86_64 builder on the current main revision of crosvm using the local version of recipes.

Important: Changes to crosvm source outside of recipes will not be part of the build.

Testing recipe and source changes on pre-submit builders

If we want to test a combination of both recipe and source changes, we can test those on a pre-submit builder, which patch in a gerrit change to test.

We can specify that gerrit change via led edit-cr-cl.

So to test, first git commit and ./tools/cl upload your local changes. Then build a job definition to run:

led get-builder luci.crosvm.try:linux_x86_64
 | led-edit-recipe-bundle
 | led-edit-cr-cl $GERRIT_URL
 | led launch

This will launch a presubmit builder using the local version of recipes, and runs it on the gerrit change at $GERRIT_URL.

Testing a new recipe

This is a little tricker, but you can change the recipe name that is launched by led. So you can:

led get-builder luci.crosvm.ci:linux_x86_64 > job.json

Then edit the job.json file to use the newly added recipe, and launch the job using the local version of recipes.

cat job.json | led-edit-recipe-bundle | led launch