Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(134)

Side by Side Diff: docs/closure_compilation.md

Issue 1306233003: Markdown style fixes for: (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: style changes Created 5 years, 3 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « docs/clang_tool_refactoring.md ('k') | docs/cocoa_tips_and_tricks.md » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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
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
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 ```
OLDNEW
« no previous file with comments | « docs/clang_tool_refactoring.md ('k') | docs/cocoa_tips_and_tricks.md » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698