tools/mb/docs/user_guide.md

   1 # The MB (Meta-Build wrapper) user guide
   2
   3 [TOC]
   4
   5 ## Introduction
   6
   7 `mb` is a simple python wrapper around the GYP and GN meta-build tools to
   8 be used as part of the GYP->GN migration.
   9
  10 It is intended to be used by bots to make it easier to manage the configuration
  11 each bot builds (i.e., the configurations can be changed from chromium
  12 commits), and to consolidate the list of all of the various configurations
  13 that Chromium is built in.
  14
  15 Ideally this tool will no longer be needed after the migration is complete.
  16
  17 ## `mb gen`
  18
  19 `mb gen` is responsible for generating the Ninja files by invoking either GYP
  20 or GN as appropriate. It takes arguments to specify a build config and
  21 a directory, then runs GYP or GN as appropriate:
  22
  23 ```
  24 % mb gen -m tryserver.chromium.linux -b linux_rel //out/Release
  25 % mb gen -c linux_rel_trybot //out/Release
  26 ```
  27
  28 Either the `-c/--config` flag or the `-m/--master` and `-b/--builder` flags
  29 must be specified so that `mb` can figure out which config to use.
  30
  31 The path must be a GN-style "source-absolute" path (as above).
  32
  33 If gen ends up using GYP, the path must have a valid GYP configuration as the
  34 last component of the path (i.e., specify `//out/Release_x64`, not `//out`).
  35
  36 ## `mb analyze`
  37
  38 `mb analyze` is reponsible for determining what targets are affected by
  39 a list of files (e.g., the list of files in a patch on a trybot):
  40
  41 ```
  42 mb analyze -c chromium_linux_rel //out/Release input.json output.json
  43 ```
  44
  45 Either the `-c/--config` flag or the `-m/--master` and `-b/--builder` flags
  46 must be specified so that `mb` can figure out which config to use.
  47
  48
  49 The first positional argument must be a GN-style "source-absolute" path
  50 to the build directory.
  51
  52 The second positional argument is a (normal) path to a JSON file containing
  53 a single object with two fields:
  54
  55   * `files`: an array of the modified filenames to check (as
  56     paths relative to the checkout root).
  57   * `targets`: an array of the unqualified target names to check.
  58
  59 The third positional argument is a (normal) path to where mb will write
  60 the result, also as a JSON object. This object may contain the following
  61 fields:
  62
  63   * `error`: this should only be present if something failed.
  64   * `targets`: the subset of the input `targets` that depend on the
  65     input `files`.
  66   * `build_targets`: the minimal subset of targets needed to build all
  67     of `targets` that were affected.
  68   * `status`: one of three strings:
  69     * `"Found dependency"` (build the `build_targets`)
  70     * `"No dependency"` (i.e., no build needed)
  71     * `"Found dependency (all)"` (build everything, in which case
  72       `targets` and `build_targets` are not returned).
  73
  74 ## `mb help`
  75
  76 Produces help output on the other subcommands
  77
  78 ## `mb lookup`
  79
  80 Prints what command will be run by `mb gen` (like `mb gen -n` but does
  81 not require you to specify a path).
  82
  83 ## `mb validate`
  84
  85 Does internal checking to make sure the config file is syntactically
  86 valid and that all of the entries are used properly. It does not validate
  87 that the flags make sense, or that the builder names are legal or
  88 comprehensive, but it does complain about configs and mixins that aren't
  89 used.
  90
  91 This is mostly useful as a presubmit check and for verifying changes to
  92 the config file.
  93
  94 ## mb_config.pyl
  95
  96 The `mb_config.pyl` config file is intended to enumerate all of the
  97 supported build configurations for Chromium. Generally speaking, you
  98 should never need to (or want to) build a configuration that isn't
  99 listed here, and so by using the configs in this file you can avoid
 100 having to juggle long lists of GYP_DEFINES and gn args by hand.
 101
 102 `mb_config.pyl` is structured as a file containing a single PYthon Literal
 103 expression: a dictionary with three main keys, `masters`, `configs` and
 104 `mixins`.
 105
 106 The `masters` key contains a nested series of dicts containing mappings
 107 of master -> builder -> config . This allows us to isolate the buildbot
 108 recipes from the actual details of the configs.
 109
 110 The `configs` key points to a dictionary of named build
 111 configurations.
 112
 113 There should be an key in this dict for every supported configuration
 114 of Chromium, meaning every configuration we have a bot for, and every
 115 configuration commonly used by develpers but that we may not have a bot
 116 for.
 117
 118 The value of each key is a list of "mixins" that will define what that
 119 build_config does. Each item in the list must be an entry in the dictionary
 120 value of the `mixins` key.
 121
 122 Each mixin value is itself a dictionary that contains one or more of the
 123 following keys:
 124
 125   * `gyp_configs`: a list of the configurations to build, e.g.,
 126     ['Release', 'Release_x64'].
 127   * `gyp_defines`: a string containing a list of GYP_DEFINES.
 128   * `gn_args`: a string containing a list of values passed to gn --args.
 129   * `mixins`: a list of other mixins that should be included.
 130   * `type`: a string with either the value `gyp` or `gn`;
 131     setting this indicates which meta-build tool to use.
 132
 133 When `mb gen` or `mb analyze` executes, it takes a config name, looks it
 134 up in the 'configs' dict, and then does a left-to-right expansion of the
 135 mixins; gyp_defines and gn_args values are concatenated, and type and
 136 gyp_configs values override each other.
 137
 138 For example, if you had:
 139
 140 ```
 141 {
 142   'configs`: {
 143     'linux_release_trybot': ['gyp_release', 'trybot'],
 144     'gn_shared_debug': None,
 145   }
 146   'mixins': {
 147     'bot': {
 148       'gyp_defines': 'use_goma=1 dcheck_always_on=0',
 149       'gn_args': 'use_goma=true dcheck_always_on=false',
 150     },
 151     'debug': {
 152       'gn_args': 'is_debug=true',
 153     },
 154     'gn': {'type': 'gn'},
 155     'gyp_release': {
 156       'gyp_config': 'Release'
 157       'mixins': ['release'],
 158       'type': 'gyp',
 159     },
 160     'release': {
 161       'gn_args': 'is_debug=false',
 162     }
 163     'shared': {
 164       'gn_args': 'is_component_build=true',
 165       'gyp_defines': 'component=shared_library',
 166     },
 167     'trybot': {
 168       'gyp_defines': 'dcheck_always_on=1',
 169       'gn_args': 'dcheck_always_on=true',
 170     }
 171   }
 172 }
 173
 174 and you ran `mb gen -c linux_release_trybot //out/Release`, it would
 175 translate into a call to `gyp_chromium -G Release` with `GYP_DEFINES` set to
 176 `"use_goma=true dcheck_always_on=false dcheck_always_on=true"`.
 177
 178 (From that you can see that mb is intentionally dumb and does not
 179 attempt to de-dup the flags, it lets gyp do that).
 180
 181 ## Debugging (-v/--verbose and -n/--dry-run)
 182
 183 By design, MB should be simple enough that very little can go wrong.
 184
 185 The most obvious issue is that you might see different commands being
 186 run than you expect; running `'mb -v'` will print what it's doing and
 187 run the commands; `'mb -n'` will print what it will do but *not* run
 188 the commands.
 189
 190 If you hit weirder things than that, add some print statements to the
 191 python script, send a question to gn-dev@chromium.org, or
 192 [file a bug](https://crbug.com/new) with the label
 193 'mb' and cc: dpranke@chromium.org.
 194
 195