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