debugger protocol. whitespace and extra closing tag.
This commit is contained in:
Paul Irish
Родитель
a4a1354779
Коммит
7d81fd4049
|
|
@ -3,147 +3,164 @@
|
|||
|
||||
|
||||
<p>Under the hood, Chrome Developer Tools is a web application written in HTML,
|
||||
JavaScript and CSS. It has a special binding available at JavaScript runtime
|
||||
that allows interacting with chrome pages and instrumenting them. Interaction
|
||||
protocol consists of commands that are sent to the page and events that
|
||||
the page is generating. Although Chrome Developer Tools is the primary client of
|
||||
this protocol, including for <a href="remote-debugging.html">remote debugging</a>, there are ways for third parties to use it and start
|
||||
instrumenting browser pages explicitly. We will describe the ways it could be
|
||||
done below.</p>
|
||||
JavaScript and CSS. It has a special binding available at JavaScript runtime
|
||||
that allows interacting with chrome pages and instrumenting them. Interaction
|
||||
protocol consists of commands that are sent to the page and events that
|
||||
the page is generating. Although Chrome Developer Tools is the primary client of
|
||||
this protocol, including for <a href="remote-debugging.html">remote debugging</a>, there are ways for third parties to use it and start
|
||||
instrumenting browser pages explicitly. We will describe the ways it could be
|
||||
done below.
|
||||
</p>
|
||||
|
||||
|
||||
<div class="collapsible">
|
||||
<h2 id="protocol">Protocol</h2>
|
||||
<p>Interaction protocol consists of JSON commands that are sent to the page and
|
||||
events that the page is generating. We define this protocol in Blink
|
||||
("upstream") so that any Blink-based browser supported it.</p>
|
||||
<h2 id="protocol">Protocol</h2>
|
||||
<p>Interaction protocol consists of JSON commands that are sent to the page and
|
||||
events that the page is generating. We define this protocol in Blink
|
||||
("upstream") so that any Blink-based browser supported it.
|
||||
</p>
|
||||
|
||||
<h3>Stable</h3>
|
||||
<p>
|
||||
<h3>Stable</h3>
|
||||
<p>
|
||||
<a href="protocol/1.1/index.html">Debugger protocol version 1.1</a> is the most recent stable release of the protocol.
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
As of Google Chrome 31, we commit to supporting v1.1. All subsequent 1.* versions of the protocol are going to be backwards compatible with 1.1. Our protocol backwards compatibility commitment is:
|
||||
<ul>
|
||||
<li>No commands or events are removed from the protocol.</li>
|
||||
<li>No required parameters are added to the commands.</li>
|
||||
<li>No required parameters are removed from command responses or events.</li>
|
||||
</ul>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<p> <b>Previous versions</b>:
|
||||
<a href="protocol/1.0/index.html">Protocol v1.0</a> was shipped and supported as of Chrome 18.
|
||||
<a href="protocol/0.1/index.html">Protocol v0.1</a> was shipped and supported as of Chrome 16.
|
||||
</p>
|
||||
|
||||
|
||||
<h3>Alpha</h3>
|
||||
|
||||
<p>
|
||||
The <a href="https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/devtools/protocol.json&q=protocol.json&sq=package:chromium&type=cs">tip-of-tree protocol</a> is volatile and may break at any time. However it captures the full capabilities of the Protocol, whereas the stable release is a subset. There is no backwards compatibility support guaranteed for the capabilities it introduces. You can
|
||||
use it with <a href="http://tools.google.com/dlpage/chromesxs">Google Canary</a>
|
||||
builds at your own risk.
|
||||
|
||||
A <i>portion</i> of the tip-of-tree protocol is documented in the <a href="protocol/tot/index.html">tot section here</a>; it may be slightly more complete than what's in <a href="protocol/1.1/index.html">1.1</a>.
|
||||
</p>
|
||||
|
||||
<p>You can inspect how the Chrome DevTools uses the protocol. Especially handy when looking up newer features. First, <a href="https://developers.google.com/chrome-developer-tools/docs/contributing#step_3_inspector_inception">inspect the inspector</a> and reload the inspector so your attached one can view its WebSocket connection (<code>Network > Filter > WebSockets</code>). Then view the frames of WebSocket activity as you use the host DevTools. You may need to re-click the WebSocket item to have the Frame activity update.</p>
|
||||
|
||||
<figure class="screenshot"> <a href="debugger-protocol/debugger-protocol-sniffing-full.jpg"><img src="debugger-protocol/debugger-protocol-sniffing.jpg" alt="Sniffing the debugger protocol" /></a></figure>
|
||||
</div>
|
||||
|
||||
<div class="collapsible">
|
||||
<h2 id="remote">Debugging over the wire</h2>
|
||||
<p>Today Developer Tools front-end can attach to a remotely running Chrome
|
||||
instance for debugging.
|
||||
|
||||
For this scenario to work, you should start your
|
||||
<i>host</i> Chrome instance with the remote-debugging-port
|
||||
command line switch:
|
||||
</p>
|
||||
|
||||
<pre class="summary">
|
||||
chrome.exe --remote-debugging-port=9222
|
||||
</pre>
|
||||
|
||||
<p>Then you can start a <i>client</i> Chrome instance, using a separate user profile:</p>
|
||||
|
||||
<pre class="summary">
|
||||
chrome.exe --user-data-dir=<some directory>
|
||||
</pre>
|
||||
|
||||
<p>And now you can navigate to the given port from your <i>client</i> and attach to
|
||||
any of the discovered tabs for debugging: <a href="http://localhost:9222">http://localhost:9222</a>
|
||||
</p>
|
||||
|
||||
<p>You will find Developer Tools interface identical to the embedded one and
|
||||
here is why:
|
||||
</p>
|
||||
<ul>
|
||||
<li>No commands or events are removed from the protocol.</li>
|
||||
<li>No required parameters are added to the commands.</li>
|
||||
<li>No required parameters are removed from command responses or events.</li>
|
||||
</ul>
|
||||
<li>When you navigate your <i>client</i> browser to the remote's Chrome port,
|
||||
Developer Tools front-end is being served from the <i>host</i> Chrome
|
||||
as a Web Application from the Web Server.
|
||||
</li>
|
||||
<li>It fetches HTML, JavaScript and CSS files over HTTP
|
||||
</li>
|
||||
<li>Once loaded, Developer Tools establishes a Web Socket connection to its
|
||||
host and starts interchanging JSON messages with it.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</p>
|
||||
<p>In this scenario, you can substitute Developer Tools front-end with your
|
||||
own implementation. Instead of navigating to the HTML page at
|
||||
http://localhost:9222, your application can discover available
|
||||
pages by requesting:
|
||||
</p>
|
||||
|
||||
<a href="http://localhost:9222/json">http://localhost:9222/json</a>
|
||||
|
||||
|
||||
<p> <b>Previous versions</b>:
|
||||
<a href="protocol/1.0/index.html">Protocol v1.0</a> was shipped and supported as of Chrome 18.
|
||||
<a href="protocol/0.1/index.html">Protocol v0.1</a> was shipped and supported as of Chrome 16.
|
||||
</p>
|
||||
<p>and getting a JSON object with information about inspectable pages along
|
||||
with the WebSocket addresses that you could use in order to start
|
||||
instrumenting them.
|
||||
</p>
|
||||
|
||||
|
||||
<h3>Alpha</h3>
|
||||
|
||||
<p>
|
||||
The <a href="https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/devtools/protocol.json&q=protocol.json&sq=package:chromium&type=cs">tip-of-tree protocol</a> is volatile and may break at any time. However it captures the full capabilities of the Protocol, whereas the stable release is a subset. There is no backwards compatibility support guaranteed for the capabilities it introduces. You can
|
||||
use it with <a href="http://tools.google.com/dlpage/chromesxs">Google Canary</a>
|
||||
builds at your own risk.
|
||||
|
||||
A <i>portion</i> of the tip-of-tree protocol is documented in the <a href="protocol/tot/index.html">tot section here</a>; it may be slightly more complete than what's in <a href="protocol/1.1/index.html">1.1</a>.
|
||||
</p>
|
||||
|
||||
<p>You can inspect how the Chrome DevTools uses the protocol. Especially handy when looking up newer features. First, <a href="https://developers.google.com/chrome-developer-tools/docs/contributing#step_3_inspector_inception">inspect the inspector</a> and reload the inspector so your attached one can view its WebSocket connection (<code>Network > Filter > WebSockets</code>). Then view the frames of WebSocket activity as you use the host DevTools. You may need to re-click the WebSocket item to have the Frame activity update.</p>
|
||||
|
||||
<figure class="screenshot"> <a href="debugger-protocol/debugger-protocol-sniffing-full.jpg"><img src="debugger-protocol/debugger-protocol-sniffing.jpg" alt="Sniffing the debugger protocol" /></a></figure>
|
||||
|
||||
<h2 id="remote">Debugging over the wire</h2>
|
||||
<p>Today Developer Tools front-end can attach to a remotely running Chrome
|
||||
instance for debugging.
|
||||
|
||||
For this scenario to work, you should start your
|
||||
<i>host</i> Chrome instance with the remote-debugging-port
|
||||
command line switch:</p>
|
||||
|
||||
<pre class="summary">
|
||||
chrome.exe --remote-debugging-port=9222
|
||||
</pre>
|
||||
|
||||
<p>Then you can start a <i>client</i> Chrome instance, using a separate user profile:</p>
|
||||
|
||||
<pre class="summary">
|
||||
chrome.exe --user-data-dir=<some directory>
|
||||
</pre>
|
||||
|
||||
<p>And now you can navigate to the given port from your <i>client</i> and attach to
|
||||
any of the discovered tabs for debugging: <a href="http://localhost:9222">http://localhost:9222</a></p>
|
||||
|
||||
<p>You will find Developer Tools interface identical to the embedded one and
|
||||
here is why:</p>
|
||||
<ul>
|
||||
<li>When you navigate your <i>client</i> browser to the remote's Chrome port,
|
||||
Developer Tools front-end is being served from the <i>host</i> Chrome
|
||||
as a Web Application from the Web Server.</li>
|
||||
<li>It fetches HTML, JavaScript and CSS files over HTTP</li>
|
||||
<li>Once loaded, Developer Tools establishes a Web Socket connection to its
|
||||
host and starts interchanging JSON messages with it.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>In this scenario, you can substitute Developer Tools front-end with your
|
||||
own implementation. Instead of navigating to the HTML page at
|
||||
http://localhost:9222, your application can discover available
|
||||
pages by requesting:</p>
|
||||
|
||||
<a href="http://localhost:9222/json">http://localhost:9222/json</a>
|
||||
|
||||
|
||||
<p>and getting a JSON object with information about inspectable pages along
|
||||
with the WebSocket addresses that you could use in order to start
|
||||
instrumenting them.</p>
|
||||
|
||||
<p>Remote debugging is especially useful when debugging remote
|
||||
instances of the browser or attaching to the embedded devices. Blink port
|
||||
owners are responsible for exposing debugging connections to the external
|
||||
users.</p>
|
||||
<p>Remote debugging is especially useful when debugging remote
|
||||
instances of the browser or attaching to the embedded devices. Blink port
|
||||
owners are responsible for exposing debugging connections to the external
|
||||
users.
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<div class="collapsible">
|
||||
<h2 id="clients">Debugging Protocol Clients</h2>
|
||||
<p>Many applications and libraries already use the protocol. Some to collect
|
||||
performance data, others to breakpoint debug from another editor. There are
|
||||
libraries to access the raw protocol from Node.js and Python.</p>
|
||||
|
||||
<p>Many of these clients are showcased here: <a href="https://developer.chrome.com/devtools/docs/debugging-clients">Showcased Debugging Protocol Clients</a>.
|
||||
<h2 id="clients">Debugging Protocol Clients</h2>
|
||||
<p>Many applications and libraries already use the protocol. Some to collect
|
||||
performance data, others to breakpoint debug from another editor. There are
|
||||
libraries to access the raw protocol from Node.js and Python.
|
||||
</p>
|
||||
|
||||
<p>Many of these clients are showcased here: <a href="https://developer.chrome.com/devtools/docs/debugging-clients">Showcased Debugging Protocol Clients</a>.
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<div class="collapsible">
|
||||
<h2 id="extension">Using debugger extension API</h2>
|
||||
<p>To allow third parties to interact with the protocol, we introduced
|
||||
<a href="https://developer.chrome.com/extensions/debugger.html">
|
||||
chrome.debugger</a> extension API that exposes this JSON message
|
||||
transport interface. As a result, you can not only attach to the remotely
|
||||
running Chrome instance, but also instrument it from its own extension.</p>
|
||||
<h2 id="extension">Using debugger extension API</h2>
|
||||
<p>
|
||||
To allow third parties to interact with the protocol, we introduced
|
||||
<a href="https://developer.chrome.com/extensions/debugger.html">chrome.debugger</a>
|
||||
extension API that exposes this JSON message
|
||||
transport interface. As a result, you can not only attach to the remotely
|
||||
running Chrome instance, but also instrument it from its own extension.
|
||||
</p>
|
||||
|
||||
<p>Chrome Debugger Extension API provides a higher level API where command
|
||||
domain, name and body are provided explicitly in the <code>sendCommand</code>
|
||||
call. This API hides request ids and handles binding of the request with its
|
||||
response, hence allowing <code>sendCommand</code> to report result in the
|
||||
callback function call. One can also use this API in combination with the other
|
||||
Extension APIs.
|
||||
</p>
|
||||
<p>Chrome Debugger Extension API provides a higher level API where command
|
||||
domain, name and body are provided explicitly in the <code>sendCommand</code>
|
||||
call. This API hides request ids and handles binding of the request with its
|
||||
response, hence allowing <code>sendCommand</code> to report result in the
|
||||
callback function call. One can also use this API in combination with the other
|
||||
Extension APIs.
|
||||
</p>
|
||||
|
||||
<p>If you are developing a Web-based IDE, you should implement an extension that
|
||||
exposes debugging capabilities to your page and your IDE will be able to open
|
||||
pages with the target application, set breakpoints there, evaluate expressions
|
||||
in console, live edit JavaScript and CSS, display live DOM, network interaction
|
||||
and any other aspect that Developer Tools is instrumenting today.</p>
|
||||
<p>If you are developing a Web-based IDE, you should implement an extension that
|
||||
exposes debugging capabilities to your page and your IDE will be able to open
|
||||
pages with the target application, set breakpoints there, evaluate expressions
|
||||
in console, live edit JavaScript and CSS, display live DOM, network interaction
|
||||
and any other aspect that Developer Tools is instrumenting today.
|
||||
</p>
|
||||
|
||||
<p>Opening embedded Developer Tools will <a href="#simultaneous">terminate</a> the
|
||||
remote connection and thus detach the extension.</p>
|
||||
<p>Opening embedded Developer Tools will <a href="#simultaneous">terminate</a> the
|
||||
remote connection and thus detach the extension.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
|
|
@ -152,23 +169,18 @@ remote connection and thus detach the extension.</p>
|
|||
|
||||
|
||||
<div class="collapsible">
|
||||
<h2 id="simultaneous">Simultaneous protocol clients</h2>
|
||||
<p>
|
||||
We currently do not support multiple clients connected to the protocol simultaneously. That includes the DevTools opening while another client is connected. On the bug tracker, <a href="https://code.google.com/p/chromium/issues/detail?id=129539">crbug.com/129539</a> follows the issue; you can star it for email updates.
|
||||
</p>
|
||||
<p>
|
||||
Upon disconnnection, the outgoing client will receive a <code>detached</code> event. For example: <code>{"method":"Inspector.detached","params":{"reason":"replaced_with_devtools"}}</code>. View the <a href="https://code.google.com/p/chromium/codesearch#chromium/src/out/Debug/gen/chrome/common/extensions/api/debugger.cc&q=file:debugger.cc%20Reason%20ParseReason&sq=package:chromium&type=cs&">enum of possible reasons.</a> (For reference: the <a href="https://chromiumcodereview.appspot.com/11361034/">original patch</a>). After disconnection, some apps have chosen to pause their state and offer a reconnect button.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</p>
|
||||
<p></p>
|
||||
|
||||
|
||||
<h2 id="simultaneous">Simultaneous protocol clients</h2>
|
||||
<p>
|
||||
We currently do not support multiple clients connected to the protocol simultaneously. That includes the DevTools opening while another client is connected. On the bug tracker, <a href="https://code.google.com/p/chromium/issues/detail?id=129539">crbug.com/129539</a> follows the issue; you can star it for email updates.
|
||||
</p>
|
||||
<p>
|
||||
Upon disconnnection, the outgoing client will receive a <code>detached</code> event. For example: <code>{"method":"Inspector.detached","params":{"reason":"replaced_with_devtools"}}</code>. View the <a href="https://code.google.com/p/chromium/codesearch#chromium/src/out/Debug/gen/chrome/common/extensions/api/debugger.cc&q=file:debugger.cc%20Reason%20ParseReason&sq=package:chromium&type=cs&">enum of possible reasons.</a> (For reference: the <a href="https://chromiumcodereview.appspot.com/11361034/">original patch</a>). After disconnection, some apps have chosen to pause their state and offer a reconnect button.
|
||||
</p>
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
{{/partials.standard_devtools_article}}
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче