OLD | NEW |
1 # Using the Chrome Devtools JavaScript preprocessing feature | 1 # Using the Chrome Devtools JavaScript preprocessing feature |
2 | 2 |
3 The Chrome Devtools JavaScript preprocessor intercepts JavaScript just before it
enters V8, the Chrome JS system, allowing the JS to be transcoded before compil
ation. In combination with page injected JavaScript, the preprocessor allows a
complete synthetic runtime to be constructed in JavaScript. Combined with other
functions in the `chrome.devtools` extension API, the preprocessor allows new mo
re sophisticated JavaScript-related developer tools to be created. | 3 The Chrome Devtools JavaScript preprocessor intercepts JavaScript just before it |
| 4 enters V8, the Chrome JS system, allowing the JS to be transcoded before |
| 5 compilation. In combination with page injected JavaScript, the preprocessor |
| 6 allows a complete synthetic runtime to be constructed in JavaScript. Combined |
| 7 with other functions in the `chrome.devtools` extension API, the preprocessor |
| 8 allows new more sophisticated JavaScript-related developer tools to be created. |
4 | 9 |
5 ## API | 10 ## API |
6 | 11 |
7 To use the script preprocessor, write a [chrome devtools extension](http://devel
oper.chrome.com/extensions/devtools.inspectedWindow.html#method-reload) that rel
oads the Web page with the preprocessor installed: | 12 To use the script preprocessor, write a |
8 ``` | 13 [chrome devtools extension](http://developer.chrome.com/extensions/devtools.insp
ectedWindow.html#method-reload) |
| 14 that reloads the Web page with the preprocessor installed: |
| 15 |
| 16 ```javascript |
9 chrome.devtools.inspectedWindow.reload({ | 17 chrome.devtools.inspectedWindow.reload({ |
10 ignoreCache: true, | 18 ignoreCache: true, |
11 injectedScript: runThisFirst, | 19 injectedScript: runThisFirst, |
12 preprocessorScript: preprocessor | 20 preprocessorScript: preprocessor |
13 }); | 21 }); |
14 ``` | 22 ``` |
15 where `preprocessorScript` is source code (string) for a JavaScript function tak
ing three string arguments, the source to preprocess, the URL of the source, and
a function name if the source is an DOM event handler. The preprocessorerScript
function should return a string to be compiled by Chrome in place of the input
source. In the case that the source is a DOM event handler, the returned source
must compile to a single JS function. | |
16 | 23 |
17 The [Chrome Preprocessor Example](http://developer.chrome.com/extensions/samples
.html) illustrates the API call in a simple chrome devtools extension. Download
and unpack the .zip file, use `chrome://extensions` in Developer Mode and load t
he unpacked extension. Then open or reopen devtools. The Preprocessor panel has
a **reload** button that triggers a simple preprocessor. | 24 where `preprocessorScript` is source code (string) for a JavaScript function |
| 25 taking three string arguments, the source to preprocess, the URL of the source, |
| 26 and a function name if the source is an DOM event handler. The |
| 27 `preprocessorerScript` function should return a string to be compiled by Chrome |
| 28 in place of the input source. In the case that the source is a DOM event |
| 29 handler, the returned source must compile to a single JS function. |
18 | 30 |
19 The preprocessor runs in an isolated world similar to the environment of Chrome
content scripts. A `window` object is available but it shares no properties with
the Web page `window` object. DOM calls in the preprocessor environment will o
perate on the Web page, but developers should be cautious about operating on the
DOM in the preprocessor. We do not test such operations though we expect the re
sult to resemble calls from the outer function of `<script>` tags. | 31 The |
| 32 [Chrome Preprocessor Example](http://developer.chrome.com/extensions/samples.htm
l) |
| 33 illustrates the API call in a simple chrome devtools extension. Download and |
| 34 unpack the .zip file, use `chrome://extensions` in Developer Mode and load the |
| 35 unpacked extension. Then open or reopen devtools. The Preprocessor panel has a |
| 36 **reload** button that triggers a simple preprocessor. |
20 | 37 |
21 In some applications the developer may coordinate runtime initialization using t
he `injectedScript` property in the object passed to the `reload()` call. This i
s also JavaScript source code; it is compiled into the page ahead of any Web pag
e scripts and thus before any JavaScript is preprocessed. | 38 The preprocessor runs in an isolated world similar to the environment of Chrome |
| 39 content scripts. A `window` object is available but it shares no properties with |
| 40 the Web page `window` object. DOM calls in the preprocessor environment will |
| 41 operate on the Web page, but developers should be cautious about operating on |
| 42 the DOM in the preprocessor. We do not test such operations though we expect the |
| 43 result to resemble calls from the outer function of `<script>` tags. |
22 | 44 |
23 The preprocessor is compiled once just before the first JavaScript appears. It r
emains active until the page is reloaded or otherwise navigated. Navigating the
Web page back and then forward will result in no preprocessing. Closing devtool
s will leave the preprocessor in place. | 45 In some applications the developer may coordinate runtime initialization using |
| 46 the `injectedScript` property in the object passed to the `reload()` call. This |
| 47 is also JavaScript source code; it is compiled into the page ahead of any Web |
| 48 page scripts and thus before any JavaScript is preprocessed. |
| 49 |
| 50 The preprocessor is compiled once just before the first JavaScript appears. It |
| 51 remains active until the page is reloaded or otherwise navigated. Navigating the |
| 52 Web page back and then forward will result in no preprocessing. Closing devtools |
| 53 will leave the preprocessor in place. |
24 | 54 |
25 ## Use Cases | 55 ## Use Cases |
26 | 56 |
27 The script preprocessor supports transcoding input source to JavaScript. Use cas
es include: | 57 The script preprocessor supports transcoding input source to JavaScript. Use cas
es include: |
28 * Adding write barriers for Querypoint debugging, | 58 |
29 * Supporting feature-specific debugging of next generation EcmaScript using eg
Traceur, | 59 * Adding write barriers for Querypoint debugging, |
30 * Integration of development tools like coverage analysis. | 60 * Supporting feature-specific debugging of next generation EcmaScript using eg
Traceur, |
31 * Analysis of call sequences for performance tuning. | 61 * Integration of development tools like coverage analysis. |
32 Several JavaScript compilers support transcoding, including [Traceur](https://gi
thub.com/google/traceur-compiler#readme) and [Esprima](http://esprima.org/). | 62 * Analysis of call sequences for performance tuning. |
| 63 |
| 64 Several JavaScript compilers support transcoding, including |
| 65 [Traceur](https://github.com/google/traceur-compiler#readme) and |
| 66 [Esprima](http://esprima.org/). |
33 | 67 |
34 ## Implementation | 68 ## Implementation |
35 | 69 |
36 The implementation relies on the Devtools front-end hosting an extension supplyi
ng the preprocessor script; the front end communicates with the browser backend
over eg web sockets. | 70 The implementation relies on the Devtools front-end hosting an extension |
| 71 supplying the preprocessor script; the front end communicates with the browser |
| 72 backend over eg web sockets. |
37 | 73 |
38 The devtools extension function call issues a postMessage() event from the devto
ols extension iframe to the devtools main frame. The event is handled in Extensi
onServer.js which forwards it over the [devtools remote debug protocol](https://
developers.google.com/chrome-developer-tools/docs/protocol/1.0/page#command-relo
ad). (See [Bug 229971](https://code.google.com/p/chromium/issues/detail?id=2299
71) for this part of the implementation and its status). | 74 The devtools extension function call issues a postMessage() event from the |
| 75 devtools extension iframe to the devtools main frame. The event is handled in |
| 76 `ExtensionServer.js` which forwards it over the |
| 77 [devtools remote debug protocol](https://developers.google.com/chrome-developer-
tools/docs/protocol/1.0/page#command-reload). |
| 78 (See [Bug 229971](https://crbug.com/229971) for this part of the implementation |
| 79 and its status). |
39 | 80 |
40 When the preprocessor script arrives in the back end, `InspectorPageAgent::reloa
d` stores the preprocessor script in `m_pendingScriptPreprocessor`. After the br
owser begins the reload operation, it calls `PageDebuggerAgent::didClearWindowOb
jectInWorld` which moves the processor source into the `scriptDebugServer()`. | 81 When the preprocessor script arrives in the back end, |
| 82 `InspectorPageAgent::reload` stores the preprocessor script in |
| 83 `m_pendingScriptPreprocessor`. After the browser begins the reload operation, it |
| 84 calls `PageDebuggerAgent::didClearWindowObjectInWorld` which moves the processor |
| 85 source into the `scriptDebugServer()`. |
41 | 86 |
42 Next the browser prepares the page environment and calls `PageDebuggerAgent::did
ClearWindowObjectInWorld`. This function clears the preprocessor object pointer
and if it is not recreated during the page load, no scripts will be preprocessed
. At this point we only store the preprocessor source, delaying the compilation
of the preprocessor until just before its first use. This helps ensure that the
JS environment we use is fully initialized. | 87 Next the browser prepares the page environment and calls |
| 88 `PageDebuggerAgent::didClearWindowObjectInWorld`. This function clears the |
| 89 preprocessor object pointer and if it is not recreated during the page load, no |
| 90 scripts will be preprocessed. At this point we only store the preprocessor |
| 91 source, delaying the compilation of the preprocessor until just before its first |
| 92 use. This helps ensure that the JS environment we use is fully initialized. |
43 | 93 |
44 Source to be preprocessed comes from three different places: | 94 Source to be preprocessed comes from three different places: |
45 1. Web page `<script>` tags, | |
46 1. DOM event-listener attributes, eg `onload`, | |
47 1. JS `eval()` or `new Function()` calls. | |
48 | 95 |
49 When the browser encounters either a `<script>` tag (`ScriptController::executeS
criptInMainWorld`) or an element attribute script (`V8LazyEventListener::prepar
eListenerObject`) we call a corresponding function in InspectorInstrumentation.
This function has a fast inlined return path in the case that the debugger is no
t attached. | 96 1. Web page `<script>` tags, |
| 97 1. DOM event-listener attributes, eg `onload`, |
| 98 1. JS `eval()` or `new Function()` calls. |
50 | 99 |
51 If the debugger is attached, InspectorInstrumentation will call the matching fun
ction in PageDebuggerAgent (see core/inspector/InspectorInstrumentation.idl). It
checks to see if the preprocessor is installed. If not, it returns. | 100 When the browser encounters either a `<script>` tag |
| 101 (`ScriptController::executeScriptInMainWorld`) or an element attribute script |
| 102 (`V8LazyEventListener::prepareListenerObject`) we call a corresponding function |
| 103 in InspectorInstrumentation. This function has a fast inlined return path in the |
| 104 case that the debugger is not attached. |
| 105 |
| 106 If the debugger is attached, InspectorInstrumentation will call the matching |
| 107 function in PageDebuggerAgent (see core/inspector/InspectorInstrumentation.idl). |
| 108 It checks to see if the preprocessor is installed. If not, it returns. |
52 | 109 |
53 The preprocessor source is stored in PageScriptDebugServer. | 110 The preprocessor source is stored in PageScriptDebugServer. |
54 If the preprocessor is installed, we check to see if it is compiled. If not, we
create a new `ScriptPreprocessor` object. The constructor uses `ScriptControll
er::executeScriptInIsolatedWorld` to compile the preprocessor in a new isolated
world associated with the Web page's main world. If the compilation and outer s
cript execution succeed and if the result is a JavaScript function, we store the
resulting function as a `ScopedPersistent<v8::Function>` member of the preproce
ssor. | 111 If the preprocessor is installed, we check to see if it is compiled. If not, we |
| 112 create a new `ScriptPreprocessor` object. The constructor uses |
| 113 `ScriptController::executeScriptInIsolatedWorld` to compile the preprocessor in |
| 114 a new isolated world associated with the Web page's main world. If the |
| 115 compilation and outer script execution succeed and if the result is a JavaScript |
| 116 function, we store the resulting function as a `ScopedPersistent<v8::Function>` |
| 117 member of the preprocessor. |
55 | 118 |
56 If the `PageScriptDebugServer::preprocess()` has a value for the preprocessor fu
nction, it applies the function to the web page source using `V8ScriptRunner::ca
llAsFunction()`. This calls the compiled JS function in the ScriptPreprocessor'
s isolated world and retrieves the resulting string. | 119 If the `PageScriptDebugServer::preprocess()` has a value for the preprocessor |
| 120 function, it applies the function to the web page source using |
| 121 `V8ScriptRunner::callAsFunction()`. This calls the compiled JS function in the |
| 122 ScriptPreprocessor's isolated world and retrieves the resulting string. |
57 | 123 |
58 When the preprocessed JavaScript source runs it may call `eval()` or `new Functi
on()`. These calls cause the V8 runtime to compile source. Immediately before c
ompiling, V8 issues a beforeCompile event which triggers `ScriptDebugServer::han
dleV8DebugEvent()`. This code is only called if the debugger is active. In the h
andler we call `ScriptDebugServer::preprocessEval()` to examine the ScriptCompil
ationTypeInfo, a marker set by V8, to see if we are compiling dynamic code. Only
dynamic code is preprocessed in this function and only if we are not executing
the preprocessor itself. | 124 When the preprocessed JavaScript source runs it may call `eval()` or |
| 125 `new Function()`. These calls cause the V8 runtime to compile source. |
| 126 Immediately before compiling, V8 issues a beforeCompile event which triggers |
| 127 `ScriptDebugServer::handleV8DebugEvent()`. This code is only called if the |
| 128 debugger is active. In the handler we call `ScriptDebugServer::preprocessEval()` |
| 129 to examine the ScriptCompilationTypeInfo, a marker set by V8, to see if we are |
| 130 compiling dynamic code. Only dynamic code is preprocessed in this function and |
| 131 only if we are not executing the preprocessor itself. |
59 | 132 |
60 During the browser operation, API generation code, debugger console initializati
on code, injected page script code, debugger information extraction code, and re
gular web page code enter this function. There is currently no way to distingui
sh internal or system code from the web page code. However the internal code is
all static. By limiting our preprocessing to dynamic code in the beforeCompile h
andler, we know we are only operating on Web page code. The static Web page code
is preprocessed as described above. | 133 During the browser operation, API generation code, debugger console |
| 134 initialization code, injected page script code, debugger information extraction |
| 135 code, and regular web page code enter this function. There is currently no way |
| 136 to distinguish internal or system code from the web page code. However the |
| 137 internal code is all static. By limiting our preprocessing to dynamic code in |
| 138 the beforeCompile handler, we know we are only operating on Web page code. The |
| 139 static Web page code is preprocessed as described above. |
61 | 140 |
62 ## Limitations | 141 ## Limitations |
63 | 142 |
64 We currently do not support preprocessing of WebWorker source code. | 143 We currently do not support preprocessing of WebWorker source code. |
OLD | NEW |