tree: 19d95513aeb6d35d32cbb0d3f633b6ca639158ae [path history] [tgz]
  1. BUILD.gn
  2. DEPS
  3. OWNERS
  4. README.md
  5. base/
  6. cipd/
  7. engine/
  8. fidl/
  9. http/
  10. runners/
fuchsia/README.md

Chromium-based Fuchsia services

This directory contains implementation code for various Fuchsia services living in the Chromium repository.

Code organization

Each of the following subdirectories contain code for a specific Fuchsia service:

  • ./engine contains the WebEngine implementation. The WebEngine enables Fuchsia applications to embed Chromium frames for rendering web content.
  • ./http contains an implementation for the Fuchsia HTTP service.
  • ./runnerscontains implementations of Fuchsia sys.runner.
    • ./runners/cast Enables the Fuchsia system to launch cast applications.
    • ./runners/web Enables the Fuchsia system to launch HTTP or HTTPS URLs.

When writing a new Fuchsia service, it is recommended to create a new subdirectory under //fuchsia or a new subdirectory under //fuchsia/runners depending on the use case.

The ./base subdirectory contains common utilities used by more than one of the aforementioned Fuchsia services.

The ./cipd and ./fidl subdirectories contain CIPD definitions and FIDL interface definitions, respectfully.

Test-only code

Test-only code should live in the same directory as the code under test. There is one exception to this rule for fake implementations of interfaces and shared test fixtures. When the number of source files containing code related to these has reached a certain threshold, they should be moved to a test subdirectory. For instance, see the //fuchsia/engine/test directory.

Namespacing

Code that is not shared across multiple targets should live in the global namespace. Code that is shared across multiple targets should live in the cr_fuchsia namespace.

Running test suites

Building test suites generate a launcher script to run them on a QEMU instance. These scripts are generated at out/fuchsia/bin. For instance,to run the base_unittests target, launch:

$ out/fuchsia/bin/run_base_unittests

Building and deploying the WebRunner service

When you build web_runner, Chromium will automatically generate scripts for you that will automatically provision a device with Fuchsia and then install web_runner and its dependencies.

To build and run web_runner, follow these steps:

  1. (Optional) Ensure that you have a device ready to boot into Fuchsia.

    If you wish to have web_runner manage the OS deployment process, then you should have the device booting into Zedboot.

  2. Build web_runner.

    $ autoninja -C out/fuchsia web_runner
    
  3. Install web_runner.

    • For devices running Zedboot:

      $ out/fuchsia/bin/install_web_runner -d
      
    • For devices already booted into Fuchsia:

      You will need to add command line flags specifying the device's IP address and the path to the ssh_config used by the device (located at $FUCHSIA_OUT_DIR/ssh-keys/ssh_config):

      $ out/fuchsia/bin/install_web_runner -d --ssh-config $PATH_TO_SSH_CONFIG
      
  4. Press Alt-Esc key on your device to switch back to terminal mode or run fx shell from the host.

  5. Launch a webpage.

    $ tiles_ctl add https://www.chromium.org/
    
  6. Press Alt-Esc to switch back to graphical view if needed. The browser window should be displayed and ready to use.

  7. You can deploy and run new versions of Chromium without needing to reboot.

    First kill any running processes:

    $ killall chromium.cmx; killall web_runner.cmx
    

    Then repeat steps 1 through 6 from the installation instructions, excluding step #3 (running Tiles).

Closing a webpage

  1. Press the Windows key to return to the terminal.

  2. Instruct tiles_ctl to remove the webpage‘s window tile. The tile’s number is reported by step 6, or it can be found by running tiles_ctl list and noting the ID of the “url” entry.

    $ tiles_ctl remove TILE_NUMBER
    

Debugging

Rudimentary debugging is now possible with zxdb which is included in the SDK. It is still early and fairly manual to set up. After following the steps above:

  1. To get your device IP address, run ifconfig on the device or fx netaddr on the host.

  2. On the device, run run debug_agent --port=2345.

  3. On the host, run

    third_party/fuchsia_sdk/sdk/tools/zxdb -s out/fuchsia/exe.unstripped -s out/fuchsia/lib.unstripped
    
  4. In zxdb, connect <ip-from-sysinfo-above> 2345.

  5. On the device, run ps and find the pid of the process you want to debug, e.g. web_runner.

  6. In zxdb, attach <pid>. You should be able to attach to multiple processes.

  7. In zxdb, b ComponentControllerImpl::CreateForRequest to set a breakpoint.

  8. On device, do something to make your breakpoint be hit. In this case tiles_ctl add https://www.google.com/ should cause a new request.

At this point, you should hit the breakpoint in zxdb.

[zxdb] l
   25     fuchsia::sys::Package package,
   26     fuchsia::sys::StartupInfo startup_info,
   27     fidl::InterfaceRequest<fuchsia::sys::ComponentController>
   28         controller_request) {
   29   std::unique_ptr<ComponentControllerImpl> result{
 ▶ 30       new ComponentControllerImpl(runner)};
   31   if (!result->BindToRequest(std::move(package), std::move(startup_info),
   32                              std::move(controller_request))) {
   33     return nullptr;
   34   }
   35   return result;
   36 }
   37
   38 ComponentControllerImpl::ComponentControllerImpl(WebContentRunner* runner)
   39     : runner_(runner), controller_binding_(this) {
   40   DCHECK(runner);
[zxdb] f
▶ 0 webrunner::ComponentControllerImpl::CreateForRequest() • component_controller_impl.cc:30
  1 webrunner::WebContentRunner::StartComponent() • web_content_runner.cc:34
  2 fuchsia::sys::Runner_Stub::Dispatch_() • fidl.cc:1255
  3 fidl::internal::StubController::OnMessage() • stub_controller.cc:38
  4 fidl::internal::MessageReader::ReadAndDispatchMessage() • message_reader.cc:213
  5 fidl::internal::MessageReader::OnHandleReady() • message_reader.cc:179
  6 fidl::internal::MessageReader::CallHandler() • message_reader.cc:166
  7 base::AsyncDispatcher::DispatchOrWaitUntil() • async_dispatcher.cc:183
  8 base::MessagePumpFuchsia::HandleEvents() • message_pump_fuchsia.cc:236
  9 base::MessagePumpFuchsia::Run() • message_pump_fuchsia.cc:282
  10 base::MessageLoop::Run() + 0x22b (no line info)
  11 base::RunLoop::Run() • run_loop.cc:102
  12 main() • main.cc:74
  13 0x472010320b8f
  14 0x0
[zxdb]

This documentation maybe be a useful reference if you do not see symbols. That page also has general help on using the debugger.