Index: tools/mb/docs/user_guide.md |
diff --git a/tools/mb/docs/user_guide.md b/tools/mb/docs/user_guide.md |
index 8f4e01054c8e0541a4a5dc506178395a1db24f14..8aff68d0f19ec54270a4853ee51b26a79322a2a6 100644 |
--- a/tools/mb/docs/user_guide.md |
+++ b/tools/mb/docs/user_guide.md |
@@ -14,11 +14,26 @@ |
Ideally this tool will no longer be needed after the migration is complete. |
-For more discussion of MB, see also [the design spec](design_spec.md). |
+## `mb gen` |
-## MB subcommands |
+`mb gen` is responsible for generating the Ninja files by invoking either GYP |
+or GN as appropriate. It takes arguments to specify a build config and |
+a directory, then runs GYP or GN as appropriate: |
-### `mb analyze` |
+``` |
+% mb gen -m tryserver.chromium.linux -b linux_rel //out/Release |
+% mb gen -c linux_rel_trybot //out/Release |
+``` |
+ |
+Either the `-c/--config` flag or the `-m/--master` and `-b/--builder` flags |
+must be specified so that `mb` can figure out which config to use. |
+ |
+The path must be a GN-style "source-absolute" path (as above). |
+ |
+If gen ends up using GYP, the path must have a valid GYP configuration as the |
+last component of the path (i.e., specify `//out/Release_x64`, not `//out`). |
+ |
+## `mb analyze` |
`mb analyze` is reponsible for determining what targets are affected by |
a list of files (e.g., the list of files in a patch on a trybot): |
@@ -29,6 +44,7 @@ |
Either the `-c/--config` flag or the `-m/--master` and `-b/--builder` flags |
must be specified so that `mb` can figure out which config to use. |
+ |
The first positional argument must be a GN-style "source-absolute" path |
to the build directory. |
@@ -55,57 +71,16 @@ |
* `"Found dependency (all)"` (build everything, in which case |
`targets` and `build_targets` are not returned). |
-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 |
-or GN as appropriate. It takes arguments to specify a build config and |
-a directory, then runs GYP or GN as appropriate: |
- |
-``` |
-% mb gen -m tryserver.chromium.linux -b linux_rel //out/Release |
-% mb gen -c linux_rel_trybot //out/Release |
-``` |
- |
-Either the `-c/--config` flag or the `-m/--master` and `-b/--builder` flags |
-must be specified so that `mb` can figure out which config to use. |
- |
-By default, MB will look in `//tools/mb/mb_config.pyl` to look up the config |
-information, but you can specify a custom config file using the |
-`-f/--config-file` flag. |
- |
-The path must be a GN-style "source-absolute" path (as above). |
- |
-You can pass the `-n/--dryrun` flag to mb gen to see what will happen without |
-actually writing anything. |
- |
-You can pass the `-q/--quiet` flag to get mb to be silent unless there is an |
-error, and pass the `-v/--verbose` flag to get mb to log all of the files |
-that are read and written, and all the commands that are run. |
- |
-If the build config will use the Goma distributed-build system, you can pass |
-the path to your Goma client in the `-g/--goma-dir` flag, and it will be |
-incorporated into the appropriate flags for GYP or GN as needed. |
- |
-If gen ends up using GYP, the path must have a valid GYP configuration as the |
-last component of the path (i.e., specify `//out/Release_x64`, not `//out`). |
- |
-### `mb help` |
+## `mb help` |
Produces help output on the other subcommands |
-### `mb lookup` |
+## `mb lookup` |
Prints what command will be run by `mb gen` (like `mb gen -n` but does |
not require you to specify a path). |
-The `-b/--builder`, `-c/--config`, `-f/--config-file`, `-m/--master`, |
-`-q/--quiet`, and `-v/--verbose` flags work as documented for `mb gen`. |
- |
-### `mb validate` |
+## `mb validate` |
Does internal checking to make sure the config file is syntactically |
valid and that all of the entries are used properly. It does not validate |
@@ -113,35 +88,10 @@ |
comprehensive, but it does complain about configs and mixins that aren't |
used. |
-The `-f/--config-file` and `-q/--quiet` flags work as documented for |
-`mb gen`. |
- |
This is mostly useful as a presubmit check and for verifying changes to |
the config file. |
-## Isolates and Swarming |
- |
-`mb gen` is also responsible for generating the `.isolate` and |
-`.isolated.gen.json` files needed to run test executables through swarming |
-in a GN build (in a GYP build, this is done as part of the compile step). |
- |
-If you wish to generate the isolate files, pass `mb gen` the |
-`--swarming-targets-file` command line argument; that arg should be a path |
-to a file containing a list of ninja build targets to compute the runtime |
-dependencies for (on Windows, use the ninja target name, not the file, so |
-`base_unittests`, not `base_unittests.exe`). |
- |
-MB will take this file, translate each build target to the matching GN |
-label (e.g., `base_unittests` -> `//base:base_unittests`, write that list |
-to a file called `runtime_deps` in the build directory, and pass that to |
-`gn gen $BUILD ... --runtime-deps-list-file=$BUILD/runtime_deps`. |
- |
-Once GN has computed the lists of runtime dependencies, MB will then |
-look up the command line for each target (currently this is hard-coded |
-in [mb.py](https://code.google.com/p/chromium/codesearch?q=mb.py#chromium/src/tools/mb/mb.py&q=mb.py%20GetIsolateCommand&sq=package:chromium&type=cs)), and write out the |
-matching `.isolate` and `.isolated.gen.json` files. |
- |
-## The `mb_config.pyl` config file |
+## mb_config.pyl |
The `mb_config.pyl` config file is intended to enumerate all of the |
supported build configurations for Chromium. Generally speaking, you |
@@ -228,7 +178,7 @@ |
(From that you can see that mb is intentionally dumb and does not |
attempt to de-dup the flags, it lets gyp do that). |
-## Debugging MB |
+## Debugging (-v/--verbose and -n/--dry-run) |
By design, MB should be simple enough that very little can go wrong. |