fuchsia/README.md

   1 # Chromium-based Fuchsia services
   2 This directory contains implementation code for various Fuchsia services living
   3 in the Chromium repository. To build Chromium on Fuchsia, check this
   4 [documentation](../docs/fuchsia_build_instructions.md).
   5
   6 [TOC]
   7
   8 ## Code organization
   9 Each of the following subdirectories contain code for a specific Fuchsia
  10 service:
  11 * `./engine` contains the WebEngine implementation. The WebEngine enables
  12 Fuchsia applications to embed Chromium frames for rendering web content.
  13 * `./http` contains an implementation for the Fuchsia HTTP service.
  14 * `./runners`contains implementations of Fuchsia `sys.runner`.
  15     * `./runners/cast` Enables the Fuchsia system to launch cast applications.
  16     * `./runners/web` Enables the Fuchsia system to launch HTTP or HTTPS URLs.
  17 * `./media_receiver` contains an implementation for an Open Screen receiver.
  18
  19 When writing a new Fuchsia service, it is recommended to create a new
  20 subdirectory under `//fuchsia` or a new subdirectory under `//fuchsia/runners`
  21 depending on the use case.
  22
  23 The `./base` subdirectory contains common utilities used by more than one of
  24 the aforementioned Fuchsia services.
  25
  26 The `./cipd` and `./fidl` subdirectories contain CIPD definitions and FIDL
  27 interface definitions, respectfully.
  28
  29 ### Namespacing
  30
  31 Code that is not shared across multiple targets should live in the global
  32 namespace. Code that is shared across multiple targets should live in the
  33 `cr_fuchsia` namespace.
  34
  35 ### Test code
  36
  37 Under the `//fuchsia` directory , there are 3 major types of tests:
  38 * Unit tests: Exercises a single class in isolation, allowing full control
  39   over the external environment of this class.
  40 * Browser tests: Spawns a full browser process along child processes. The test
  41   code is run inside the browser process, allowing for full access to the
  42   browser code, but not other processes.
  43 * Integration tests: they exercise the published API of a Fuchsia component. For
  44   instance, `//fuchsia/engine:web_engine_integration_tests` make use of the
  45   `//fuchsia/engine:web_engine` component. The test code is run in a separate
  46   process in a separate component, allowing only access to the published API of
  47   the component under test.
  48
  49 Integration tests are more resource-intensive than browser tests, which are in
  50 turn more expensive than unit tests. Therefore, when writing new tests, it is
  51 preferred to write unit tests over browser tests over integration tests.
  52
  53 As a general rule, test-only code should live in the same directory as the code
  54 under test with an explicit file name, either `fake_*`, `test_*`,
  55 `*_unittest.cc`, `*_ browser_test.cc` or `*_integration_test.cc`.
  56
  57 Test code that is shared across components should live in a dedicated `test`
  58 directory, under the `cr_fuchsia` namespace. For instance, see the
  59 `//fuchsia/engine/test` directory, which contains code shared by all browser
  60 tests.
  61
  62 ## Deploying and running Fuchsia code.
  63
  64 Fuchsia binaries are deployed and executed via scripts that are automatically
  65 generated by the `fuchsia_package_runner()` GN target.
  66 `fuchsia_package_runner()` targets exist for all tests and a number of
  67 frequently used standalone executables like `"content_shell_fuchsia"`'. The
  68 scripts can deploy to either emulators started by the runner script, an existing
  69 emulator instance, or a physical device.
  70
  71 For the sake of this example, we will be using `base_unittests` as the package
  72 we wish to install and/or execute.
  73
  74 **Hermetic emulation**
  75 ```bash
  76 $ out/fuchsia/bin/run_base_unittests
  77 ```
  78
  79 **Run on an physical device running Zedboot**. Note the `-d` flag, which is an
  80 alias for `--device`.
  81
  82 ```bash
  83 $ out/fuchsia/bin/run_base_unittests -d
  84 ```
  85
  86 **Run on a device paved with Fuchsia built from source.**
  87
  88 ```bash
  89 $ out/fuchsia/bin/run_base_unittests -d
  90 --fuchsia-out-dir=/path/to/fuchsia/outdir
  91 ```
  92
  93 **Install on a device running Fuchsia built from source.**
  94
  95 ```bash
  96 $ out/fuchsia/bin/install_base_unittests
  97 --fuchsia-out-dir=/path/to/fuchsia/outdir
  98 ```
  99
 100 You will need to run the package manually on your device. In this case, run the
 101 following from your Fuchsia directory:
 102
 103 ```
 104 $ fx shell run fuchsia-pkg://fuchsia.com/base_unittests#meta/base_unittests.cmx
 105 ```
 106
 107 If you are frequently deploying to Fuchsia built from source, you might want to
 108 add the following entry to your `args.gn`:
 109
 110 ```
 111 default_fuchsia_build_dir_for_installation = "/path/to/fuchsia/outdir"
 112 ```
 113
 114 With this flag in place, the `--fuchsia-out-dir` flag will automatically be used
 115 whenever you `run_` or `install_` Fuchsia packages, making your command lines
 116 much shorter:
 117
 118 ```bash
 119 $ out/fuchsia/bin/run_base_unittests -d
 120 ```
 121
 122 Make sure that the CPU architecture of your Chromium output directory matches the
 123 architecture of the Fuchsia output directory (x64==x64, arm64==arm64, etc.).
 124
 125 ## Debugging
 126
 127 1. (From Chromium) Install your package(s) and its symbols onto the device.
 128
 129    ```bash
 130    $ out/fuchsia/bin/install_base_unittests
 131    ```
 132
 133 2. (From Fuchsia source tree) Run the debugger.
 134
 135   ```bash
 136   $ fx debug
 137   ```
 138
 139 3. Set up the debugger to attach to the process.
 140
 141   ```
 142   [zxdb] attach base_unittests.cmx
 143   ```
 144
 145 4. Configure breakpoint(s).
 146
 147   ```
 148   [zxdb] break base::GetDefaultJob
 149   ```
 150
 151 5. (In another terminal, from Fuchsia source tree) Run the test package.
 152
 153   ```bash
 154   $ fx shell run fuchsia-pkg://fuchsia.com/base_unittests#meta/base_unittests.cmx
 155   ```
 156
 157 6. At this point, you should hit a breakpoint in `zxdb`.
 158
 159   ```
 160   [zxdb] f
 161   ▶ 0 base::GetDefaultJob() • default_job.cc:18
 162     1 base::$anon::LaunchChildTestProcessWithOptions(…) • test_launcher.cc:335
 163     2 base::$anon::DoLaunchChildTestProcess(…) • test_launcher.cc:528
 164     3 base::TestLauncher::LaunchChildGTestProcess(…) • test_launcher.cc:877
 165     ...
 166   ```
 167
 168 7. Enjoy debugging! Steps 2 through 6 will also work for things like services
 169    which aren't run directly from the command line, such as WebEngine.
 170    Run `help` inside ZXDB to see what debugger commands are available.
 171
 172
 173 ## WebRunner/WebEngine
 174
 175 ### Building and deploying the WebRunner service
 176
 177 When you build `web_runner`, Chromium will automatically generate scripts for
 178 you that will automatically provision a device with Fuchsia and then install
 179 `web_runner` and its dependencies.
 180
 181 To build and run `web_runner`, follow these steps:
 182
 183 1. (Optional) Ensure that you have a device ready to boot into Fuchsia.
 184
 185     If you wish to have `web_runner` manage the OS deployment process, then you
 186     should have the device booting into
 187     [Zedboot](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/usb_setup.md).
 188
 189 2. Build `web_runner`.
 190
 191     ```bash
 192     $ autoninja -C out/fuchsia web_runner
 193     ```
 194
 195 3. Install `web_runner`.
 196
 197     * For devices running Zedboot:
 198
 199         ```bash
 200         $ out/fuchsia/bin/install_web_runner -d
 201         ```
 202
 203     * For devices already booted into Fuchsia:
 204
 205         You will need to add command line flags specifying the device's IP
 206         address and the path to the `ssh_config` used by the device
 207         (located at `$FUCHSIA_OUT_DIR/ssh-keys/ssh_config`):
 208
 209         ```bash
 210         $ out/fuchsia/bin/install_web_runner -d --ssh-config $PATH_TO_SSH_CONFIG
 211         ```
 212
 213 4. Press Alt-Esc key on your device to switch back to terminal mode or run
 214 `fx shell` from the host.
 215
 216 5. Launch a webpage.
 217
 218     ```bash
 219     $ tiles_ctl add https://www.chromium.org/
 220     ```
 221
 222 6. Press Alt-Esc to switch back to graphical view if needed. The browser
 223 window should be displayed and ready to use.
 224
 225 7. You can deploy and run new versions of Chromium without needing to reboot.
 226
 227     First kill any running processes:
 228
 229     ```bash
 230     $ killall context_provider.cmx; killall web_runner.cmx
 231     ```
 232
 233     Then repeat steps 1 through 6 from the installation instructions, excluding
 234     step #3 (running Tiles).
 235
 236
 237 ### Closing a webpage
 238
 239 1. Press the Windows key to return to the terminal.
 240
 241 2. Instruct tiles_ctl to remove the webpage's window tile. The tile's number is
 242     reported by step 6, or it can be found by running `tiles_ctl list` and
 243     noting the ID of the "url" entry.
 244
 245     ```bash
 246     $ tiles_ctl remove TILE_NUMBER
 247     ```