docs/cr_user_manual.md

   1 # Cr
   2
   3 Cr is a tool that tries to hide some of the tools used for working on Chromium
   4 behind an abstraction layer. Nothing that cr does can't be done manually, but cr
   5 attempts to make things nicer. Its main additional feature is that it allows you
   6 to build many configurations and run targets within a single checkout (by not
   7 relying on a directory called 'out'). This is especially important when you want
   8 to cross-compile (for instance, building android from linux or building arm from
   9 intel), but it extends to any build variation.
  10
  11 [TOC]
  12
  13 ## A quick example
  14
  15 The following is all you need to prepare an output directory, and then build and
  16 run the release build of chrome for the host platform:
  17
  18 ```shell
  19 cr init
  20 cr run
  21 ```
  22
  23 ## How do I get it?
  24
  25 You already have it, it lives in `src/tools/cr`
  26
  27 You can run the cr.py file by hand, but if you are using bash it is much easier
  28 to source the bash helpers. This will add a cr function to your bash shell that
  29 runs with pyc generation turned off, and also installs the bash tab completion
  30 handler (which is very primitive at the moment, it only completes the command
  31 not the options) It also adds a function you can use in your prompt to tell you
  32 your selected build (`_cr_ps1`), and an helper to return you to the root of your
  33 active tree (`crcd`). I recommend you add the following lines to the end of your
  34 `~/.bashrc` (with a more correct path):
  35
  36 ```shell
  37 CR_CLIENT_PATH="/path/to/chromium"
  38 source ${CR_CLIENT_PATH}/src/tools/cr/cr-bash-helpers.sh
  39 ```
  40
  41 At that point the cr command is available to you.
  42
  43 ## How do I use it?
  44
  45 It should be mostly self documenting
  46
  47     cr --help
  48
  49 will list all the commands installed
  50
  51     cr --help command
  52
  53 will give you more detailed help for a specific command.
  54
  55 _**A note to existing android developers:**_
  56
  57 *   Do not source envsetup! ever!
  58 *   If you use cr in a shell that has had envsetup sourced, miscellaneous things
  59     will be broken. The cr tool does all the work that envsetup used to do in a
  60     way that does not pollute your current shell.
  61 *   If you really need a shell that has had the environment modified like
  62     envsetup used to do, see the cr shell command, also probably file a bug for
  63     a missing cr feature!
  64
  65 ## The commands
  66
  67 Below are some common workflows, but first there is a quick overview of the
  68 commands currently in the system.
  69
  70 ### Output directory commands
  71
  72     init
  73
  74 Create and configure an output directory. Also runs select to make it the
  75 default.
  76
  77     select
  78
  79 Select an output directory. This makes it the default output for all commands,
  80 so you can omit  the --out option if you want to.
  81
  82     prepare
  83
  84 Prepares an output directory. This runs any preparation steps needed for an
  85 output directory to be viable, which at the moment means run gyp.
  86
  87 ### Build commands
  88
  89     build
  90
  91 Build a target.
  92
  93     install
  94
  95 Install a binary. Does build first unless `--builder==skip`. This does nothing
  96 on linux, and installs the apk onto the device for android builds.
  97
  98     run
  99
 100 Invoke a target. Does an install first, unless `--installer=skip`.
 101
 102     debug
 103
 104 Debug a target. Does a run first, unless `--runner=skip`. Uses the debugger
 105 specified by `--debugger`.
 106
 107 ### Other commands
 108
 109     sync
 110
 111 Sync the source tree. Uses gclient sync to do the real work.
 112
 113     shell
 114
 115 Run an exernal command in a cr environment. This is an escape hatch, if passed
 116 a command it runs it in the correct environment for the current output
 117 directory, otherwise it starts a sub shell with that environment. This allows
 118 you to run any commands that don't have shims, or are too specialized to get
 119 one. This is especially important on android where the environment is heavily
 120 modified.
 121
 122 ## Preparing to build
 123
 124 The first thing you need to do is prepare an output directory to build into.
 125 You do this with:
 126
 127     cr init
 128
 129 By default on linux this will prepare a linux x86 release build output
 130 directory, called `out_linux/Release`, if you want an android debug one, you can
 131 use:
 132
 133     cr init --out=out_android/Debug
 134
 135 The output directory can be called anything you like, but if you pick a non
 136 standard name cr might not be able to infer the platform, in which case you need
 137 to specify it. The second part **must** be either Release or Debug. All options
 138 can be shortened to the shortest non ambiguous prefix, so the short command line
 139 to prepare an android debug output directory in out is:
 140
 141     cr init --o=out/Debug --p=android
 142
 143 It is totally safe to do this in an existing output directory, and is an easy
 144 way to migrate an existing output directory to use in cr if you don't want to
 145 start from scratch.
 146
 147 Most commands in cr take a --out parameter to tell them which output directory
 148 you want to operate on, but it will default to the last value passed to init or
 149 select. This enables you to omit it from most commands.
 150
 151 Both init and select do additional work to prepare the output directory, which
 152 include things like running gyp. You can do that work on it's own with the
 153 prepare command if you want, something you need to do when changing between
 154 branches where you have modified the build files.
 155
 156 If you want to set custom GYP defines for your build you can do this by adding
 157 adding the `-s GYP_DEFINES` argument, for example:
 158
 159     cr init --o=out/Debug -s GYP_DEFINES=component=shared_library
 160
 161 ## Running chrome
 162
 163 If you just want to do a basic build and run, then you do
 164
 165     cr run
 166
 167 which will build, install if necessary, and run chrome, with some default args
 168 to open on https://www.google.com/. The same command line will work for any
 169 supported platform and mode. If you want to just run it again, you can turn off
 170 the build and install steps,
 171
 172     cr run --installer=skip
 173
 174 note that turning off install automatically turns off build (which you could do
 175 with `--builder=skip`) as there is no point building if you are not going to
 176 install.
 177
 178 ## Debugging chrome
 179
 180 To start chrome under a debugger you use
 181
 182     cr debug
 183
 184 which will build, install, and run chrome, and attach a debugger to it. This
 185 works on any supported platform, and if multiple debuggers are available, you
 186 can select which one you want with `--debugger=my_debugger`
 187
 188 ## Help, it went wrong!
 189
 190 There are a few things to do, and you should probably do all of them.
 191 Run your commands with dry-run and/or verbose turned on to see what the tool is
 192 really doing, for instance
 193
 194     cr --d -vvvv init
 195
 196 The number of v's matter, it's the verbosity level, you can also just specify
 197 the value with -v=4 if you would rather.
 198
 199 [Report a bug], even if it is just something that confused or annoyed rather
 200 than broke, we want this tool to be very low friction for developers.
 201
 202 ## Known issues
 203
 204 You can see the full list of issues with
 205 [this](https://code.google.com/p/chromium/issues/list?can=2&q=label%3Atool-cr)
 206 query, but here are the high level issues:
 207
 208 *   **Only supports gtest** : You run tests using the run command, which tries
 209     to infer from the target whether it is a runnable binary or a test. The
 210     inference could be improved, and it needs to handle the other test types as
 211     well.
 212 *   **No support for windows or mac** : allowed for in the design, but need
 213     people with expertise on those platforms to help out
 214 *   **Bash completion** : The hooks for it are there, but at the moment it only
 215     ever completes the command, not any of the arguments
 216
 217 [Report a bug]:
 218 https://code.google.com/p/chromium/issues/entry?comment=%3CDont%20forget%20to%20attach%20the%20command%20lines%20used%20with%20-v=4%20if%20possible%3E&pri=2&labels=OS-Android,tool-cr,Build-Tools,Type-Bug&owner=iancottrell@chromium.org&status=Assigned