OLD | NEW |
---|---|
1 # Headless Chromium | 1 # Headless Chromium |
2 | 2 |
3 Headless Chromium is a library for running Chromium in a headless/server | 3 Headless Chromium allows running Chromium in a headless/server environment. |
4 environment. Expected use cases include loading web pages, extracting metadata | 4 Expected use cases include loading web pages, extracting metadata (e.g., the |
5 (e.g., the DOM) and generating bitmaps from page contents -- using all the | 5 DOM) and generating bitmaps from page contents -- using all the modern web |
6 modern web platform features provided by Chromium and Blink. | 6 platform features provided by Chromium and Blink. |
7 | 7 |
8 See the [architecture design doc](https://docs.google.com/document/d/11zIkKkLBoc ofGgoTeeyibB2TZ_k7nR78v7kNelCatUE) | 8 There are two ways to use Headless Chromium: |
9 for more information. | |
10 | 9 |
11 ## Headless shell | 10 ## Usage via the DevTools remote debugging protocol |
12 | 11 |
13 The headless shell is a sample application which demonstrates the use of the | 12 1. Start a normal Chrome binary with the `--headless` command line flag |
14 headless API. To run it, first initialize a headless build configuration: | 13 (Linux-only for now): |
14 | |
15 ``` | |
16 $ chrome --headless --remote-debugging-port=9222 https://chromium.org | |
Eric Seckler
2016/12/23 10:51:46
should we mention --disable-gpu?
Sami
2016/12/23 10:59:43
Good point, done!
| |
17 ``` | |
18 | |
19 2. Navigate to `http://localhost:9222` in another browser to open the | |
20 [DevTools](https://developer.chrome.com/devtools) interface or use a tool such | |
21 as [Selenium](http://www.seleniumhq.org/) to drive the headless browser. | |
22 | |
23 ## Usage as a C++ library | |
24 | |
25 Headless Chromium can be built as a library for embedding into a C++ | |
26 application. This approach is otherwise similar to controlling the browser over | |
27 a DevTools connection, but it provides more customization points, e.g., for | |
28 networking and [mojo services](https://docs.google.com/document/d/1Fr6_DJH6OK9rG 3-ibMvRPTNnHsAXPk0VzxxiuJDSK3M/edit#heading=h.qh0udvlk963d). | |
29 | |
30 Headless Shell is a sample application which demonstrates the use of the | |
31 headless C++ API. To run it, first initialize a headless build configuration: | |
15 | 32 |
16 ``` | 33 ``` |
17 $ mkdir -p out/Debug | 34 $ mkdir -p out/Debug |
18 $ echo 'import("//build/args/headless.gn")' > out/Debug/args.gn | 35 $ echo 'import("//build/args/headless.gn")' > out/Debug/args.gn |
19 $ gn gen out/Debug | 36 $ gn gen out/Debug |
20 ``` | 37 ``` |
21 | 38 |
22 Then build the shell: | 39 Then build the shell: |
23 | 40 |
24 ``` | 41 ``` |
25 $ ninja -C out/Debug headless_shell | 42 $ ninja -C out/Debug headless_shell |
26 ``` | 43 ``` |
27 | 44 |
28 After the build completes, the headless shell can be run with the following | 45 After the build completes, Headless Shell can be run with the following command: |
29 command: | |
30 | 46 |
31 ``` | 47 ``` |
32 $ out/Debug/headless_shell https://www.google.com | 48 $ out/Debug/headless_shell https://www.google.com |
33 ``` | 49 ``` |
34 | 50 |
35 To attach a [DevTools](https://developer.chrome.com/devtools) debugger to the | 51 To attach a [DevTools](https://developer.chrome.com/devtools) debugger to the |
36 shell, start it with an argument specifying the debugging port: | 52 shell, start it with an argument specifying the debugging port: |
37 | 53 |
38 ``` | 54 ``` |
39 $ out/Debug/headless_shell --remote-debugging-port=9222 https://youtube.com | 55 $ out/Debug/headless_shell --remote-debugging-port=9222 https://youtube.com |
40 ``` | 56 ``` |
41 | 57 |
42 Then navigate to `http://127.0.0.1:9222` with your browser. | 58 Then navigate to `http://localhost:9222` with your browser. |
43 | 59 |
44 ## Embedder API | 60 ## Embedder API |
45 | 61 |
46 The embedder API allows developers to integrate the headless library into their | 62 The embedder API allows developers to integrate the headless library into their |
47 application. The API provides default implementations for low level adaptation | 63 application. The API provides default implementations for low level adaptation |
48 points such as networking and the run loop. | 64 points such as networking and the run loop. |
49 | 65 |
50 The main embedder API classes are: | 66 The main embedder API classes are: |
51 | 67 |
52 - `HeadlessBrowser::Options::Builder` - Defines the embedding options, e.g.: | 68 - `HeadlessBrowser::Options::Builder` - Defines the embedding options, e.g.: |
53 - `SetMessagePump` - Replaces the default base message pump. See | 69 - `SetMessagePump` - Replaces the default base message pump. See |
54 `base::MessagePump`. | 70 `base::MessagePump`. |
55 - `SetProxyServer` - Configures an HTTP/HTTPS proxy server to be used for | 71 - `SetProxyServer` - Configures an HTTP/HTTPS proxy server to be used for |
56 accessing the network. | 72 accessing the network. |
57 | 73 |
58 ## Client/DevTools API | 74 ## Client/DevTools API |
59 | 75 |
60 The headless client API is used to drive the browser and interact with loaded | 76 The headless client API is used to drive the browser and interact with loaded |
61 web pages. Its main classes are: | 77 web pages. Its main classes are: |
62 | 78 |
63 - `HeadlessBrowser` - Represents the global headless browser instance. | 79 - `HeadlessBrowser` - Represents the global headless browser instance. |
64 - `HeadlessWebContents` - Represents a single "tab" within the browser. | 80 - `HeadlessWebContents` - Represents a single "tab" within the browser. |
65 - `HeadlessDevToolsClient` - Provides a C++ interface for inspecting and | 81 - `HeadlessDevToolsClient` - Provides a C++ interface for inspecting and |
66 controlling a tab. The API functions corresponds to [DevTools commands](https: //developer.chrome.com/devtools/docs/debugger-protocol). | 82 controlling a tab. The API functions corresponds to [DevTools commands](https: //developer.chrome.com/devtools/docs/debugger-protocol). |
67 See the [client API documentation](https://docs.google.com/document/d/1rlqcp8n k-ZQvldNJWdbaMbwfDbJoOXvahPCDoPGOwhQ/edit#) | 83 See the [client API documentation](https://docs.google.com/document/d/1rlqcp8n k-ZQvldNJWdbaMbwfDbJoOXvahPCDoPGOwhQ/edit#) |
68 for more information. | 84 for more information. |
69 | 85 |
70 ## Documentation | 86 ## Resources and Documentation |
87 | |
88 Mailing list: [headless-dev@chromium.org](https://groups.google.com/a/chromium.o rg/forum/#!forum/headless-dev) | |
89 Bug tracker: [Proj=Headless](https://bugs.chromium.org/p/chromium/issues/list?ca n=2&q=Proj%3DHeadless) | |
71 | 90 |
72 * [Runtime headless mode for Chrome](https://docs.google.com/document/d/1aIJUzQr 3eougZQp90bp4mqGr5gY6hdUice8UPa-Ys90/edit#) | 91 * [Runtime headless mode for Chrome](https://docs.google.com/document/d/1aIJUzQr 3eougZQp90bp4mqGr5gY6hdUice8UPa-Ys90/edit#) |
73 * [Virtual Time in Blink](https://docs.google.com/document/d/1y9kdt_zezt7pbey6uz vt1dgklwc1ob_vy4nzo1zbqmo/edit#heading=h.tn3gd1y9ifml) | 92 * [Virtual Time in Blink](https://docs.google.com/document/d/1y9kdt_zezt7pbey6uz vt1dgklwc1ob_vy4nzo1zbqmo/edit#heading=h.tn3gd1y9ifml) |
74 * [Headless Chrome architecture](https://docs.google.com/document/d/11zIkKkLBoco fGgoTeeyibB2TZ_k7nR78v7kNelCatUE/edit) | 93 * [Headless Chrome architecture](https://docs.google.com/document/d/11zIkKkLBoco fGgoTeeyibB2TZ_k7nR78v7kNelCatUE/edit) |
75 * [Headless Chrome C++ DevTools API](https://docs.google.com/document/d/1rlqcp8n k-ZQvldNJWdbaMbwfDbJoOXvahPCDoPGOwhQ/edit#heading=h.ng2bxb15li9a) | 94 * [Headless Chrome C++ DevTools API](https://docs.google.com/document/d/1rlqcp8n k-ZQvldNJWdbaMbwfDbJoOXvahPCDoPGOwhQ/edit#heading=h.ng2bxb15li9a) |
76 * [Session isolation in Headless Chrome](https://docs.google.com/document/d/1XAK vrxtSEoe65vNghSWC5S3kJ--z2Zpt2UWW1Fi8GiM/edit) | 95 * [Session isolation in Headless Chrome](https://docs.google.com/document/d/1XAK vrxtSEoe65vNghSWC5S3kJ--z2Zpt2UWW1Fi8GiM/edit) |
77 * [Headless Chrome mojo service](https://docs.google.com/document/d/1Fr6_DJH6OK9 rG3-ibMvRPTNnHsAXPk0VzxxiuJDSK3M/edit#heading=h.qh0udvlk963d) | 96 * [Headless Chrome mojo service](https://docs.google.com/document/d/1Fr6_DJH6OK9 rG3-ibMvRPTNnHsAXPk0VzxxiuJDSK3M/edit#heading=h.qh0udvlk963d) |
78 * [Controlling BeginFrame through DevTools](https://docs.google.com/document/d/1 LVMYDkfjrrX9PNkrD8pJH5-Np_XUTQHIuJ8IEOirQH4/edit?ts=57d96dbd#heading=h.ndv831lc9 uf0) | 97 * [Controlling BeginFrame through DevTools](https://docs.google.com/document/d/1 LVMYDkfjrrX9PNkrD8pJH5-Np_XUTQHIuJ8IEOirQH4/edit?ts=57d96dbd#heading=h.ndv831lc9 uf0) |
79 * [Viewport bounds and scale for screenshots](https://docs.google.com/document/d /1VTcYz4q_x0f1O5IVrvRX4u1DVd_K34IVUl1VULLTCWw/edit#heading=h.ndv831lc9uf0) | 98 * [Viewport bounds and scale for screenshots](https://docs.google.com/document/d /1VTcYz4q_x0f1O5IVrvRX4u1DVd_K34IVUl1VULLTCWw/edit#heading=h.ndv831lc9uf0) |
80 * [BlinkOn 6 presentation slides](https://docs.google.com/presentation/d/1gqK9F4 lGAY3TZudAtdcxzMQNEE7PcuQrGu83No3l0lw/edit#slide=id.p) | 99 * [BlinkOn 6 presentation slides](https://docs.google.com/presentation/d/1gqK9F4 lGAY3TZudAtdcxzMQNEE7PcuQrGu83No3l0lw/edit#slide=id.p) |
100 * [Architecture design doc](https://docs.google.com/document/d/11zIkKkLBocofGgoT eeyibB2TZ_k7nR78v7kNelCatUE) | |
OLD | NEW |