From 8f5805551f4d8db26e8f5911bd91c3c3596714a8 Mon Sep 17 00:00:00 2001
From: Kris Giesing <kgiesing@google.com>
Date: Mon, 3 Sep 2018 18:23:00 -0700
Subject: [PATCH] [docs] Consolidate build and pave workflow documentation
Refactor the documentation on building and paving to put the basic
workflow in a separate quickstart doc. Rename the full
paving workflow doc to better match its location in the docs.
Rewrite clients to point to either the full doc or the quickstart,
depending on context.
Also, pull the Google-specific setup instructions out of the
getting started guide, since those instructions are already
captured in Google-internal documentation.
Test: Verbal discussion
Change-Id: I24401c01e5a9e95978e9fb17a8c3d93ddc2121d1
---
.../workflows/build_and_pave_quickstart.md | 63 +++++++++++++++++++
development/workflows/package_update.md | 2 +-
.../workflows/{fuchsia_paver.md => paving.md} | 21 +------
getting_started.md | 22 ++-----
glossary.md | 2 +-
5 files changed, 74 insertions(+), 36 deletions(-)
create mode 100644 development/workflows/build_and_pave_quickstart.md
rename development/workflows/{fuchsia_paver.md => paving.md} (88%)
diff --git a/development/workflows/build_and_pave_quickstart.md b/development/workflows/build_and_pave_quickstart.md
new file mode 100644
index 00000000000..816cc804c43
--- /dev/null
+++ b/development/workflows/build_and_pave_quickstart.md
@@ -0,0 +1,63 @@
+# Build and Pave Quickstart
+
+This document captures the common-case workflow for building and deploying
+Fuchsia onto a device using `fx` development commands. Most such commands
+have options for less common situations; see `fx help <command>` for details.
+
+## Initial Build and Deploy
+
+The initial build and deploy workflow using `fx` is as follows:
+
+1. `fx set <arch>`
+ Configures the build for <arch>: one of [x64, arm64].
+1. `fx full-build`
+ Builds Zircon, then the rest of Fuchsia.
+1. `fx mkzedboot <usb_drive_device_path>`
+ Builds the Zedboot media and installs to the USB drive target. See below
+ for notes on obtaining the USB drive device path.
+1. `fx boot`
+ Starts the bootserver.
+1. Attach Zedboot USB to device and reboot.
+ Zedboot will connect to the host, download the pave image, and pave the
+ device.
+
+### USB drive device path
+
+Instructions for determining the correct path to your USB drive are as follows,
+depending on the host OS. In either case, you can run the command once with the
+USB drive disconnected, then run again with it connected, to see the
+difference.
+
+* Linux users:
+ - `sudo fdisk -l`
+ Drives are usually of the form /dev/sd[x], e.g. '/dev/sdc'. Select
+ the drive rather than a specific partition.
+* Mac users:
+ - `diskutil list | grep external`
+ Drives are usually of the form /dev/disk[n], e.g. '/dev/disk2'.
+ - If you see 'ERROR: Can't open /dev/disk[n]: Resource busy'
+ then you will have to unmount the usb drive.
+ For this run `hdiutil unmount /dev/disk[n]`.
+ If this does not fix the error, try reformating the drive:
+ `diskutil eraseDisk JHFSX <name_of_the_usb_stick> /dev/disk[n]`.
+
+## Subsequent Build and Deploy
+
+The workflow for re-building and re-deploying using `fx` is slightly different:
+
+1. Check the [build waterfall dashboard](https://fuchsia-dashboard.appspot.com/).
+ Helps ensure that HEAD is in a good state to pull.
+1. `jiri update`
+ Fetches the latest code.
+1. `fx full-build`
+ Builds Zircon, then the rest of Fuchsia.
+1. `fx serve`
+ Starts a development package server on the host.
+1. Boot the device *without* Zedboot USB attached.
+ Boots the device into its last-paved state.
+1. `fx ota`
+ Pushes updated packages to the device.
+
+NOTE: If desired, the device can be re-paved using Zedboot USB as per steps 4-5
+in the previous section. This is slower, but may be necessary in some cases
+where the system handles the OTA less than gracefully.
diff --git a/development/workflows/package_update.md b/development/workflows/package_update.md
index f43b9d6ea49..b2cda1478e9 100644
--- a/development/workflows/package_update.md
+++ b/development/workflows/package_update.md
@@ -150,5 +150,5 @@ root hash and put in a directory at the root of the TUF file tree called 'blobs'
[TUF-home]: https://theupdateframework.github.io "TUF Homepage"
[pkg-doc]: /development/build/packages.md "Packaging docs"
[flutter-gni]: https://fuchsia.googlesource.com/topaz/+/master/runtime/flutter_runner/flutter_app.gni "Flutter GN build template"
-[paver]: fuchsia_paver.md "Fuchsia paver"
+[paver]: paving.md "Fuchsia paver"
[OTA]: #triggering-an-ota "Triggering an OTA"
diff --git a/development/workflows/fuchsia_paver.md b/development/workflows/paving.md
similarity index 88%
rename from development/workflows/fuchsia_paver.md
rename to development/workflows/paving.md
index 79458934399..cbc40473d87 100644
--- a/development/workflows/fuchsia_paver.md
+++ b/development/workflows/paving.md
@@ -22,24 +22,9 @@ extend to allow you to build what you need.
## TL;DR
-Read this all before? Here are the common case commands
-1. `fx set x64`
-2. `fx full-build`
-3. Make the install media
- * [[ insert USB drive into host ]]
- * `fx mkzedboot <usb_drive_device_path>`
- * Mac users:
- - The USB drives connected to your computer can be found by running
- `diskutil list | grep external`.
- They are usually of the form /dev/disk[n], e.g. '/dev/disk2'.
- - If you see 'ERROR: Can't open /dev/disk[n]: Resource busy'
- then you will have to unmount the usb drive.
- For this run `hdiutil unmount /dev/disk[n]`.
- If this does not fix the error, try reformating the drive:
- `diskutil eraseDisk JHFSX <name_of_the_usb_stick> /dev/disk[n]`.
-4. Boot and pave
- * [[ move USB drive to target ]]
- * `fx boot <efi|vboot|nuc|cros|..>`
+Read this all before? See the
+[quickstart guide](https://fuchsia.googlesource.com/fuchsia/+/master/docs/development/workflows/build_and_pave_quickstart.md)
+for a workflow summary.
## Building
diff --git a/getting_started.md b/getting_started.md
index ad825431b0c..77271a4b66a 100644
--- a/getting_started.md
+++ b/getting_started.md
@@ -38,26 +38,14 @@ sudo apt-get install build-essential curl git python unzip
1. In addition to Command Line Tools, you also need to
install a recent version of [Xcode](https://developer.apple.com/xcode/).
-### [Googlers only] Goma
-
-Ensure `goma` is installed on your machine for faster builds.
-
-## Build Fuchsia
-
-### Get the source
+## Get the Source
Follow [the instructions to get the Fuchsia source](/development/source_code/README.md)
and then return to this document.
-### [Googlers only] CIPD auth-login
-
-Run
-```
-./buildtools/cipd auth-login
-jiri run-hooks # Re-run hooks now that you're logged in.
-```
+## Build Fuchsia
-You should only need to do this once per host.
+Note: A quick overview of the basic build-and-pave workflow can be found [here](/development/workflows/build_and_pave_quickstart.md).
### Build
@@ -116,7 +104,9 @@ To override the default behaviors, pass flags to `fx set`:
### Installing and booting from hardware
To get Fuchsia running on hardware requires using the paver, which these
-[instructions](/development/workflows/fuchsia_paver.md) will help you get up and running with.
+[instructions](/development/workflows/paving.md) will help you get up and running with.
+
+Note: A quick overview of the basic build-and-pave workflow can be found [here](/development/workflows/build_and_pave_quickstart.md).
### Boot from QEMU
diff --git a/glossary.md b/glossary.md
index ce641c907b7..87c87cd0007 100644
--- a/glossary.md
+++ b/glossary.md
@@ -257,7 +257,7 @@ Package is an overloaded term. Package may refer to a
#### **Paver**
A tool in Zircon that installs partition images to internal storage of a device.
-- [Guide for installing Fuchsia with paver](/development/workflows/fuchsia_paver.md).
+- [Guide for installing Fuchsia with paver](/development/workflows/paving.md).
#### **Peridot**
--
GitLab