Index: tools/mb/docs/user_guide.md |
diff --git a/tools/mb/docs/user_guide.md b/tools/mb/docs/user_guide.md |
index 7f002919aeae663b30d4339d48f79957a0c793bb..f31897f7a4caf2b75de85dc37b1eea5d7d951575 100644 |
--- a/tools/mb/docs/user_guide.md |
+++ b/tools/mb/docs/user_guide.md |
@@ -34,31 +34,59 @@ The first positional argument must be a GN-style "source-absolute" path |
to the build directory. |
The second positional argument is a (normal) path to a JSON file containing |
-a single object with two fields: |
- |
- * `files`: an array of the modified filenames to check (as |
- paths relative to the checkout root). |
- * `targets`: an array of the unqualified target names to check. |
+a single object with the following fields: |
+ |
+ * `files`: an array of the modified filenames to check (as paths relative to |
+ the checkout root). |
+ * `compile_targets`: an array of (ninja) build targets that reflect the stuff |
+ we might want to rebuild if affected by the patch. The targets may contain |
+ *meta* (GN: group, GYP: none) targets like 'blink_tests' or |
+ 'chromium_builder_tests', or even the ninja-specific 'all' target. Any |
+ empty list will be treated as equivalent to ["all"] (build everything). |
+ * `test_targets`: an array of (ninja) build targets that, if affected, will |
+ affect which tests we want to run. This is usually a *subset* of |
+ `compile_targets`. An empty list is treated as if there are no tests |
+ to run. |
+ * `targets`: a legacy field that resembled a union of `compile_targets` |
+ and `test_targets`. Support for this field will be removed once the |
+ bots have been updated to use compile_targets and test_targets instead. |
The third positional argument is a (normal) path to where mb will write |
the result, also as a JSON object. This object may contain the following |
fields: |
* `error`: this should only be present if something failed. |
- * `targets`: the subset of the input `targets` that depend on the |
- input `files`. |
- * `build_targets`: the minimal subset of targets needed to build all |
- of `targets` that were affected. |
- * `status`: one of three strings: |
+ * `compile_targets`: the list of ninja targets that should be passed |
+ directly to the corresponding ninja / compile.py invocation. This |
+ list may contain entries that are *not* listed in the input (see |
+ [design_spec.md](the design spec) for how this works). |
+ * `test_targets`: the subset of the input `test_targets` that are |
+ potentially out of date, indicating that the matching test steps |
+ should be re-run. |
+ * `targets`: a legacy field that indicates the subset of the input `targets` |
+ that depend on the input `files`. |
+ * `build_targets`: a legacy field that indicates the minimal subset of |
+ targets needed to build all of `targets` that were affected. |
+ * `status`: a legacy field containing one of three strings: |
+ |
* `"Found dependency"` (build the `build_targets`) |
* `"No dependency"` (i.e., no build needed) |
* `"Found dependency (all)"` (build everything, in which case |
- `targets` and `build_targets` are not returned). |
+ `targets` and `build_targets` are not returned). |
+ |
+ This field is no longer needed with the newer compile_targets and |
+ test_targets outputs, and will be removed along with `targets` and |
+ `build_targets` once all the bots have been updated. |
Dirk Pranke
2015/11/06 04:34:19
NB: this might surprise you.
Dirk Pranke
2015/11/06 05:08:47
Actually, having thought about this some more, I t
|
+ |
+The differences between `compile_targets` and `test_targets` and between |
+how they are treated as input and output is subtle and complicated; see |
+[design_spec.md](the design spec) for details. We won't even go into how |
+the `targets` and `build_targets` differ from each other or from |
+`compile_targets` and `test_targets`. |
The `-b/--builder`, `-c/--config`, `-f/--config-file`, `-m/--master`, |
`-q/--quiet`, and `-v/--verbose` flags work as documented for `mb gen`. |
- |
### `mb gen` |
`mb gen` is responsible for generating the Ninja files by invoking either GYP |