blob: 8e9d0f508afd3092c290f41f2066a2c16db40efc [file] [log] [blame] [view]
nodir06cbaa02015-08-25 17:15:241# Instructions on how to use the buildrunner to execute builds.
andybons3322f762015-08-24 21:37:092
nodir06cbaa02015-08-25 17:15:243The buildrunner is a script which extracts buildsteps from builders and runs
4them locally on the slave. It is being developed to simplify development on and
5reduce the complexity of the Chromium build infrastructure. When provided a
6master name (with `master.cfg` inside) and a builder, it will either execute
7steps sequentially or output information about them.
andybons3322f762015-08-24 21:37:098
nodir06cbaa02015-08-25 17:15:249`runbuild.py` is the main script, while `runit.py` is a convenience script that
10sets up `PYTHONPATH` for you. Note that you can use `runit.py` to conveniently
11run other scripts in the `build/` directory.
andybons3322f762015-08-24 21:37:0912
nodir06cbaa02015-08-25 17:15:2413[TOC]
andybons3322f762015-08-24 21:37:0914
nodir06cbaa02015-08-25 17:15:2415## Master/Builder Selection
andybons3322f762015-08-24 21:37:0916
nodir06cbaa02015-08-25 17:15:2417 scripts/tools/runit.py scripts/slave/runbuild.py --list-masters
andybons3322f762015-08-24 21:37:0918
nodir06cbaa02015-08-25 17:15:2419will list all masters in the search path. Select a mastername
20(alternatively, use --master-dir to use a specific directory).
andybons3322f762015-08-24 21:37:0921
nodir06cbaa02015-08-25 17:15:2422Next, we need to pick a builder or slave hostname to build. The slave hostname
23is only used to locate a suitable builder, so it need not be the actual hostname
24of the slave you're on.
andybons3322f762015-08-24 21:37:0925
26To list all the builders in a master, run:
27
nodir06cbaa02015-08-25 17:15:2428 scripts/tools/runit.py scripts/slave/runbuild.py mastername --list-builders
andybons3322f762015-08-24 21:37:0929
30Example, if you're in `/home/user/chromium/build/scripts/slave/`:
31
nodir06cbaa02015-08-25 17:15:2432 scripts/tools/runit.py scripts/slave/runbuild.py chromium --list-builders
andybons3322f762015-08-24 21:37:0933
34will show you which builders are available under the `chromium` master.
35
nodir06cbaa02015-08-25 17:15:2436## Step Inspection and Execution
andybons3322f762015-08-24 21:37:0937
38You can check out the list of steps without actually running them like so:
39
nodir06cbaa02015-08-25 17:15:2440 scripts/tools/runit.py scripts/slave/runbuild.py chromium build56-m1 --list-steps
andybons3322f762015-08-24 21:37:0941
nodir06cbaa02015-08-25 17:15:2442Note that some exotic steps, such as gclient steps, won't show up in
43buildrunner.) You can show the exact commands of most steps with --show-
44commands:
andybons3322f762015-08-24 21:37:0945
nodir06cbaa02015-08-25 17:15:2446 scripts/tools/runit.py scripts/slave/runbuild.py chromium build56-m1 --show-commands
andybons3322f762015-08-24 21:37:0947
48Finally, you can run the build with:
49
nodir06cbaa02015-08-25 17:15:2450 scripts/tools/runit.py scripts/slave/runbuild.py mastername buildername/slavehost
andybons3322f762015-08-24 21:37:0951
52Example, if you're in `/home/user/chromium/build/scripts/slave/`:
53
nodir06cbaa02015-08-25 17:15:2454 scripts/tools/runit.py scripts/slave/runbuild.py chromium build56-m1
andybons3322f762015-08-24 21:37:0955
56or
57
nodir06cbaa02015-08-25 17:15:2458 scripts/tools/runit.py scripts/slave/runbuild.py chromium 'Linux x64'
andybons3322f762015-08-24 21:37:0959
nodir06cbaa02015-08-25 17:15:2460`--stepfilter` and `--stepreject`` can be used to filter steps to execute based
61on a regex (you can see which with `--list-steps`). See `-help`for more info.
andybons3322f762015-08-24 21:37:0962
nodir06cbaa02015-08-25 17:15:2463## Properties
andybons3322f762015-08-24 21:37:0964
nodir06cbaa02015-08-25 17:15:2465Build properties and factory properties can be specified using `--build-
66properties` and `--factory-properties`, respectively. Since build properties
67contain a master and builder directive, any master or builder options on the CLI
68are ignored. Properties can be inspected with either or both of --output-build-
69properties or --output-factory-properties.
andybons3322f762015-08-24 21:37:0970
nodir06cbaa02015-08-25 17:15:2471## Monitoring
andybons3322f762015-08-24 21:37:0972
nodir06cbaa02015-08-25 17:15:2473You can specify a log destination (including '`-`' for stdout) with `--logfile`.
74Enabling `--annotate` will enable annotator output.
andybons3322f762015-08-24 21:37:0975
nodir06cbaa02015-08-25 17:15:2476## Using Within a Buildstep
andybons3322f762015-08-24 21:37:0977
nodir06cbaa02015-08-25 17:15:2478The an annotated buildrunner can be invoked via
79chromium_commands.AddBuildStep(). Set the master, builder, and any
80stepfilter/reject options in factory_properties. For example usage, see
81f_linux_runnertest in master.chromium.fyi/master.cfg and
82check_deps2git_runner in chromium_factory.py
andybons3322f762015-08-24 21:37:0983
nodir06cbaa02015-08-25 17:15:2484## More Information
andybons3322f762015-08-24 21:37:0985
nodir06cbaa02015-08-25 17:15:2486Running with `--help` provides more detailed usage and options. If you have any
87questions or issues please contact [email protected].