[Fuchsia] Create/Reorganize documentation for Fuchsia
Put Fuchsia specific instructions in //docs/fuchsia
Added instructions for running blink and gpu integration tests.
Added instructions for running tests on remote devices.
Bug: 1174296
Change-Id: I54fabb5b339fe90b3517c6341c62d7269726772f
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2673628
Reviewed-by: Sharon Yang <[email protected]>
Reviewed-by: Bob Haarman <[email protected]>
Reviewed-by: Fabrice de Gans-Riberi <[email protected]>
Auto-Submit: Chong Gu <[email protected]>
Commit-Queue: Chong Gu <[email protected]>
Cr-Commit-Position: refs/heads/master@{#854575}
diff --git a/docs/fuchsia/build_instructions.md b/docs/fuchsia/build_instructions.md
new file mode 100644
index 0000000..0b37b748
--- /dev/null
+++ b/docs/fuchsia/build_instructions.md
@@ -0,0 +1,210 @@
+# Checking out and building on Fuchsia
+
+***Note that the Fuchsia port is in the early stages, and things are likely to
+frequently be broken. Try #cr-fuchsia on Freenode or Slack if something seems
+awry.***
+
+There are instructions for other platforms linked from the
+[get the code](get_the_code.md) page.
+
+[TOC]
+
+## System requirements
+
+* A 64-bit Intel machine with at least 8GB of RAM. More than 16GB is highly
+ recommended.
+* At least 100GB of free disk space.
+* You must have Git and Python installed already.
+
+Most development is done on Ubuntu. Mac build is supported on a best-effort
+basis.
+
+## Install `depot_tools`
+
+Clone the `depot_tools` repository:
+
+```shell
+$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
+```
+
+Add `depot_tools` to the end of your PATH (you will probably want to put this
+in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned `depot_tools` to
+`/path/to/depot_tools`:
+
+```shell
+$ export PATH="$PATH:/path/to/depot_tools"
+```
+
+## Get the code
+
+Create a `chromium` directory for the checkout and change to it (you can call
+this whatever you like and put it wherever you like, as long as the full path
+has no spaces):
+
+```shell
+$ mkdir ~/chromium && cd ~/chromium
+```
+
+Run the `fetch` tool from depot_tools to check out the code and its
+dependencies.
+
+```shell
+$ fetch --nohooks chromium
+```
+
+Expect the command to take 30 minutes on even a fast connection, and many
+hours on slower ones.
+
+If you've already installed the build dependencies on the machine (from another
+checkout, for example), you can omit the `--nohooks` flag and `fetch`
+will automatically execute `gclient runhooks` at the end.
+
+When `fetch` completes, it will have created a hidden `.gclient` file and a
+directory called `src` in the working directory.
+
+### Configure for building on Fuchsia
+
+Edit `.gclient` to include (this is a list, so it could also include `android`,
+etc. if necessary.)
+
+```
+target_os = ['fuchsia']
+```
+
+Note that this should be added as a top-level statement in the `.gclient` file,
+not an entry inside the `solutions` dict. An example `.gclient` file would look
+as follows:
+
+```
+solutions = [
+ {
+ "url": "https://chromium.googlesource.com/chromium/src.git",
+ "managed": False,
+ "name": "src",
+ "custom_deps": {},
+ "custom_vars": {}
+ }
+]
+target_os = ['fuchsia']
+```
+
+You will then need to run:
+
+```shell
+$ gclient sync
+```
+
+This makes sure the Fuchsia SDK is available in third\_party and keeps it up to
+date.
+
+The remaining instructions assume you have switched to the `src` directory:
+
+```shell
+$ cd src
+```
+
+### (Linux-only) Install any required host packages
+
+Chromium relies on some platform packages to be present in order to build.
+You can install the current set of required packages with:
+
+```shell
+$ build/install-build-deps.sh
+```
+
+Note that you need to do this only once, and thereafter only if new dependencies
+are added - these will be announced to the chromium-dev@ group.
+
+### Update your checkout
+
+To update an existing checkout, you can run
+
+```shell
+$ git rebase-update
+$ gclient sync
+```
+
+The first command updates the primary Chromium source repository and rebases
+any of your local branches on top of tip-of-tree (aka the Git branch
+`origin/master`). If you don't want to use this script, you can also just use
+`git pull` or other common Git commands to update the repo.
+
+The second command syncs dependencies to the appropriate versions and re-runs
+hooks as needed. `gclient sync` updates dependencies to the versions specified
+in `DEPS`, so any time that file is modified (pulling, changing branches, etc.)
+`gclient sync` should be run.
+
+## (Mac-only) Download additional required Clang binaries
+
+Go to [this page](https://chrome-infra-packages.appspot.com/p/fuchsia/clang/mac-amd64/+/)
+and download the most recent build. Extract `bin/llvm-ar` to the clang folder
+in Chromium:
+
+```shell
+$ unzip /path/to/clang.zip bin/llvm-ar -d ${CHROMIUM_SRC}/third_party/llvm-build/Release+Asserts
+```
+
+## Setting up the build
+
+Chromium uses [Ninja](https://ninja-build.org) as its main build tool along with
+a tool called [GN](https://gn.googlesource.com/gn/+/master/docs/quick_start.md)
+to generate `.ninja` files. You can create any number of *build directories*
+with different configurations. To create a build directory, run:
+
+```shell
+$ gn gen out/fuchsia --args="is_debug=false dcheck_always_on=true is_component_build=false target_os=\"fuchsia\""
+```
+
+You can also build for Debug, with `is_debug=true`, but since we don't currently
+have any Debug build-bots, it may be more broken than Release.
+
+`use_goma=true` is fine to use also if you're a Googler.
+
+Architecture options are x64 (default) and arm64. This can be set with
+`target_cpu=\"arm64\"`.
+
+## Build
+
+All targets included in the GN build should build successfully. You can also
+build a specific binary, for example, base\_unittests:
+
+```shell
+$ autoninja -C out/fuchsia base_unittests
+```
+
+(`autoninja` is a wrapper that automatically provides optimal values for the
+arguments passed to `ninja`.)
+
+## Run
+
+Once you've built a package, you'll want to run it!
+
+### (Recommended)(Linux-only) Enable KVM acceleration
+
+Under Linux, if your host and target CPU architectures are the same (e.g. you're
+building for Fuchsia/x64 on a Linux/x64 host) then you can benefit from QEMU's
+support for the KVM hypervisor:
+
+1. Install the KVM module for your kernel, to get a /dev/kvm device.
+2. Ensure that your system has a "kvm" group, and it owns /dev/kvm.
+You can do that by installing the QEMU system common package:
+```shell
+$ sudo apt-get install qemu-system-common
+```
+3. Add users to the "kvm" group, and have them login again, to pick-up the new
+group.
+```shell
+$ sudo adduser <user> kvm
+$ exit
+[log in again]
+```
+
+### Running test suites
+
+There are three types of tests available to run on Fuchsia:
+
+1. [Gtests](gtests.md)
+2. [GPU integration tests](gpu_testing.md)
+3. [Blink tests](web_tests.md)
+
+Check the documentations to learn more about how to run these tests.
diff --git a/docs/fuchsia/debug_instructions.md b/docs/fuchsia/debug_instructions.md
new file mode 100644
index 0000000..264332b
--- /dev/null
+++ b/docs/fuchsia/debug_instructions.md
@@ -0,0 +1,49 @@
+# Debugging
+
+It is possible to debug Fuchsia binaries using `zxdb`. For the sake of this
+example, we will be using `base_unittests` as the test suite we wish to execute:
+
+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.
\ No newline at end of file
diff --git a/docs/fuchsia/gpu_testing.md b/docs/fuchsia/gpu_testing.md
new file mode 100644
index 0000000..a5bcbf3
--- /dev/null
+++ b/docs/fuchsia/gpu_testing.md
@@ -0,0 +1,45 @@
+# Running GPU integration tests on Fuchsia.
+
+General instruction on running and debugging GPU integration tests can be
+found [here](../gpu/gpu_testing.md).
+
+Fuchsia uses [web_engine_shell](../../fuchsia/engine/test/README.md) to run GPU
+integration tests. For the sake of this example, we will be using `gpu_process`
+as the test suite we wish to execute. Build the target
+`fuchsia_telemetry_gpu_integration_test` and run the appropriate commands:
+
+## Hermetic emulation
+
+The test script brings up an emulator, runs the tests on it, and shuts the
+emulator down when finished.
+
+```bash
+$ content/test/gpu/run_gpu_integration_test_fuchsia.py gpu_process
+--browser=web-engine-shell --out-dir=/path/to/outdir
+```
+
+## Run on an physical device
+
+```bash
+$ content/test/gpu/run_gpu_integration_test_fuchsia.py gpu_process
+--browser=web-engine-shell --out-dir=/path/to/outdir -d
+```
+
+## Run on a device paved with Fuchsia built from source
+
+```bash
+$ content/test/gpu/run_gpu_integration_test_fuchsia.py gpu_process
+--browser=web-engine-shell --out-dir=/path/to/outdir -d
+--fuchsia-out-dir=/path/to/fuchsia/outdir
+```
+
+## Run on a device the host is connected to remotely via ssh
+
+Note the `--ssh-config` flag, which should point to the config file used to set
+up the connection between the host and the remote device.
+
+```bash
+$ content/test/gpu/run_gpu_integration_test_fuchsia.py gpu_process
+--browser=web-engine-shell --out-dir=/path/to/outdir -d --host=localhost
+--ssh-config=/path/to/ssh/config
+```
\ No newline at end of file
diff --git a/docs/fuchsia/gtests.md b/docs/fuchsia/gtests.md
new file mode 100644
index 0000000..aacb9823
--- /dev/null
+++ b/docs/fuchsia/gtests.md
@@ -0,0 +1,97 @@
+# Deploying and running gtests on Fuchsia.
+
+Fuchsia gtest binaries are deployed and executed via scripts that are
+automatically generated by the `fuchsia_package_runner()` GN target.
+The binaries can deploy to either emulators started by the runner script,
+an existing emulator instance, or a physical device. To build a gtest binary,
+check this [documentation](build_instructions.md).
+
+For the sake of this example, we will be using `base_unittests` as the package
+we wish to install and/or execute.
+
+## Hermetic emulation
+
+The test script brings up an emulator, runs the tests on it, and
+shuts the emulator down when finished.
+```bash
+$ out/fuchsia/bin/run_base_unittests
+```
+
+## Run on an physical device
+
+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
+
+Make sure that the CPU architecture of your Chromium output directory matches
+the architecture of the Fuchsia output directory (x64==x64, arm64==arm64, etc.).
+
+```bash
+$ out/fuchsia/bin/run_base_unittests -d
+--fuchsia-out-dir=/path/to/fuchsia/outdir
+```
+
+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
+```
+
+## 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
+```
+
+## Run on a device the host is connected to remotely via ssh
+
+Note the `--ssh-config` flag, which should point to the config file used to set
+up the connection between the host and the remote device.
+
+```bash
+$ out/fuchsia/bin/run_base_unittests -d
+--host=localhost --ssh-config=/path/to/ssh/config
+```
+
+## Troubleshooting a test
+
+To troubleshoot a specific test, consider a combination of the following
+arguments to the test runner script:
+
+* `--gtest_filter="[TestSuite.TestName]"` to only run a specific test, or a
+ comma-separated list to run a set of tests. Wildcards can also be used to run
+ a set of tests or an entire test suite, e.g. `--gtest_filter="[TestSuite.*]"`.
+* `--test-launcher-jobs=1` to only have one batch of tests running at a time.
+ This bypasses the test launcher buffering of test log output, making it
+ possible to access the log output from successful test runs.
+* `--single-process-tests` to run all the tests in the same process. Unlike the
+ above option, this will run the tests directly in the test launcher process,
+ making it easier to attach a debugger.
+* `system-log-file=[/path/to/syslog]` to specify the file to write system logs
+ to. Or `system-log-file=-` to write the system logs to stdout. By default,
+ Chromium logs are written to the system log on Fuchsia. This argument is known
+ to cause `IOError` python exceptions with a QEMU target.
+* `--gtest_repeat=[number] --gtest_break_on_failure` to run a test or test suite
+ a certain number of times until it fails. This is useful to investigate flaky
+ tests.
\ No newline at end of file
diff --git a/docs/fuchsia/sdk_updates.md b/docs/fuchsia/sdk_updates.md
new file mode 100644
index 0000000..6fb5530
--- /dev/null
+++ b/docs/fuchsia/sdk_updates.md
@@ -0,0 +1,39 @@
+# Manually updating Chromium to a new Fuchsia SDK
+
+Normally the Fuchsia SDK dependency is automatically updated to a recent build
+on a regular basis, by the [Fuchsia SDK AutoRoll Bot](https://fuchsia-sdk-chromium-roll.skia.org).
+
+Should you need to manually update the SDK dependency for some reason, then:
+
+1. Check the [Fuchsia-side
+ job](https://luci-scheduler.appspot.com/jobs/fuchsia/sdk-topaz-x64-linux)
+ for a recent green archive. On the "SUCCEEDED" link, copy the SHA-1 from the
+ `gsutil.upload` link of the `upload fuchsia-sdk` step.
+0. Put that into Chromium's src.git `build/fuchsia/linux.sdk.sha1`.
+0. `gclient sync && ninja ...` and make sure things go OK locally.
+0. Upload the roll CL, making sure to include the `fuchsia` trybot. Tag the roll
+ with `Bug: 707030`.
+
+If you would like to build an SDK locally, `tools/fuchsia/local-sdk.py` tries to
+do this (so you can iterate on ToT Fuchsia against your Chromium build), however
+it's simply a copy of the steps run on the bot above, and so may be out of date.
+
+In order to sync a Fuchsia tree to the state matching an SDK hash, you can use:
+
+`jiri update https://storage.googleapis.com/fuchsia-snapshots/<SDK_HASH_HERE>`
+
+If you are waiting for a Zircon CL to roll into the SDK, you can check the
+status of the [Zircon
+roller](https://luci-scheduler.appspot.com/jobs/fuchsia/zircon-roller).
+Checking the bot's [list of
+CLs](https://fuchsia-review.googlesource.com/q/owner:zircon-roller%40fuchsia-infra.iam.gserviceaccount.com)
+might be useful too.
+
+Another useful command, if the SDK was pulled by `cipd` (which it is in
+Chromium-related projects like Crashpad, instead of directly pulling the
+.tar.gz), is:
+
+`cipd describe fuchsia/sdk/linux-amd64 -version <CIPD_HASH_HERE>`
+
+This description will show the `jiri_snapshot` "tag" for the CIPD package which
+corresponds to the SDK revision that's specified in `linux.sdk.sha1` here.
diff --git a/docs/fuchsia/web_tests.md b/docs/fuchsia/web_tests.md
new file mode 100644
index 0000000..6c573b2
--- /dev/null
+++ b/docs/fuchsia/web_tests.md
@@ -0,0 +1,28 @@
+# Deploying content_shell and running web_tests on Fuchsia.
+
+General instruction on running and debugging web_tests can be found
+[here](../testing/web_tests.md).
+
+Currently, only
+[a small subset of web tests](../../third_party/blink/web_tests/SmokeTests)
+can be run on Fuchsia. Build the target `blink_tests` first before running any
+of the commands below:
+
+## Hermetic emulation
+
+The test script brings up an emulator, runs the tests on it, and shuts the
+emulator down when finished.
+```bash
+$ third_party/blink/tools/run_web_tests.py -t <output-dir> --platform=fuchsia
+```
+
+## Run on an physical device.
+
+Note the `--fuchsia-host-ip` flag, which is the ip address of the test host that
+the Fuchsia device uses to establish a connection.
+
+```bash
+$ third_party/blink/tools/run_web_tests.py -t <output-dir> --platform=fuchsia
+--device=device --fuchsia-target-cpu=<device-cpu-arch>
+--fuchsia-out-dir=/path/to/fuchsia/outdir --fuchsia-host-ip=test.host.ip.address
+```
\ No newline at end of file
