docs/using_build_runner.md

   1 # Instructions on how to use the buildrunner to execute builds.
   2
   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.
   8
   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.
  12
  13 [TOC]
  14
  15 ## Master/Builder Selection
  16
  17     scripts/tools/runit.py scripts/slave/runbuild.py --list-masters
  18
  19 will list all masters in the search path. Select a mastername
  20 (alternatively, use --master-dir to use a specific directory).
  21
  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.
  25
  26 To list all the builders in a master, run:
  27
  28     scripts/tools/runit.py scripts/slave/runbuild.py mastername --list-builders
  29
  30 Example, if you're in `/home/user/chromium/build/scripts/slave/`:
  31
  32     scripts/tools/runit.py scripts/slave/runbuild.py chromium --list-builders
  33
  34 will show you which builders are available under the `chromium` master.
  35
  36 ## Step Inspection and Execution
  37
  38 You can check out the list of steps without actually running them like so:
  39
  40     scripts/tools/runit.py scripts/slave/runbuild.py chromium  build56-m1 --list-steps
  41
  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:
  45
  46     scripts/tools/runit.py scripts/slave/runbuild.py chromium  build56-m1 --show-commands
  47
  48 Finally, you can run the build with:
  49
  50     scripts/tools/runit.py scripts/slave/runbuild.py mastername buildername/slavehost
  51
  52 Example, if you're in `/home/user/chromium/build/scripts/slave/`:
  53
  54     scripts/tools/runit.py scripts/slave/runbuild.py chromium  build56-m1
  55
  56 or
  57
  58     scripts/tools/runit.py scripts/slave/runbuild.py chromium  'Linux x64'
  59
  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.
  62
  63 ## Properties
  64
  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.
  70
  71 ## Monitoring
  72
  73 You can specify a log destination (including '`-`' for stdout) with `--logfile`.
  74 Enabling `--annotate` will enable annotator output.
  75
  76 ## Using Within a Buildstep
  77
  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
  83
  84 ## More Information
  85
  86 Running with `--help` provides more detailed usage and options. If you have any
  87 questions or issues please contact xusydoc@chromium.org.