docs/closure_compilation.md

   1 # I just need to fix the compile!
   2
   3 To locally run closure compiler like the bots, do this:
   4
   5 ```
   6 cd $CHROMIUM_SRC
   7 # sudo apt-get install openjdk-7-jre # may be required
   8 GYP_GENERATORS=ninja tools/gyp/gyp --depth . third_party/closure_compiler/compiled_resources.gyp
   9 ninja -C out/Default
  10 ```
  11
  12 # Background
  13
  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 typed and therefore doesn't offer this safety.  This makes writing JavaScript more error prone as it's _one more thing_ to mess up.
  15
  16 Because having this safety is handy, Chrome now has a way to optionally typecheck your JavaScript and produce compiled output with [Closure Compiler](https://developers.google.com/closure/compiler/).
  17
  18 See also: [the design doc](https://docs.google.com/a/chromium.org/document/d/1Ee9ggmp6U-lM-w9WmxN5cSLkK9B5YAq14939Woo-JY0/edit).
  19
  20 # Assumptions
  21
  22 A working Chrome checkout.  See here: http://www.chromium.org/developers/how-tos/get-the-code
  23
  24 # Typechecking Your Javascript
  25
  26 So you'd like to compile your JavaScript!
  27
  28 Maybe you're working on a page that looks like this:
  29
  30 ```
  31 <script src="other_file.js"></script>
  32 <script src="my_product/my_file.js"></script>
  33 ```
  34
  35 Where `other_file.js` contains:
  36
  37 ```
  38 var wit = 100;
  39
  40 // ... later on, sneakily ...
  41
  42 wit += ' IQ';  // '100 IQ'
  43 ```
  44
  45 and `src/my_product/my_file.js` contains:
  46
  47 ```
  48 /** @type {number} */ var mensa = wit + 50;
  49 alert(mensa);  // '100 IQ50' instead of 150
  50 ```
  51
  52 In order to check that our code acts as we'd expect, we can create a
  53
  54 ```
  55 my_project/compiled_resources.gyp
  56 ```
  57
  58 with the contents:
  59
  60 ```
  61 # Copyright 2015 The Chromium Authors. All rights reserved.
  62 # Use of this source code is governed by a BSD-style license that can be
  63 # found in the LICENSE file.
  64 {
  65   'targets': [
  66     {
  67       'target_name': 'my_file',  # file name without ".js"
  68
  69       'variables': {  # Only use if necessary (no need to specify empty lists).
  70         'depends': [
  71           'other_file.js',  # or 'other_project/compiled_resources.gyp:target',
  72         ],
  73         'externs': [
  74           '<(CLOSURE_DIR)/externs/any_needed_externs.js'  # e.g. chrome.send(), chrome.app.window, etc.
  75         ],
  76       },
  77
  78       'includes': ['../third_party/closure_compiler/compile_js.gypi'],
  79     },
  80   ],
  81 }
  82 ```
  83
  84 You should get results like:
  85
  86 ```
  87 (ERROR) Error in: my_project/my_file.js
  88 ## /my/home/chromium/src/my_project/my_file.js:1: ERROR - initializing variable
  89 ## found   : string
  90 ## required: number
  91 ## /** @type {number} */ var mensa = wit + 50;
  92 ##                                   ^
  93 ```
  94
  95 Yay!  We can easily find our unexpected type errors and write less error-prone code!
  96
  97 # Continuous Checking
  98
  99 To compile your code on every commit, add a line to [third\_party/closure\_compiler/compiled\_resources.gyp](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/closure_compiler/compiled_resources.gyp&sq=package:chromium&type=cs) like this:
 100
 101 ```
 102 {
 103   'targets': [
 104     {
 105       'target_name': 'compile_all_resources',
 106       'dependencies': [
 107          # ... other projects ...
 108 ++       '../my_project/compiled_resources.gyp:*',
 109       ],
 110     }
 111   ]
 112 }
 113 ```
 114
 115 and the [Closure compiler bot](http://build.chromium.org/p/chromium.fyi/builders/Closure%20Compilation%20Linux) will [re-]compile your code whenever relevant .js files change.
 116
 117 # Using Compiled JavaScript
 118
 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 compiled JavaScript, we can create a
 120
 121 ```
 122 my_project/my_project_resources.gpy
 123 ```
 124
 125 with the contents:
 126
 127 ```
 128 # Copyright 2015 The Chromium Authors. All rights reserved.
 129 # Use of this source code is governed by a BSD-style license that can be
 130 # found in the LICENSE file.
 131
 132 {
 133   'targets': [
 134     {
 135       # GN version: //my_project/resources
 136       'target_name': 'my_project_resources',
 137       'type': 'none',
 138       'variables': {
 139         'grit_out_dir': '<(SHARED_INTERMEDIATE_DIR)/my_project',
 140         'my_file_gen_js': '<(SHARED_INTERMEDIATE_DIR)/closure/my_project/my_file.js',
 141       },
 142       'actions': [
 143         {
 144           # GN version: //my_project/resources:my_project_resources
 145           'action_name': 'generate_my_project_resources',
 146           'variables': {
 147             'grit_grd_file': 'resources/my_project_resources.grd',
 148             'grit_additional_defines': [
 149               '-E', 'my_file_gen_js=<(my_file_gen_js)',
 150             ],
 151           },
 152           'includes': [ '../build/grit_action.gypi' ],
 153         },
 154       ],
 155       'includes': [ '../build/grit_target.gypi' ],
 156     },
 157   ],
 158 }
 159 ```
 160
 161 The variables can also be defined in an existing .gyp file if appropriate. The variables can then be used in to create a
 162
 163 ```
 164 my_project/my_project_resources.grd
 165 ```
 166
 167 with the contents:
 168
 169 ```
 170 <?xml version="1.0" encoding="utf-8"?>
 171 <grit-part>
 172   <include name="IDR_MY_FILE_GEN_JS" file="${my_file_gen_js}" use_base_dir="false" type="BINDATA" />
 173 </grit-part>
 174 ```
 175
 176 In your C++, the resource can be retrieved like this:
 177 ```
 178 base::string16 my_script =
 179     base::UTF8ToUTF16(
 180         ResourceBundle::GetSharedInstance()
 181             .GetRawDataResource(IDR_MY_FILE_GEN_JS)
 182             .as_string());
 183 ```
 184
 185 # Debugging Compiled JavaScript
 186
 187 Along with the compiled JavaScript, a source map is created: src/out/<Debug|Release>/gen/closure/my\_project/my\_file.js.map
 188
 189 Chrome DevTools has built in support for working with source maps: [https://developer.chrome.com/devtools/docs/javascript-debugging#source-maps](https://developer.chrome.com/devtools/docs/javascript-debugging#source-maps)
 190
 191 In order to use the source map, you must first manually edit the path to the 'sources' in the .js.map file that was generated. For example, if the source map looks like this:
 192 ```
 193 {
 194 "version":3,
 195 "file":"/tmp/gen/test_script.js",
 196 "lineCount":1,
 197 "mappings":"A,aAAA,IAAIA,OAASA,QAAQ,EAAG,CACtBC,KAAA,CAAM,OAAN,CADsB;",
 198 "sources":["/tmp/tmp70_QUi"],
 199 "names":["fooBar","alert"]
 200 }
 201 ```
 202
 203 sources should be changed to:
 204 ```
 205 ...
 206 "sources":["/tmp/test_script.js"],
 207 ...
 208 ```
 209
 210 In your browser, the source map can be loaded through the Chrome DevTools context 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 the 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 version to help debug; behind the scenes Chrome will still be running the compiled version of the JavaScript.
 211
 212 # Additional Arguments
 213
 214 compile\_js.gypi accepts an optional script\_args variable, which passes additional arguments to compile.py, as well as an optional closure\_args variable, which passes additional arguments to the closure compiler. You may also override the disabled\_closure\_args for more strict compilation.
 215
 216 For example, if you would like to specify multiple sources, strict compilation, and an output wrapper, you would create a
 217
 218 ```
 219 my_project/compiled_resources.gyp
 220 ```
 221
 222 with contents similar to this:
 223 ```
 224 # Copyright 2015 The Chromium Authors. All rights reserved.
 225 # Use of this source code is governed by a BSD-style license that can be
 226 # found in the LICENSE file.
 227 {
 228   'targets' :[
 229     {
 230       'target_name': 'my_file',
 231       'variables': {
 232         'source_files': [
 233           'my_file.js',
 234           'my_file2.js',
 235         ],
 236         'script_args': ['--no-single-file'], # required to process multiple files at once
 237         'closure_args': [
 238           'output_wrapper=\'(function(){%output%})();\'',
 239           'jscomp_error=reportUnknownTypes',     # the following three provide more strict compilation
 240           'jscomp_error=duplicate',
 241           'jscomp_error=misplacedTypeAnnotation',
 242         ],
 243         'disabled_closure_args': [], # remove the disabled closure args for more strict compilation
 244       },
 245       'includes': ['../third_party/closure_compiler/compile_js.gypi'],
 246     },
 247   ],
 248 }
 249 ```