blob: f164d4cbfe4a9581b4102b22cb23c50233753ec2 [file] [log] [blame] [view]
andybons6eaa0c0d2015-08-26 20:12:521# Closure Compilation
2
3## I just need to fix the compile!
andybons3322f762015-08-24 21:37:094
5To locally run closure compiler like the bots, do this:
6
andybons6eaa0c0d2015-08-26 20:12:527```shell
andybons3322f762015-08-24 21:37:098cd $CHROMIUM_SRC
9# sudo apt-get install openjdk-7-jre # may be required
andybons6eaa0c0d2015-08-26 20:12:5210GYP_GENERATORS=ninja tools/gyp/gyp --depth . \
11third_party/closure_compiler/compiled_resources.gyp
andybons3322f762015-08-24 21:37:0912ninja -C out/Default
13```
14
andybons6eaa0c0d2015-08-26 20:12:5215## Background
andybons3322f762015-08-24 21:37:0916
andybons6eaa0c0d2015-08-26 20:12:5217In C++ and Java, compiling the code gives you _some_ level of protection against
18misusing variables based on their type information. JavaScript is loosely typed
19and therefore doesn't offer this safety. This makes writing JavaScript more
20error prone as it's _one more thing_ to mess up.
andybons3322f762015-08-24 21:37:0921
andybons6eaa0c0d2015-08-26 20:12:5222Because having this safety is handy, Chrome now has a way to optionally
23typecheck your JavaScript and produce compiled output with
24[Closure Compiler](https://developers.google.com/closure/compiler/).
andybons3322f762015-08-24 21:37:0925
andybons6eaa0c0d2015-08-26 20:12:5226See also:
27[the design doc](https://docs.google.com/a/chromium.org/document/d/1Ee9ggmp6U-lM-w9WmxN5cSLkK9B5YAq14939Woo-JY0/edit).
andybons3322f762015-08-24 21:37:0928
andybons6eaa0c0d2015-08-26 20:12:5229## Assumptions
andybons3322f762015-08-24 21:37:0930
andybons6eaa0c0d2015-08-26 20:12:5231A working Chrome checkout. See here:
32http://www.chromium.org/developers/how-tos/get-the-code
andybons3322f762015-08-24 21:37:0933
andybons6eaa0c0d2015-08-26 20:12:5234## Typechecking Your Javascript
andybons3322f762015-08-24 21:37:0935
36So you'd like to compile your JavaScript!
37
38Maybe you're working on a page that looks like this:
39
andybons6eaa0c0d2015-08-26 20:12:5240```html
andybons3322f762015-08-24 21:37:0941<script src="other_file.js"></script>
42<script src="my_product/my_file.js"></script>
43```
44
45Where `other_file.js` contains:
46
andybons6eaa0c0d2015-08-26 20:12:5247```javascript
andybons3322f762015-08-24 21:37:0948var wit = 100;
49
50// ... later on, sneakily ...
51
52wit += ' IQ'; // '100 IQ'
53```
54
55and `src/my_product/my_file.js` contains:
56
andybons6eaa0c0d2015-08-26 20:12:5257```javascript
andybons3322f762015-08-24 21:37:0958/** @type {number} */ var mensa = wit + 50;
59alert(mensa); // '100 IQ50' instead of 150
60```
61
62In order to check that our code acts as we'd expect, we can create a
63
andybons6eaa0c0d2015-08-26 20:12:5264 my_project/compiled_resources.gyp
andybons3322f762015-08-24 21:37:0965
66with the contents:
67
68```
69# Copyright 2015 The Chromium Authors. All rights reserved.
70# Use of this source code is governed by a BSD-style license that can be
71# found in the LICENSE file.
72{
73 'targets': [
74 {
75 'target_name': 'my_file', # file name without ".js"
76
77 'variables': { # Only use if necessary (no need to specify empty lists).
78 'depends': [
79 'other_file.js', # or 'other_project/compiled_resources.gyp:target',
80 ],
81 'externs': [
82 '<(CLOSURE_DIR)/externs/any_needed_externs.js' # e.g. chrome.send(), chrome.app.window, etc.
83 ],
84 },
85
86 'includes': ['../third_party/closure_compiler/compile_js.gypi'],
87 },
88 ],
89}
90```
91
92You should get results like:
93
94```
95(ERROR) Error in: my_project/my_file.js
96## /my/home/chromium/src/my_project/my_file.js:1: ERROR - initializing variable
97## found : string
98## required: number
99## /** @type {number} */ var mensa = wit + 50;
100## ^
101```
102
andybons6eaa0c0d2015-08-26 20:12:52103Yay! We can easily find our unexpected type errors and write less error-prone
104code!
andybons3322f762015-08-24 21:37:09105
andybons6eaa0c0d2015-08-26 20:12:52106## Continuous Checking
andybons3322f762015-08-24 21:37:09107
andybons6eaa0c0d2015-08-26 20:12:52108To compile your code on every commit, add a line to
109/third_party/closure_compiler/compiled_resources.gyp
110like this:
andybons3322f762015-08-24 21:37:09111
112```
113{
114 'targets': [
115 {
116 'target_name': 'compile_all_resources',
117 'dependencies': [
118 # ... other projects ...
119++ '../my_project/compiled_resources.gyp:*',
120 ],
121 }
122 ]
123}
124```
125
andybons6eaa0c0d2015-08-26 20:12:52126and the
127[Closure compiler bot](http://build.chromium.org/p/chromium.fyi/builders/Closure%20Compilation%20Linux)
128will [re-]compile your code whenever relevant .js files change.
andybons3322f762015-08-24 21:37:09129
andybons6eaa0c0d2015-08-26 20:12:52130## Using Compiled JavaScript
andybons3322f762015-08-24 21:37:09131
andybons6eaa0c0d2015-08-26 20:12:52132Compiled JavaScript is output in
133`src/out/<Debug|Release>/gen/closure/my_project/my_file.js` along with a source
134map for use in debugging. In order to use the compiled JavaScript, we can create
135a
andybons3322f762015-08-24 21:37:09136
andybons6eaa0c0d2015-08-26 20:12:52137 my_project/my_project_resources.gpy
andybons3322f762015-08-24 21:37:09138
139with the contents:
140
141```
142# Copyright 2015 The Chromium Authors. All rights reserved.
143# Use of this source code is governed by a BSD-style license that can be
144# found in the LICENSE file.
145
146{
147 'targets': [
148 {
149 # GN version: //my_project/resources
150 'target_name': 'my_project_resources',
151 'type': 'none',
152 'variables': {
153 'grit_out_dir': '<(SHARED_INTERMEDIATE_DIR)/my_project',
154 'my_file_gen_js': '<(SHARED_INTERMEDIATE_DIR)/closure/my_project/my_file.js',
155 },
156 'actions': [
157 {
158 # GN version: //my_project/resources:my_project_resources
159 'action_name': 'generate_my_project_resources',
160 'variables': {
161 'grit_grd_file': 'resources/my_project_resources.grd',
162 'grit_additional_defines': [
163 '-E', 'my_file_gen_js=<(my_file_gen_js)',
164 ],
165 },
166 'includes': [ '../build/grit_action.gypi' ],
167 },
168 ],
169 'includes': [ '../build/grit_target.gypi' ],
170 },
171 ],
172}
173```
174
andybons6eaa0c0d2015-08-26 20:12:52175The variables can also be defined in an existing .gyp file if appropriate. The
176variables can then be used in to create a
andybons3322f762015-08-24 21:37:09177
andybons6eaa0c0d2015-08-26 20:12:52178 my_project/my_project_resources.grd
andybons3322f762015-08-24 21:37:09179
180with the contents:
181
182```
183<?xml version="1.0" encoding="utf-8"?>
184<grit-part>
185 <include name="IDR_MY_FILE_GEN_JS" file="${my_file_gen_js}" use_base_dir="false" type="BINDATA" />
186</grit-part>
187```
188
189In your C++, the resource can be retrieved like this:
190```
191base::string16 my_script =
192 base::UTF8ToUTF16(
193 ResourceBundle::GetSharedInstance()
194 .GetRawDataResource(IDR_MY_FILE_GEN_JS)
195 .as_string());
196```
197
andybons6eaa0c0d2015-08-26 20:12:52198## Debugging Compiled JavaScript
andybons3322f762015-08-24 21:37:09199
andybons6eaa0c0d2015-08-26 20:12:52200Along with the compiled JavaScript, a source map is created:
201`src/out/<Debug|Release>/gen/closure/my_project/my_file.js.map`
andybons3322f762015-08-24 21:37:09202
andybons6eaa0c0d2015-08-26 20:12:52203Chrome DevTools has built in support for working with source maps:
204https://developer.chrome.com/devtools/docs/javascript-debugging#source-maps
andybons3322f762015-08-24 21:37:09205
andybons6eaa0c0d2015-08-26 20:12:52206In 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
208looks like this:
209
andybons3322f762015-08-24 21:37:09210```
211{
212"version":3,
213"file":"/tmp/gen/test_script.js",
214"lineCount":1,
215"mappings":"A,aAAA,IAAIA,OAASA,QAAQ,EAAG,CACtBC,KAAA,CAAM,OAAN,CADsB;",
216"sources":["/tmp/tmp70_QUi"],
217"names":["fooBar","alert"]
218}
219```
220
221sources should be changed to:
andybons6eaa0c0d2015-08-26 20:12:52222
andybons3322f762015-08-24 21:37:09223```
224...
225"sources":["/tmp/test_script.js"],
226...
227```
228
andybons6eaa0c0d2015-08-26 20:12:52229In your browser, the source map can be loaded through the Chrome DevTools
230context menu that appears when you right click in the compiled JavaScript source
231body. A dialog will pop up prompting you for the path to the source map file.
232Once the source map is loaded, the uncompiled version of the JavaScript will
233appear in the Sources panel on the left. You can set break points in the
234uncompiled version to help debug; behind the scenes Chrome will still be running
235the compiled version of the JavaScript.
andybons3322f762015-08-24 21:37:09236
andybons6eaa0c0d2015-08-26 20:12:52237## Additional Arguments
andybons3322f762015-08-24 21:37:09238
andybons6eaa0c0d2015-08-26 20:12:52239`compile_js.gypi` accepts an optional `script_args` variable, which passes
240additional arguments to `compile.py`, as well as an optional `closure_args`
241variable, which passes additional arguments to the closure compiler. You may
242also override the `disabled_closure_args` for more strict compilation.
andybons3322f762015-08-24 21:37:09243
andybons6eaa0c0d2015-08-26 20:12:52244For example, if you would like to specify multiple sources, strict compilation,
245and an output wrapper, you would create a
andybons3322f762015-08-24 21:37:09246
247```
248my_project/compiled_resources.gyp
249```
250
251with contents similar to this:
252```
253# Copyright 2015 The Chromium Authors. All rights reserved.
254# Use of this source code is governed by a BSD-style license that can be
255# found in the LICENSE file.
256{
257 'targets' :[
258 {
259 'target_name': 'my_file',
260 'variables': {
261 'source_files': [
262 'my_file.js',
263 'my_file2.js',
264 ],
265 'script_args': ['--no-single-file'], # required to process multiple files at once
266 'closure_args': [
267 'output_wrapper=\'(function(){%output%})();\'',
268 'jscomp_error=reportUnknownTypes', # the following three provide more strict compilation
269 'jscomp_error=duplicate',
270 'jscomp_error=misplacedTypeAnnotation',
271 ],
272 'disabled_closure_args': [], # remove the disabled closure args for more strict compilation
273 },
274 'includes': ['../third_party/closure_compiler/compile_js.gypi'],
275 },
276 ],
277}
andybons6eaa0c0d2015-08-26 20:12:52278```