| OLD | NEW |
|---|
| (Empty) |
| 1 # Running Blimp | |
| 2 [TOC] | |
| 3 | |
| 4 See [build](build.md) for instructions on how to build Blimp. | |
| 5 | |
| 6 ## Android Client | |
| 7 | |
| 8 ### Installing the client | |
| 9 | |
| 10 Install the Chrome Public APK with the following: | |
| 11 | |
| 12 ```bash | |
| 13 ./build/android/adb_install_apk.py $(PRODUCT_DIR)/apks/ChromePublic.apk | |
| 14 ``` | |
| 15 | |
| 16 ### Setting up command line flags | |
| 17 | |
| 18 Set up any command line flags with: | |
| 19 | |
| 20 ```bash | |
| 21 ./build/android/adb_chrome_public_command_line <your flags here> | |
| 22 ``` | |
| 23 | |
| 24 For example: | |
| 25 ```bash | |
| 26 ./build/android/adb_chrome_public_command_line --engine-ip=127.0.0.1 \ | |
| 27 --engine-port=25467 --engine-transport=tcp \ | |
| 28 --blimp-client-token-path=/data/data/org.chromium.chrome/blimp_client_token \ | |
| 29 --vmodule="*=1" | |
| 30 ``` | |
| 31 | |
| 32 To see your current command line, run | |
| 33 `./build/android/adb_chrome_public_command_line` without any arguments. | |
| 34 | |
| 35 ### Instructing client to connect to specific host | |
| 36 | |
| 37 To have the client connect to a custom engine use the `--engine-ip`, | |
| 38 `--engine-port`, and `--engine-transport` flags. The possible valid | |
| 39 values for `--engine-transport` are 'tcp' and 'ssl'. | |
| 40 An example valid endpoint would be | |
| 41 `--engine-ip=127.0.0.1 --engine-port=25467 --engine-transport=tcp`. | |
| 42 | |
| 43 SSL-encrypted connections take an additional flag | |
| 44 `--engine-cert-path` which specifies a path to a PEM-encoded certificate | |
| 45 file (e.g. `--engine-cert-path=/path_on_device_to/file.pem`). Remember to also | |
| 46 copy the file to the device when using this option. | |
| 47 | |
| 48 ### Specifying the client auth token file | |
| 49 The client needs access to a file containing a client auth token. One should | |
| 50 make sure this file is available by pushing it onto the device before running | |
| 51 the client. One can do this by running the following command: | |
| 52 | |
| 53 ```bash | |
| 54 adb push /path/to/blimp_client_token \ | |
| 55 /data/data/org.chromium.chrome/blimp_client_token | |
| 56 ``` | |
| 57 | |
| 58 To have the client use the given client auth token file, use the | |
| 59 `--blimp-client-token-path` flag (e.g. | |
| 60 `--blimp-client-token-path=/data/data/org.chromium.chrome/blimp_client_token`) | |
| 61 | |
| 62 An example of a client token file is | |
| 63 [test_client_token](https://code.google.com/p/chromium/codesearch#chromium/src/b
limp/test/data/test_client_token). | |
| 64 | |
| 65 ### Optional: Forcefully enabling the blimp client | |
| 66 | |
| 67 Usually, the end user will have to manually enable blimp by using the Blimp | |
| 68 panel in the application settings, but for developers it might be beneficial to | |
| 69 skip this check by forcefully enabling the blimp client. | |
| 70 | |
| 71 You can do this by adding the command line flag: | |
| 72 ``` | |
| 73 --enable-blimp | |
| 74 ``` | |
| 75 | |
| 76 *Note:* This still does not skip the authentication checks for the assigner. You | |
| 77 will still have to either pass in the `--engine-ip=...` argument or sign in | |
| 78 with a valid account. | |
| 79 | |
| 80 ### Optional: Requesting the complete page from the engine | |
| 81 | |
| 82 The engine sends partially rendered content to the client. To request the | |
| 83 complete page from the engine, use the `--download-whole-document` flag on the | |
| 84 client. | |
| 85 | |
| 86 ### Give Permissions & Start the Client | |
| 87 | |
| 88 Give permissions to app: Long-press the chromium icon on your app drawer, | |
| 89 dragging it to the “App info” shortcut that appears at the top of the screen, | |
| 90 and releasing it. Once the "App info" opens, there should be a "Permissions" | |
| 91 entry. Make sure to enable all permissions inside the "Permissions" screen. | |
| 92 | |
| 93 Run the Chrome Public APK with: | |
| 94 | |
| 95 ```bash | |
| 96 ./build/android/adb_run_chrome_public | |
| 97 ``` | |
| 98 | |
| 99 ### Connecting to an Engine running on a workstation | |
| 100 To run the engine on a workstation and make your Android client connect to it, | |
| 101 you need to forward a port from the Android device to the host, and also | |
| 102 instruct the client to connect using that port on its localhost address. | |
| 103 | |
| 104 #### Port forwarding | |
| 105 If you are running the engine on your workstation and are connected to the | |
| 106 client device via USB, you'll need remote port forwarding to allow the Blimp | |
| 107 client to talk to your computer. | |
| 108 | |
| 109 ##### Option A | |
| 110 Follow the | |
| 111 [remote debugging instructions](https://developer.chrome.com/devtools/docs/remot
e-debugging) | |
| 112 to get started. You'll probably want to remap 25467 to "localhost:25467". | |
| 113 *Note* This requires the separate `Chrome` application to be running on the | |
| 114 device. Otherwise you will not see the green light for the port forwarding. | |
| 115 | |
| 116 ##### Option B | |
| 117 If you are having issues with using the built-in Chrome port forwarding, you can | |
| 118 also start a new shell and keep the following command running: | |
| 119 | |
| 120 ```bash | |
| 121 ./build/android/adb_reverse_forwarder.py --debug -v 25467 25467 | |
| 122 ``` | |
| 123 | |
| 124 ### Running the client in an Android emulator | |
| 125 Running the client using an Android emulator is similar to running it on device. | |
| 126 Here are a few gotchas: | |
| 127 | |
| 128 * Build an APK matching the emulator cpu type. The emulator cpu type is most | |
| 129 likely x86, while the default Android build cpu type is ARM. Follow the | |
| 130 Android build instructions above to change the CPU type. | |
| 131 | |
| 132 * Ensure that the emulator is running at least Android Marshmallow so that | |
| 133 fonts are rendered correctly. Also ensure that you have the latest Play | |
| 134 services binaries. | |
| 135 | |
| 136 * Some of scripts under `build/android` will fail to run as it uses `adb scp`. | |
| 137 Follow the instruction above to use `adb` directly. | |
| 138 | |
| 139 * To connect to an Engine running on the host machine, you should use | |
| 140 `10.0.2.2` as `engine-ip` instead of `127.0.0.1` as `127.0.0.1` will refer to | |
| 141 the emulator itself. There is no need of set up | |
| 142 [port forwarding](#Port-forwarding) when this approach is used. | |
| 143 | |
| 144 ## Linux Client | |
| 145 | |
| 146 The Linux client is useful for development purposes where the full Android UI is | |
| 147 not required. | |
| 148 | |
| 149 Build with the following commands: | |
| 150 ``` | |
| 151 gn gen out-linux/Client | |
| 152 ninja -C out-linux/Client blimp_shell | |
| 153 ``` | |
| 154 | |
| 155 | |
| 156 To run it with local logging enabled, execute: | |
| 157 | |
| 158 ```bash | |
| 159 ./out-linux/Client/blimp_shell \ | |
| 160 --user-data-dir=/tmp/blimpclient \ | |
| 161 --enable-logging=stderr \ | |
| 162 --vmodule="*=1" \ | |
| 163 --engine-ip=127.0.0.1 \ | |
| 164 --engine-port=25467 \ | |
| 165 --engine-transport=tcp \ | |
| 166 --blimp-client-token-path=/tmp/blimpengine-token | |
| 167 ``` | |
| 168 | |
| 169 **PS:** Create the `/tmp/blimpengine-token` file with any sequence of | |
| 170 characters. For example: | |
| 171 | |
| 172 ``` | |
| 173 echo "anything" > /tmp/blimpengine-token | |
| 174 ``` | |
| 175 | |
| 176 ## Running the engine | |
| 177 | |
| 178 ### In a container | |
| 179 For running the engine in a container, see [container](container.md). | |
| 180 | |
| 181 ### On a workstation | |
| 182 The following flags are required to start an Engine instance: | |
| 183 | |
| 184 * `--blimp-client-token-path=$PATH`: Path to a file containing a nonempty | |
| 185 token string. If this is not present, the engine will fail to boot. | |
| 186 * `--use-remote-compositing`: Ensures that the renderer uses the remote | |
| 187 compositor. | |
| 188 * `--disable-cached-picture-raster`: Ensures that rasterized content is not | |
| 189 destroyed before serialization. | |
| 190 * `--android-fonts-path=$PATH`: Path to where the fonts are located. | |
| 191 If the Android client is Kitkat system, this would be | |
| 192 `out-linux/Debug/gen/third_party/blimp_fonts/font_bundle/kitkat/`. | |
| 193 If the Android client is Marshmallow system, this would be | |
| 194 `out-linux/Debug/gen/third_party/blimp_fonts/font_bundle/marshmallow/`. | |
| 195 * `--disable-remote-fonts`: Disables downloading of custom web fonts in the | |
| 196 renderer. | |
| 197 | |
| 198 #### Typical invocation | |
| 199 | |
| 200 One can start the engine using these flags: | |
| 201 | |
| 202 ```bash | |
| 203 out-linux/Debug/blimp_engine_app \ | |
| 204 --android-fonts-path=out-linux/Debug/gen/third_party/blimp_fonts/font_bundle/m
arshmallow/ \ | |
| 205 --blimp-client-token-path=/tmp/blimpengine-token \ | |
| 206 --enable-logging=stderr \ | |
| 207 --vmodule="blimp*=1" | |
| 208 ``` | |
| 209 | |
| 210 ## Running client engine integration with script | |
| 211 | |
| 212 When building the target `blimp` on a Linux host, a script is created which | |
| 213 automates running the Blimp client and starting the engine. Setting up the | |
| 214 environment like this is much quicker than executing each of the steps | |
| 215 separately. It is used for development purpose as well as running tests under | |
| 216 integration environment. | |
| 217 | |
| 218 ### Generate the script | |
| 219 | |
| 220 The script is wrapped as an command `client_engine_integration` and ends up in | |
| 221 `out-linux/Debug/bin/` which is generated with building engine. Command should b
e with | |
| 222 the positional argument `{start,run,load,stop}`. | |
| 223 | |
| 224 ### Running the script | |
| 225 | |
| 226 One can use the script to set up engine and connect it with client, then start c
lient. | |
| 227 | |
| 228 #### Option A | |
| 229 | |
| 230 1. `{start}` Start engine & forwarder: | |
| 231 | |
| 232 ```bash | |
| 233 out-linux/Debug/bin/client_engine_integration start | |
| 234 ``` | |
| 235 | |
| 236 Engine runs until when you run the script with `{stop}` as the positional ar
gument. | |
| 237 | |
| 238 2. After engine starting successfully, run `{load}` client which installs apk i
n | |
| 239 device and runs blimp. | |
| 240 | |
| 241 ```bash | |
| 242 out-linux/Debug/bin/client_engine_integration load -p/--apk-path /path/to/ap
k | |
| 243 ``` | |
| 244 | |
| 245 You are now ready to run tests or do development. | |
| 246 | |
| 247 Instead of `{load}`, if want to manually install/launch the client can also
do | |
| 248 e.g. the incremental install: | |
| 249 | |
| 250 ```bash | |
| 251 ninja -C out-android/Debug blimp chrome_public_apk_incremental && \ | |
| 252 out-android/Debug/bin/install_chrome_public_apk_incremental | |
| 253 ``` | |
| 254 | |
| 255 3. `{stop}` Stops the engine & the forwarder: | |
| 256 | |
| 257 ```bash | |
| 258 out-linux/Debug/bin/client_engine_integration stop | |
| 259 ``` | |
| 260 | |
| 261 #### Option B | |
| 262 | |
| 263 1. `{run}` Start and keep running engine & forwarder. | |
| 264 Script keeps running and auto-checking engine process. Is responsible for | |
| 265 killing engine if keyboard interrupts or client gets killed. | |
| 266 | |
| 267 ```bash | |
| 268 out-linux/Debug/bin/client_engine_integration run | |
| 269 ``` | |
| 270 | |
| 271 2. Same as step 2 in Option A. | |
| 272 | |
| 273 3. Engine should be auto-killed by keyboard stopping the `{run}` script or the
client | |
| 274 gets wiped out. `{stop}` works as well. | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2626423004:
Remove all //blimp code. (Closed)
