nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 1 | # Instructions on how to use the buildrunner to execute builds. |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 2 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 3 | The buildrunner is a script which extracts buildsteps from builders and runs |
| 4 | them locally on the slave. It is being developed to simplify development on and |
| 5 | reduce the complexity of the Chromium build infrastructure. When provided a |
| 6 | master name (with `master.cfg` inside) and a builder, it will either execute |
| 7 | steps sequentially or output information about them. |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 8 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 9 | `runbuild.py` is the main script, while `runit.py` is a convenience script that |
| 10 | sets up `PYTHONPATH` for you. Note that you can use `runit.py` to conveniently |
| 11 | run other scripts in the `build/` directory. |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 12 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 13 | [TOC] |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 14 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 15 | ## Master/Builder Selection |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 16 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 17 | scripts/tools/runit.py scripts/slave/runbuild.py --list-masters |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 18 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 19 | will list all masters in the search path. Select a mastername |
| 20 | (alternatively, use --master-dir to use a specific directory). |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 21 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 22 | Next, we need to pick a builder or slave hostname to build. The slave hostname |
| 23 | is only used to locate a suitable builder, so it need not be the actual hostname |
| 24 | of the slave you're on. |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 25 | |
| 26 | To list all the builders in a master, run: |
| 27 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 28 | scripts/tools/runit.py scripts/slave/runbuild.py mastername --list-builders |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 29 | |
| 30 | Example, if you're in `/home/user/chromium/build/scripts/slave/`: |
| 31 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 32 | scripts/tools/runit.py scripts/slave/runbuild.py chromium --list-builders |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 33 | |
| 34 | will show you which builders are available under the `chromium` master. |
| 35 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 36 | ## Step Inspection and Execution |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 37 | |
| 38 | You can check out the list of steps without actually running them like so: |
| 39 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 40 | scripts/tools/runit.py scripts/slave/runbuild.py chromium build56-m1 --list-steps |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 41 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 42 | Note that some exotic steps, such as gclient steps, won't show up in |
| 43 | buildrunner.) You can show the exact commands of most steps with --show- |
| 44 | commands: |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 45 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 46 | scripts/tools/runit.py scripts/slave/runbuild.py chromium build56-m1 --show-commands |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 47 | |
| 48 | Finally, you can run the build with: |
| 49 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 50 | scripts/tools/runit.py scripts/slave/runbuild.py mastername buildername/slavehost |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 51 | |
| 52 | Example, if you're in `/home/user/chromium/build/scripts/slave/`: |
| 53 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 54 | scripts/tools/runit.py scripts/slave/runbuild.py chromium build56-m1 |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 55 | |
| 56 | or |
| 57 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 58 | scripts/tools/runit.py scripts/slave/runbuild.py chromium 'Linux x64' |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 59 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 60 | `--stepfilter` and `--stepreject`` can be used to filter steps to execute based |
| 61 | on a regex (you can see which with `--list-steps`). See `-help`for more info. |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 62 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 63 | ## Properties |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 64 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 65 | Build properties and factory properties can be specified using `--build- |
| 66 | properties` and `--factory-properties`, respectively. Since build properties |
| 67 | contain a master and builder directive, any master or builder options on the CLI |
| 68 | are ignored. Properties can be inspected with either or both of --output-build- |
| 69 | properties or --output-factory-properties. |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 70 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 71 | ## Monitoring |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 72 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 73 | You can specify a log destination (including '`-`' for stdout) with `--logfile`. |
| 74 | Enabling `--annotate` will enable annotator output. |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 75 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 76 | ## Using Within a Buildstep |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 77 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 78 | The an annotated buildrunner can be invoked via |
| 79 | chromium_commands.AddBuildStep(). Set the master, builder, and any |
| 80 | stepfilter/reject options in factory_properties. For example usage, see |
| 81 | f_linux_runnertest in master.chromium.fyi/master.cfg and |
| 82 | check_deps2git_runner in chromium_factory.py |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 83 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 84 | ## More Information |
andybons | 3322f76 | 2015-08-24 21:37:09 | [diff] [blame] | 85 | |
nodir | 06cbaa0 | 2015-08-25 17:15:24 | [diff] [blame] | 86 | Running with `--help` provides more detailed usage and options. If you have any |
| 87 | questions or issues please contact [email protected]. |