Index: headless/README.md |
diff --git a/headless/README.md b/headless/README.md |
index 9e98dae1d36f06aed2a9491068ab342c91700d3c..bf4d30149cfd9885fcc7415769619b36b13c4d37 100644 |
--- a/headless/README.md |
+++ b/headless/README.md |
@@ -1,17 +1,37 @@ |
# Headless Chromium |
-Headless Chromium is a library for running Chromium in a headless/server |
-environment. Expected use cases include loading web pages, extracting metadata |
-(e.g., the DOM) and generating bitmaps from page contents -- using all the |
-modern web platform features provided by Chromium and Blink. |
+Headless Chromium allows running Chromium in a headless/server environment. |
+Expected use cases include loading web pages, extracting metadata (e.g., the |
+DOM) and generating bitmaps from page contents -- using all the modern web |
+platform features provided by Chromium and Blink. |
-See the [architecture design doc](https://docs.google.com/document/d/11zIkKkLBocofGgoTeeyibB2TZ_k7nR78v7kNelCatUE) |
-for more information. |
+There are two ways to use Headless Chromium: |
-## Headless shell |
+## Usage via the DevTools remote debugging protocol |
-The headless shell is a sample application which demonstrates the use of the |
-headless API. To run it, first initialize a headless build configuration: |
+1. Start a normal Chrome binary with the `--headless` command line flag |
+(Linux-only for now): |
+ |
+``` |
+$ chrome --headless --remote-debugging-port=9222 https://chromium.org |
+``` |
+ |
+Currently you'll also need to use `--disable-gpu` to avoid an error from a |
+missing Mesa library. |
+ |
+2. Navigate to `http://localhost:9222` in another browser to open the |
+[DevTools](https://developer.chrome.com/devtools) interface or use a tool such |
+as [Selenium](http://www.seleniumhq.org/) to drive the headless browser. |
+ |
+## Usage as a C++ library |
+ |
+Headless Chromium can be built as a library for embedding into a C++ |
+application. This approach is otherwise similar to controlling the browser over |
+a DevTools connection, but it provides more customization points, e.g., for |
+networking and [mojo services](https://docs.google.com/document/d/1Fr6_DJH6OK9rG3-ibMvRPTNnHsAXPk0VzxxiuJDSK3M/edit#heading=h.qh0udvlk963d). |
+ |
+Headless Shell is a sample application which demonstrates the use of the |
+headless C++ API. To run it, first initialize a headless build configuration: |
``` |
$ mkdir -p out/Debug |
@@ -25,8 +45,7 @@ Then build the shell: |
$ ninja -C out/Debug headless_shell |
``` |
-After the build completes, the headless shell can be run with the following |
-command: |
+After the build completes, Headless Shell can be run with the following command: |
``` |
$ out/Debug/headless_shell https://www.google.com |
@@ -39,7 +58,7 @@ shell, start it with an argument specifying the debugging port: |
$ out/Debug/headless_shell --remote-debugging-port=9222 https://youtube.com |
``` |
-Then navigate to `http://127.0.0.1:9222` with your browser. |
+Then navigate to `http://localhost:9222` with your browser. |
## Embedder API |
@@ -67,7 +86,10 @@ web pages. Its main classes are: |
See the [client API documentation](https://docs.google.com/document/d/1rlqcp8nk-ZQvldNJWdbaMbwfDbJoOXvahPCDoPGOwhQ/edit#) |
for more information. |
-## Documentation |
+## Resources and Documentation |
+ |
+Mailing list: [headless-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/headless-dev) |
+Bug tracker: [Proj=Headless](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=Proj%3DHeadless) |
* [Runtime headless mode for Chrome](https://docs.google.com/document/d/1aIJUzQr3eougZQp90bp4mqGr5gY6hdUice8UPa-Ys90/edit#) |
* [Virtual Time in Blink](https://docs.google.com/document/d/1y9kdt_zezt7pbey6uzvt1dgklwc1ob_vy4nzo1zbqmo/edit#heading=h.tn3gd1y9ifml) |
@@ -78,3 +100,4 @@ web pages. Its main classes are: |
* [Controlling BeginFrame through DevTools](https://docs.google.com/document/d/1LVMYDkfjrrX9PNkrD8pJH5-Np_XUTQHIuJ8IEOirQH4/edit?ts=57d96dbd#heading=h.ndv831lc9uf0) |
* [Viewport bounds and scale for screenshots](https://docs.google.com/document/d/1VTcYz4q_x0f1O5IVrvRX4u1DVd_K34IVUl1VULLTCWw/edit#heading=h.ndv831lc9uf0) |
* [BlinkOn 6 presentation slides](https://docs.google.com/presentation/d/1gqK9F4lGAY3TZudAtdcxzMQNEE7PcuQrGu83No3l0lw/edit#slide=id.p) |
+* [Architecture design doc](https://docs.google.com/document/d/11zIkKkLBocofGgoTeeyibB2TZ_k7nR78v7kNelCatUE) |