OLD | NEW |
1 # I just need to fix the compile! | 1 # Closure Compilation |
2 | 2 |
| 3 ## I just need to fix the compile! |
| 4 |
3 To locally run closure compiler like the bots, do this: | 5 To locally run closure compiler like the bots, do this: |
4 | 6 |
5 ``` | 7 ```shell |
6 cd $CHROMIUM_SRC | 8 cd $CHROMIUM_SRC |
7 # sudo apt-get install openjdk-7-jre # may be required | 9 # sudo apt-get install openjdk-7-jre # may be required |
8 GYP_GENERATORS=ninja tools/gyp/gyp --depth . third_party/closure_compiler/compil
ed_resources.gyp | 10 GYP_GENERATORS=ninja tools/gyp/gyp --depth . \ |
| 11 third_party/closure_compiler/compiled_resources.gyp |
9 ninja -C out/Default | 12 ninja -C out/Default |
10 ``` | 13 ``` |
11 | 14 |
12 # Background | 15 ## Background |
13 | 16 |
14 In C++ and Java, compiling the code gives you _some_ level of protection against
misusing variables based on their type information. JavaScript is loosely type
d and therefore doesn't offer this safety. This makes writing JavaScript more e
rror prone as it's _one more thing_ to mess up. | 17 In C++ and Java, compiling the code gives you _some_ level of protection against |
| 18 misusing variables based on their type information. JavaScript is loosely typed |
| 19 and therefore doesn't offer this safety. This makes writing JavaScript more |
| 20 error prone as it's _one more thing_ to mess up. |
15 | 21 |
16 Because having this safety is handy, Chrome now has a way to optionally typechec
k your JavaScript and produce compiled output with [Closure Compiler](https://de
velopers.google.com/closure/compiler/). | 22 Because having this safety is handy, Chrome now has a way to optionally |
| 23 typecheck your JavaScript and produce compiled output with |
| 24 [Closure Compiler](https://developers.google.com/closure/compiler/). |
17 | 25 |
18 See also: [the design doc](https://docs.google.com/a/chromium.org/document/d/1Ee
9ggmp6U-lM-w9WmxN5cSLkK9B5YAq14939Woo-JY0/edit). | 26 See also: |
| 27 [the design doc](https://docs.google.com/a/chromium.org/document/d/1Ee9ggmp6U-lM
-w9WmxN5cSLkK9B5YAq14939Woo-JY0/edit). |
19 | 28 |
20 # Assumptions | 29 ## Assumptions |
21 | 30 |
22 A working Chrome checkout. See here: http://www.chromium.org/developers/how-tos
/get-the-code | 31 A working Chrome checkout. See here: |
| 32 http://www.chromium.org/developers/how-tos/get-the-code |
23 | 33 |
24 # Typechecking Your Javascript | 34 ## Typechecking Your Javascript |
25 | 35 |
26 So you'd like to compile your JavaScript! | 36 So you'd like to compile your JavaScript! |
27 | 37 |
28 Maybe you're working on a page that looks like this: | 38 Maybe you're working on a page that looks like this: |
29 | 39 |
30 ``` | 40 ```html |
31 <script src="other_file.js"></script> | 41 <script src="other_file.js"></script> |
32 <script src="my_product/my_file.js"></script> | 42 <script src="my_product/my_file.js"></script> |
33 ``` | 43 ``` |
34 | 44 |
35 Where `other_file.js` contains: | 45 Where `other_file.js` contains: |
36 | 46 |
37 ``` | 47 ```javascript |
38 var wit = 100; | 48 var wit = 100; |
39 | 49 |
40 // ... later on, sneakily ... | 50 // ... later on, sneakily ... |
41 | 51 |
42 wit += ' IQ'; // '100 IQ' | 52 wit += ' IQ'; // '100 IQ' |
43 ``` | 53 ``` |
44 | 54 |
45 and `src/my_product/my_file.js` contains: | 55 and `src/my_product/my_file.js` contains: |
46 | 56 |
47 ``` | 57 ```javascript |
48 /** @type {number} */ var mensa = wit + 50; | 58 /** @type {number} */ var mensa = wit + 50; |
49 alert(mensa); // '100 IQ50' instead of 150 | 59 alert(mensa); // '100 IQ50' instead of 150 |
50 ``` | 60 ``` |
51 | 61 |
52 In order to check that our code acts as we'd expect, we can create a | 62 In order to check that our code acts as we'd expect, we can create a |
53 | 63 |
54 ``` | 64 my_project/compiled_resources.gyp |
55 my_project/compiled_resources.gyp | |
56 ``` | |
57 | 65 |
58 with the contents: | 66 with the contents: |
59 | 67 |
60 ``` | 68 ``` |
61 # Copyright 2015 The Chromium Authors. All rights reserved. | 69 # Copyright 2015 The Chromium Authors. All rights reserved. |
62 # Use of this source code is governed by a BSD-style license that can be | 70 # Use of this source code is governed by a BSD-style license that can be |
63 # found in the LICENSE file. | 71 # found in the LICENSE file. |
64 { | 72 { |
65 'targets': [ | 73 'targets': [ |
66 { | 74 { |
(...skipping 18 matching lines...) Expand all Loading... |
85 | 93 |
86 ``` | 94 ``` |
87 (ERROR) Error in: my_project/my_file.js | 95 (ERROR) Error in: my_project/my_file.js |
88 ## /my/home/chromium/src/my_project/my_file.js:1: ERROR - initializing variable | 96 ## /my/home/chromium/src/my_project/my_file.js:1: ERROR - initializing variable |
89 ## found : string | 97 ## found : string |
90 ## required: number | 98 ## required: number |
91 ## /** @type {number} */ var mensa = wit + 50; | 99 ## /** @type {number} */ var mensa = wit + 50; |
92 ## ^ | 100 ## ^ |
93 ``` | 101 ``` |
94 | 102 |
95 Yay! We can easily find our unexpected type errors and write less error-prone c
ode! | 103 Yay! We can easily find our unexpected type errors and write less error-prone |
| 104 code! |
96 | 105 |
97 # Continuous Checking | 106 ## Continuous Checking |
98 | 107 |
99 To compile your code on every commit, add a line to [third\_party/closure\_compi
ler/compiled\_resources.gyp](https://code.google.com/p/chromium/codesearch#chrom
ium/src/third_party/closure_compiler/compiled_resources.gyp&sq=package:chromium&
type=cs) like this: | 108 To compile your code on every commit, add a line to |
| 109 /third_party/closure_compiler/compiled_resources.gyp |
| 110 like this: |
100 | 111 |
101 ``` | 112 ``` |
102 { | 113 { |
103 'targets': [ | 114 'targets': [ |
104 { | 115 { |
105 'target_name': 'compile_all_resources', | 116 'target_name': 'compile_all_resources', |
106 'dependencies': [ | 117 'dependencies': [ |
107 # ... other projects ... | 118 # ... other projects ... |
108 ++ '../my_project/compiled_resources.gyp:*', | 119 ++ '../my_project/compiled_resources.gyp:*', |
109 ], | 120 ], |
110 } | 121 } |
111 ] | 122 ] |
112 } | 123 } |
113 ``` | 124 ``` |
114 | 125 |
115 and the [Closure compiler bot](http://build.chromium.org/p/chromium.fyi/builders
/Closure%20Compilation%20Linux) will [re-]compile your code whenever relevant .j
s files change. | 126 and the |
| 127 [Closure compiler bot](http://build.chromium.org/p/chromium.fyi/builders/Closure
%20Compilation%20Linux) |
| 128 will [re-]compile your code whenever relevant .js files change. |
116 | 129 |
117 # Using Compiled JavaScript | 130 ## Using Compiled JavaScript |
118 | 131 |
119 Compiled JavaScript is output in src/out/<Debug|Release>/gen/closure/my\_project
/my\_file.js along with a source map for use in debugging. In order to use the c
ompiled JavaScript, we can create a | 132 Compiled JavaScript is output in |
| 133 `src/out/<Debug|Release>/gen/closure/my_project/my_file.js` along with a source |
| 134 map for use in debugging. In order to use the compiled JavaScript, we can create |
| 135 a |
120 | 136 |
121 ``` | 137 my_project/my_project_resources.gpy |
122 my_project/my_project_resources.gpy | |
123 ``` | |
124 | 138 |
125 with the contents: | 139 with the contents: |
126 | 140 |
127 ``` | 141 ``` |
128 # Copyright 2015 The Chromium Authors. All rights reserved. | 142 # Copyright 2015 The Chromium Authors. All rights reserved. |
129 # Use of this source code is governed by a BSD-style license that can be | 143 # Use of this source code is governed by a BSD-style license that can be |
130 # found in the LICENSE file. | 144 # found in the LICENSE file. |
131 | 145 |
132 { | 146 { |
133 'targets': [ | 147 'targets': [ |
(...skipping 17 matching lines...) Expand all Loading... |
151 }, | 165 }, |
152 'includes': [ '../build/grit_action.gypi' ], | 166 'includes': [ '../build/grit_action.gypi' ], |
153 }, | 167 }, |
154 ], | 168 ], |
155 'includes': [ '../build/grit_target.gypi' ], | 169 'includes': [ '../build/grit_target.gypi' ], |
156 }, | 170 }, |
157 ], | 171 ], |
158 } | 172 } |
159 ``` | 173 ``` |
160 | 174 |
161 The variables can also be defined in an existing .gyp file if appropriate. The v
ariables can then be used in to create a | 175 The variables can also be defined in an existing .gyp file if appropriate. The |
| 176 variables can then be used in to create a |
162 | 177 |
163 ``` | 178 my_project/my_project_resources.grd |
164 my_project/my_project_resources.grd | |
165 ``` | |
166 | 179 |
167 with the contents: | 180 with the contents: |
168 | 181 |
169 ``` | 182 ``` |
170 <?xml version="1.0" encoding="utf-8"?> | 183 <?xml version="1.0" encoding="utf-8"?> |
171 <grit-part> | 184 <grit-part> |
172 <include name="IDR_MY_FILE_GEN_JS" file="${my_file_gen_js}" use_base_dir="fals
e" type="BINDATA" /> | 185 <include name="IDR_MY_FILE_GEN_JS" file="${my_file_gen_js}" use_base_dir="fals
e" type="BINDATA" /> |
173 </grit-part> | 186 </grit-part> |
174 ``` | 187 ``` |
175 | 188 |
176 In your C++, the resource can be retrieved like this: | 189 In your C++, the resource can be retrieved like this: |
177 ``` | 190 ``` |
178 base::string16 my_script = | 191 base::string16 my_script = |
179 base::UTF8ToUTF16( | 192 base::UTF8ToUTF16( |
180 ResourceBundle::GetSharedInstance() | 193 ResourceBundle::GetSharedInstance() |
181 .GetRawDataResource(IDR_MY_FILE_GEN_JS) | 194 .GetRawDataResource(IDR_MY_FILE_GEN_JS) |
182 .as_string()); | 195 .as_string()); |
183 ``` | 196 ``` |
184 | 197 |
185 # Debugging Compiled JavaScript | 198 ## Debugging Compiled JavaScript |
186 | 199 |
187 Along with the compiled JavaScript, a source map is created: src/out/<Debug|Rele
ase>/gen/closure/my\_project/my\_file.js.map | 200 Along with the compiled JavaScript, a source map is created: |
| 201 `src/out/<Debug|Release>/gen/closure/my_project/my_file.js.map` |
188 | 202 |
189 Chrome DevTools has built in support for working with source maps: [https://deve
loper.chrome.com/devtools/docs/javascript-debugging#source-maps](https://develop
er.chrome.com/devtools/docs/javascript-debugging#source-maps) | 203 Chrome DevTools has built in support for working with source maps: |
| 204 https://developer.chrome.com/devtools/docs/javascript-debugging#source-maps |
190 | 205 |
191 In order to use the source map, you must first manually edit the path to the 'so
urces' in the .js.map file that was generated. For example, if the source map lo
oks like this: | 206 In order to use the source map, you must first manually edit the path to the |
| 207 'sources' in the .js.map file that was generated. For example, if the source map |
| 208 looks like this: |
| 209 |
192 ``` | 210 ``` |
193 { | 211 { |
194 "version":3, | 212 "version":3, |
195 "file":"/tmp/gen/test_script.js", | 213 "file":"/tmp/gen/test_script.js", |
196 "lineCount":1, | 214 "lineCount":1, |
197 "mappings":"A,aAAA,IAAIA,OAASA,QAAQ,EAAG,CACtBC,KAAA,CAAM,OAAN,CADsB;", | 215 "mappings":"A,aAAA,IAAIA,OAASA,QAAQ,EAAG,CACtBC,KAAA,CAAM,OAAN,CADsB;", |
198 "sources":["/tmp/tmp70_QUi"], | 216 "sources":["/tmp/tmp70_QUi"], |
199 "names":["fooBar","alert"] | 217 "names":["fooBar","alert"] |
200 } | 218 } |
201 ``` | 219 ``` |
202 | 220 |
203 sources should be changed to: | 221 sources should be changed to: |
| 222 |
204 ``` | 223 ``` |
205 ... | 224 ... |
206 "sources":["/tmp/test_script.js"], | 225 "sources":["/tmp/test_script.js"], |
207 ... | 226 ... |
208 ``` | 227 ``` |
209 | 228 |
210 In your browser, the source map can be loaded through the Chrome DevTools contex
t menu that appears when you right click in the compiled JavaScript source body.
A dialog will pop up prompting you for the path to the source map file. Once th
e source map is loaded, the uncompiled version of the JavaScript will appear in
the Sources panel on the left. You can set break points in the uncompiled versio
n to help debug; behind the scenes Chrome will still be running the compiled ver
sion of the JavaScript. | 229 In your browser, the source map can be loaded through the Chrome DevTools |
| 230 context menu that appears when you right click in the compiled JavaScript source |
| 231 body. A dialog will pop up prompting you for the path to the source map file. |
| 232 Once the source map is loaded, the uncompiled version of the JavaScript will |
| 233 appear in the Sources panel on the left. You can set break points in the |
| 234 uncompiled version to help debug; behind the scenes Chrome will still be running |
| 235 the compiled version of the JavaScript. |
211 | 236 |
212 # Additional Arguments | 237 ## Additional Arguments |
213 | 238 |
214 compile\_js.gypi accepts an optional script\_args variable, which passes additio
nal arguments to compile.py, as well as an optional closure\_args variable, whic
h passes additional arguments to the closure compiler. You may also override the
disabled\_closure\_args for more strict compilation. | 239 `compile_js.gypi` accepts an optional `script_args` variable, which passes |
| 240 additional arguments to `compile.py`, as well as an optional `closure_args` |
| 241 variable, which passes additional arguments to the closure compiler. You may |
| 242 also override the `disabled_closure_args` for more strict compilation. |
215 | 243 |
216 For example, if you would like to specify multiple sources, strict compilation,
and an output wrapper, you would create a | 244 For example, if you would like to specify multiple sources, strict compilation, |
| 245 and an output wrapper, you would create a |
217 | 246 |
218 ``` | 247 ``` |
219 my_project/compiled_resources.gyp | 248 my_project/compiled_resources.gyp |
220 ``` | 249 ``` |
221 | 250 |
222 with contents similar to this: | 251 with contents similar to this: |
223 ``` | 252 ``` |
224 # Copyright 2015 The Chromium Authors. All rights reserved. | 253 # Copyright 2015 The Chromium Authors. All rights reserved. |
225 # Use of this source code is governed by a BSD-style license that can be | 254 # Use of this source code is governed by a BSD-style license that can be |
226 # found in the LICENSE file. | 255 # found in the LICENSE file. |
(...skipping 12 matching lines...) Expand all Loading... |
239 'jscomp_error=reportUnknownTypes', # the following three provide m
ore strict compilation | 268 'jscomp_error=reportUnknownTypes', # the following three provide m
ore strict compilation |
240 'jscomp_error=duplicate', | 269 'jscomp_error=duplicate', |
241 'jscomp_error=misplacedTypeAnnotation', | 270 'jscomp_error=misplacedTypeAnnotation', |
242 ], | 271 ], |
243 'disabled_closure_args': [], # remove the disabled closure args for more
strict compilation | 272 'disabled_closure_args': [], # remove the disabled closure args for more
strict compilation |
244 }, | 273 }, |
245 'includes': ['../third_party/closure_compiler/compile_js.gypi'], | 274 'includes': ['../third_party/closure_compiler/compile_js.gypi'], |
246 }, | 275 }, |
247 ], | 276 ], |
248 } | 277 } |
249 ``` | 278 ``` |
OLD | NEW |