OLD | NEW |
1 # Cr | 1 # Cr |
2 | 2 |
3 Cr is a tool that tries to hide some of the tools used for working on Chromium | 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 | 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 | 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 | 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 | 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 | 8 to cross-compile (for instance, building Android from Linux or building arm from |
9 intel), but it extends to any build variation. | 9 intel), but it extends to any build variation. |
10 | 10 |
11 [TOC] | 11 [TOC] |
12 | 12 |
13 ## A quick example | 13 ## A quick example |
14 | 14 |
15 The following is all you need to prepare an output directory, and then build and | 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: | 16 run the release build of chrome for the host platform: |
17 | 17 |
18 ```shell | 18 ```shell |
(...skipping 26 matching lines...) Expand all Loading... |
45 It should be mostly self documenting | 45 It should be mostly self documenting |
46 | 46 |
47 cr --help | 47 cr --help |
48 | 48 |
49 will list all the commands installed | 49 will list all the commands installed |
50 | 50 |
51 cr --help command | 51 cr --help command |
52 | 52 |
53 will give you more detailed help for a specific command. | 53 will give you more detailed help for a specific command. |
54 | 54 |
55 _**A note to existing android developers:**_ | 55 _**A note to existing Android developers:**_ |
56 | 56 |
57 * Do not source envsetup! ever! | 57 * Do not source envsetup! ever! |
58 * If you use cr in a shell that has had envsetup sourced, miscellaneous things | 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 | 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. | 60 way that does not pollute your current shell. |
61 * If you really need a shell that has had the environment modified like | 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 | 62 envsetup used to do, see the cr shell command, also probably file a bug for |
63 a missing cr feature! | 63 a missing cr feature! |
64 | 64 |
65 ## The commands | 65 ## The commands |
(...skipping 20 matching lines...) Expand all Loading... |
86 | 86 |
87 ### Build commands | 87 ### Build commands |
88 | 88 |
89 build | 89 build |
90 | 90 |
91 Build a target. | 91 Build a target. |
92 | 92 |
93 install | 93 install |
94 | 94 |
95 Install a binary. Does build first unless `--builder==skip`. This does nothing | 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. | 96 on Linux, and installs the apk onto the device for Android builds. |
97 | 97 |
98 run | 98 run |
99 | 99 |
100 Invoke a target. Does an install first, unless `--installer=skip`. | 100 Invoke a target. Does an install first, unless `--installer=skip`. |
101 | 101 |
102 debug | 102 debug |
103 | 103 |
104 Debug a target. Does a run first, unless `--runner=skip`. Uses the debugger | 104 Debug a target. Does a run first, unless `--runner=skip`. Uses the debugger |
105 specified by `--debugger`. | 105 specified by `--debugger`. |
106 | 106 |
107 ### Other commands | 107 ### Other commands |
108 | 108 |
109 sync | 109 sync |
110 | 110 |
111 Sync the source tree. Uses gclient sync to do the real work. | 111 Sync the source tree. Uses gclient sync to do the real work. |
112 | 112 |
113 shell | 113 shell |
114 | 114 |
115 Run an exernal command in a cr environment. This is an escape hatch, if passed | 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 | 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 | 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 | 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 | 119 one. This is especially important on Android where the environment is heavily |
120 modified. | 120 modified. |
121 | 121 |
122 ## Preparing to build | 122 ## Preparing to build |
123 | 123 |
124 The first thing you need to do is prepare an output directory to build into. | 124 The first thing you need to do is prepare an output directory to build into. |
125 You do this with: | 125 You do this with: |
126 | 126 |
127 cr init | 127 cr init |
128 | 128 |
129 By default on linux this will prepare a linux x86 release build output | 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 | 130 directory, called `out_linux/Release`, if you want an Android debug one, you can |
131 use: | 131 use: |
132 | 132 |
133 cr init --out=out_android/Debug | 133 cr init --out=out_android/Debug |
134 | 134 |
135 The output directory can be called anything you like, but if you pick a non | 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 | 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 | 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 | 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: | 139 to prepare an Android debug output directory in out is: |
140 | 140 |
141 cr init --o=out/Debug --p=android | 141 cr init --o=out/Debug --p=android |
142 | 142 |
143 It is totally safe to do this in an existing output directory, and is an easy | 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 | 144 way to migrate an existing output directory to use in cr if you don't want to |
145 start from scratch. | 145 start from scratch. |
146 | 146 |
147 Most commands in cr take a --out parameter to tell them which output directory | 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 | 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. | 149 select. This enables you to omit it from most commands. |
(...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
202 ## Known issues | 202 ## Known issues |
203 | 203 |
204 You can see the full list of issues with | 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) | 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: | 206 query, but here are the high level issues: |
207 | 207 |
208 * **Only supports gtest** : You run tests using the run command, which tries | 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 | 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 | 210 inference could be improved, and it needs to handle the other test types as |
211 well. | 211 well. |
212 * **No support for windows or mac** : allowed for in the design, but need | 212 * **No support for Windows or Mac** : allowed for in the design, but need |
213 people with expertise on those platforms to help out | 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 | 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 | 215 ever completes the command, not any of the arguments |
216 | 216 |
217 [Report a bug]: | 217 [Report a bug]: |
218 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 | 218 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 |