tools/mb/docs/design_spec.md

   1 # The MB (Meta-Build wrapper) design spec
   2
   3 [TOC]
   4
   5 ## Intro
   6
   7 MB is intended to address two major aspects of the GYP -> GN transition
   8 for Chromium:
   9
  10 1. "bot toggling" - make it so that we can easily flip a given bot
  11    back and forth between GN and GYP.
  12
  13 2. "bot configuration" - provide a single source of truth for all of
  14    the different configurations (os/arch/`gyp_define` combinations) of
  15    Chromium that are supported.
  16
  17 MB must handle at least the `gen` and `analyze` steps on the bots, i.e.,
  18 we need to wrap both the `gyp_chromium` invocation to generate the
  19 Ninja files, and the `analyze` step that takes a list of modified files
  20 and a list of targets to build and returns which targets are affected by
  21 the files.
  22
  23 For more information on how to actually use MB, see
  24 [the user guide](user_guide.md).
  25
  26 ## Design
  27
  28 MB is intended to be as simple as possible, and to defer as much work as
  29 possible to GN or GYP. It should live as a very simple Python wrapper
  30 that offers little in the way of surprises.
  31
  32 ### Command line
  33
  34 It is structured as a single binary that supports a list of subcommands:
  35
  36 * `mb gen -c linux_rel_bot //out/Release`
  37 * `mb analyze -m tryserver.chromium.linux -b linux_rel /tmp/input.json /tmp/output.json`
  38
  39 ### Configurations
  40
  41 `mb` looks in the `//tools/mb/mb_config.pyl` config file to determine whether
  42 to use GYP or GN for a particular build directory, and what set of flags
  43 (`GYP_DEFINES` or `gn args`) to use.
  44
  45 A config can either be specified directly (useful for testing) or by specifying
  46 the master name and builder name (useful on the bots so that they do not need
  47 to specify a config directly and can be hidden from the details).
  48
  49 See the [user guide](user_guide.md#mb_config.pyl) for details.
  50
  51 ### Handling the analyze step
  52
  53 The interface to `mb analyze` is described in the
  54 [user\_guide](user_guide.md#mb_analyze).
  55
  56 Since the interface basically mirrors the way the "analyze" step on the bots
  57 invokes gyp\_chromium today, when the config is found to be a gyp config,
  58 the arguments are passed straight through.
  59
  60 It implements the equivalent functionality in GN by calling `'gn refs
  61 [list of files] --type=executable --all --as=output` and filtering the
  62 output to match the list of targets.
  63
  64 ## Detailed Design Requirements and Rationale
  65
  66 This section is collection of semi-organized notes on why MB is the way
  67 it is ...
  68
  69 ### in-tree or out-of-tree
  70
  71 The first issue is whether or not this should exist as a script in
  72 Chromium at all; an alternative would be to simply change the bot
  73 configurations to know whether to use GYP or GN, and which flags to
  74 pass.
  75
  76 That would certainly work, but experience over the past two years
  77 suggests a few things:
  78
  79   * we should push as much logic as we can into the source repositories
  80     so that they can be versioned and changed atomically with changes to
  81     the product code; having to coordinate changes between src/ and
  82     build/ is at best annoying and can lead to weird errors.
  83   * the infra team would really like to move to providing
  84     product-independent services (i.e., not have to do one thing for
  85     Chromium, another for NaCl, a third for V8, etc.).
  86   * we found that during the SVN->GIT migration the ability to flip bot
  87     configurations between the two via changes to a file in chromium
  88     was very useful.
  89
  90 All of this suggests that the interface between bots and Chromium should
  91 be a simple one, hiding as much of the chromium logic as possible.
  92
  93 ### Why not have MB be smarter about de-duping flags?
  94
  95 This just adds complexity to the MB implementation, and duplicates logic
  96 that GYP and GN already have to support anyway; in particular, it might
  97 require MB to know how to parse GYP and GN values. The belief is that
  98 if MB does *not* do this, it will lead to fewer surprises.
  99
 100 It will not be hard to change this if need be.
 101
 102 ### Integration w/ gclient runhooks
 103
 104 On the bots, we will disable `gyp_chromium` as part of runhooks (using
 105 `GYP_CHROMIUM_NO_ACTION=1`), so that mb shows up as a separate step.
 106
 107 At the moment, we expect most developers to either continue to use
 108 `gyp_chromium` in runhooks or to disable at as above if they have no
 109 use for GYP at all. We may revisit how this works once we encourage more
 110 people to use GN full-time (i.e., we might take `gyp_chromium` out of
 111 runhooks altogether).
 112
 113 ### Config per flag set or config per (os/arch/flag set)?
 114
 115 Currently, mb_config.pyl does not specify the host_os, target_os, host_cpu, or
 116 target_cpu values for every config that Chromium runs on, it only specifies
 117 them for when the values need to be explicitly set on the command line.
 118
 119 Instead, we have one config per unique combination of flags only.
 120
 121 In other words, rather than having `linux_rel_bot`, `win_rel_bot`, and
 122 `mac_rel_bot`, we just have `rel_bot`.
 123
 124 This design allows us to determine easily all of the different sets
 125 of flags that we need to support, but *not* which flags are used on which
 126 host/target combinations.
 127
 128 It may be that we should really track the latter. Doing so is just a
 129 config file change, however.
 130
 131 ### Non-goals
 132
 133 * MB is not intended to replace direct invocation of GN or GYP for
 134   complicated build scenarios (aka ChromeOS), where multiple flags need
 135   to be set to user-defined paths for specific toolchains (e.g., where
 136   ChromeOS needs to specify specific board types and compilers).
 137
 138 * MB is not intended at this time to be something developers use frequently,
 139   or to add a lot of features to. We hope to be able to get rid of it once
 140   the GYP->GN migration is done, and so we should not add things for
 141   developers that can't easily be added to GN itself.
 142
 143 * MB is not intended to replace the
 144   [CR tool](https://code.google.com/p/chromium/wiki/CRUserManual). Not
 145   only is it only intended to replace the gyp\_chromium part of `'gclient
 146   runhooks'`, it is not really meant as a developer-facing tool.
 147
 148 ### Open issues
 149
 150 * Some common flags (goma\_dir being the obvious one) may need to be
 151   specified via the user, and it's unclear how to integrate this with
 152   the concept of build\_configs.
 153
 154   Right now, MB has hard-coded support for a few flags (i.e., you can
 155   pass the --goma-dir flag, and it will know to expand "${goma\_dir}" in
 156   the string before calling out to the tool. We may want to generalize
 157   this to a common key/value approach (perhaps then meeting the
 158   ChromeOS non-goal, above), or we may want to keep this very strictly
 159   limited for simplicity.