[fuchsia] Improve docs for running/installing/debugging Fuchsia binaries.

Update README.md how-to docs to use the new `--fuchsia-out-dir` flag.

Update the debugging how-to in README.md to incorporate improvements
with Chromium package/symbol installation and the "fx debug"
entrypoint.

Change-Id: I95f99c37c5afedb06db5229eae820d06353b45cc
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1913573
Commit-Queue: Kevin Marshall <kmarshall@chromium.org>
Reviewed-by: David Dorwin <ddorwin@chromium.org>
Cr-Commit-Position: refs/heads/master@{#715884}

fuchsia/README.md

@@ -58,7 +58,120 @@ directory, under the `cr_fuchsia` namespace. For instance, see the
 `//fuchsia/engine/test` directory, which contains code shared by all browser
 tests.
 
-## Building and deploying the WebRunner service
+## Deploying and running Fuchsia code.
+
+Fuchsia binaries are deployed and executed via scripts that are automatically
+generated by the `fuchsia_package_runner()` GN target.
+`fuchsia_package_runner()` targets exist for all tests and a number of
+frequently used standalone executables like `"content_shell_fuchsia"`'. The
+scripts can deploy to either emulators started by the runner script, an existing
+emulator instance, or a physical device.
+
+For the sake of this example, we will be using `base_unittests` as the package
+we wish to install and/or execute.
+
+**Hermetic emulation**
+```bash
+$ out/fuchsia/bin/run_base_unittests
+```
+
+**Run on an physical device running Zedboot**. Note the `-d` flag, which is an
+alias for `--device`.
+
+```bash
+$ out/fuchsia/bin/run_base_unittests -d
+```
+
+**Run on a device paved with Fuchsia built from source.**
+
+```bash
+$ out/fuchsia/bin/run_base_unittests -d
+--fuchsia-out-dir=/path/to/fuchsia/outdir
+```
+
+**Install on a device running Fuchsia built from source.**
+
+```bash
+$ out/fuchsia/bin/install_base_unittests
+--fuchsia-out-dir=/path/to/fuchsia/outdir
+```
+
+You will need to run the package manually on your device. In this case, run the
+following from your Fuchsia directory:
+
+```
+$ fx shell run fuchsia-pkg://fuchsia.com/base_unittests#meta/base_unittests.cmx
+```
+
+If you are frequently deploying to Fuchsia built from source, you might want to
+add the following entry to your `args.gn`:
+
+```
+default_fuchsia_build_dir_for_installation = "/path/to/fuchsia/outdir"
+```
+
+With this flag in place, the `--fuchsia-out-dir` flag will automatically be used
+whenever you `run_` or `install_` Fuchsia packages, making your command lines
+much shorter:
+
+```bash
+$ out/fuchsia/bin/run_base_unittests -d
+```
+
+Make sure that the CPU architecture of your Chromium output directory matches the
+architecture of the Fuchsia output directory (x64==x64, arm64==arm64, etc.).
+
+## Debugging
+
+1. (From Chromium) Install your package(s) and its symbols onto the device.
+
+   ```bash
+   $ out/fuchsia/bin/install_base_unittests
+   ```
+
+2. (From Fuchsia source tree) Run the debugger.
+
+  ```bash
+  $ fx debug
+  ```
+
+3. Set up the debugger to attach to the process.
+
+  ```
+  [zxdb] attach base_unittests.cmx
+  ```
+
+4. Configure breakpoint(s).
+
+  ```
+  [zxdb] break base::GetDefaultJob
+  ```
+
+5. (In another terminal, from Fuchsia source tree) Run the test package.
+
+  ```bash
+  $ fx shell run fuchsia-pkg://fuchsia.com/base_unittests#meta/base_unittests.cmx
+  ```
+
+6. At this point, you should hit a breakpoint in `zxdb`.
+
+  ```
+  [zxdb] f
+  ▶ 0 base::GetDefaultJob() • default_job.cc:18
+    1 base::$anon::LaunchChildTestProcessWithOptions(…) • test_launcher.cc:335
+    2 base::$anon::DoLaunchChildTestProcess(…) • test_launcher.cc:528
+    3 base::TestLauncher::LaunchChildGTestProcess(…) • test_launcher.cc:877
+    ...
+  ```
+
+7. Enjoy debugging! Steps 2 through 6 will also work for things like services
+   which aren't run directly from the command line, such as WebEngine.
+   Run `help` inside ZXDB to see what debugger commands are available.
+
+
+## WebRunner/WebEngine
+
+### 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
@@ -132,74 +245,3 @@ window should be displayed and ready to use.
     $ 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
-
-    ```bash
-    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](https://fuchsia.googlesource.com/garnet/+/master/docs/debugger.md#diagnosing-symbol-problems)
-maybe be a useful reference if you do not see symbols. That page also has
-general help on using the debugger.