There are many repositories containing recipes and recipe modules. Repositories declare their relationships to each other in a file called recipes.cfg
, in the infra/config
directory from the repository root. For example:
{ "api_version": 2, "repo_name": "build_internal", "recipes_path": "", "deps": { "build": { "url": "https://chromium.googlesource.com/chromium/tools/build", "branch": "master", "revision": "09cee0ae226949923db058cb21e98a42d7d29f11" }, "recipe_engine": { "url": "https://chromium.googlesource.com/infra/luci/recipes-py.git", "branch": "master", "revision": "fe88a668a6cea70d2233c4e61be352fc1551d1ce" } } }
repo_name
is a unique name for this repo. Typically this is the same as the LUCI-config project_id for the repo. recipes_path
is the path from the root of the repository to the location of the recipes
and recipe_modules
directories. This collection of recipes-related things in a repository is called a recipe repo.
There are two deps
entries in this file. There always has to be an entry for the recipe_engine
repo, which pins the version of the engine that is used, and all repos in a particular dependency graph must agree on the engine revision (in fact, they must agree on the revision of any shared dependency).
The recipes.py
tool, which goes alongside the recipes
and recipe_modules
directories, can be used to interact with the dependencies of a recipe repo.
$ ./recipes.py fetch
fetches the whole dependency graph into the .recipe_deps
directory (again alongside recipes
and recipe_modules
) at the pinned revisions. This is done automatically in most cases, but can be helpful if you want to poke around the graph.
$ ./recipes.py roll
updates the dependencies in recipes.cfg
, following the specified branch
forward. roll
takes as small a step forward as possible, so you have to run it multiple times if you want to roll farther. This is so that it is possible, for example, to tell at which point the simulation tests broke.
The recipes.py
tool has several other modes for working with a recipe repo, which are not covered here, but look at recipes.py --help
.
When locally developing recipes, it is oftentimes desirable to observe the effect that your local changes will have on other repositories. This can be done by using recipe engine local overrides command-line flags (-O
).
Local overrides allow the user to redirect a repo's checkout to a local path during execution. A developer would run the downstream recipes, overriding the one or more upstream recipe repos under development.
For example, to make a change in build
and see what its effect on build_internal
recipes, one would execute build_internal
's recipe, overriding its build
repo to point to the local path.
$ ./recipes.py -O build=/path/to/build test train
This would simulate and train build_internal
recipes, using the local build
checkout instead of the one configured in build_internal
's recipes.cfg
.
In the case that you want to test local changes to the recipe engine itself, the workflow is a little different, for technical reasons. Let‘s say you have a recipes-py
checkout in /b/recipes-py
, which you’ve modified, and you want to see its effects on the repository /b/build
. Run:
$ /b/recipes-py/recipes.py --package /b/build/infra/config/recipes.cfg \ -O recipe_engine=/b/recipes-py test run
Running /b/recipes-py/recipes.py
uses the modified engine, however without the -O
repo override option, it would still use core modules pinned in recipes.cfg
.