First pass at a meta-build wrapper for the gyp->gn migration

tools/mb/docs/user_guide.md

Index: tools/mb/docs/user_guide.md
diff --git a/tools/mb/docs/user_guide.md b/tools/mb/docs/user_guide.md
new file mode 100644
index 0000000000000000000000000000000000000000..9152970548a09517debbcb521d7e1aa59712c54a
--- /dev/null
+++ b/tools/mb/docs/user_guide.md
@@ -0,0 +1,90 @@
+# The MB (Meta-Build wrapper) user guide
+
+[TOC]
+
+## introduction
+
+`mb` is a simple python wrapper around the GYP and GN meta-build tools.
+It is intended to be used by both developers and bots to make it easier
+to manage one or more builds of Chromium from a single checkout.
+
+## `mb gen`
+
+`mb gen` is responsible for generating the Ninja files by invoking 
+either GYP or GN as appropriate. It can be run one of two ways.
+
+With no arguments, `mb gen` looks for a [builds.pyl](#//../builds.pyl)
+file above the checkout for a description of what to build. If no
+builds.pyl file is found, it attempts to do something sane by default;
+for now, it calls `gyp_chromium` with no arguments, but passes through
+the `GYP_DEFINES` env variable if set.
+
+With two arguments (for example, `'mb gen //out/Release
+shared_release'`), `mb gen` builds one specific build directory using
+one specific build config taken from the list of build configs in
+[//build/mb_conf.pyl](#//mb_conf.pyl).
+
+## `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). We
+don't generally expect users to invoke this directly, so see [the design
+spec](design_spec.md#Handling_the_analyze_step) for details.
+
+## debugging (-v/--verbose and -n/--dry-run)
+
+By design, MB should be simple enough that very little can go wrong.
+
+The most obvious issue is that you might see different commands being
+run than you expect; running `'mb -v'` will print what it's doing and
+run the commands; `'mb -n'` will print what it will do but *not* run
+the commands.
+
+If you hit weirder things than that, add some print statements to the
+python script, send a question to gn-dev@chromium.org, or
+[file a bug](https://crbug.com/new) with the label
+'mb' and cc: dpranke@chromium.org.
+
+## //builds/mb_conf.pyl
+
+The `mb_conf.pyl` config file is intended to enumerate all of the
+supported build configurations for Chromium. Generally speaking, you
+should never need to (or want to) build a configuration that isn't
+listed here, and so by using the configs in this file you can avoid
+having to juggle long lists of GYP_DEFINES and gn args by hand.
+
+See [the design spec](design_spec.md#Configurations) for details;
+generally as a user you should only need worry about the list of keys in
+the `build_configs` dictionary at the top of file.
+
+## //../builds.pyl
+
+The builds.pyl allows the user to manage and generate multiple sets of
+build directories at once; it is intended to replace the myriad
+configuration options for GYP without requiring you to have to manually
+manage and update multiple sets of gn args. 
+
+The file should contain a python dict with a list of paths as keys, and
+a list of configurations as values.
+
+For example (quoting the design spec), this:
+
+```
+src% cat ../build.pyl
+{
+  "//out/Release": ["linux_release_trybot"],
+  "//out/Debug.gn": ["gn_shared_debug"],
+}
+src% mbw gen
+src%
+```
+
+is the equivalent of:
+
+```
+src% GYP_DEFINES="use_goma=1 dcheck_always_on=0 dcheck_always_on=1" build/gyp_chromium -G config=Release -G output_dir=out
+src% gn gen //out/Debug.gn --args='use_goma=true dcheck_always_on=true dcheck_always_on=false'
+```
+
+See [the design spec](design_spec.md#Multi-build_support) for more
+details.