diff --git a/build_system.md b/build_system.md
index b37e6c69da60ebe485f73fa95db6b8f5ef762958..543542e6df8d1b39506f0dab4c8e2507336eb2a9 100644
--- a/build_system.md
+++ b/build_system.md
@@ -1,19 +1,21 @@
-
# Fuchsia Build Notes
-You should probably use the [standard build instructions](https://fuchsia.googlesource.com/fuchsia/+/HEAD/README.md) instead of using the instructions here.
+These are notes on using the `gen.py` script and `ninja` directly for builds,
+and the `scripts/run-magenta-*` scripts to launch QEMU.
-These are notes on using the `gen.py` script and `ninja` directly for builds, and the `scripts/run-magenta-*` scripts to launch QEMU. The functions in `env.sh` should cover all the functionality described here and use these commands under-the-hood.
+You can alternatively use the [standard build instructions](getting_started.md)
+using commands defined in `env.sh` instead.
### Build Magenta and the sysroot
-First, you need to [build the Magenta kernel](https://fuchsia.googlesource.com/magenta/+/HEAD/docs/getting_started.md) and the sysroot:
+First, you need to [build the Magenta kernel](magenta) and the sysroot:
```
(cd magenta; make -j32 magenta-pc-x86-64)
./scripts/build-sysroot.sh
```
-### Building Fuchsia
+
+### Build Fuchsia
Build Fuchsia using these commands:
@@ -31,8 +33,8 @@ for faster builds:
./buildtools/ninja -C out/debug-x86-64
```
-[Googlers only] If you have goma installed, prefer goma over ccache and use these
-alternative commands for faster builds:
+[Googlers only] If you have goma installed, prefer goma over ccache and use
+these alternative commands for faster builds:
```
./packages/gn/gen.py --goma
@@ -53,13 +55,16 @@ argument. After running `gen.py` once, you can do incremental builds using
### Running Fuchsia
-These commands will create an `out/debug-{arch}/user.bootfs` file. To run the
-system with this filesystem attached in QEMU, pass the user.bootfs path as the
-value of the '-x' parameter in Magenta's start command script, for example:
+The commands above create an `out/debug-{arch}/user.bootfs` file. To run the
+system with this filesystem attached in QEMU, pass the path to user.bootfs as
+the value of the `-x` parameter in Magenta's start command script, for example:
```
./scripts/run-magenta-x86-64 -x out/debug-x86-64/user.bootfs -m 2048
./scripts/run-magenta-arm64 -x out/debug-aarch64/user.bootfs -m 2048
```
-See the [standard build instructions](https://fuchsia.googlesource.com/fuchsia/+/HEAD/README.md) for other flags you can pass to QEMU.
+See the [standard build instructions](getting_started.md) for other flags you
+can pass to QEMU.
+
+[magenta]: https://fuchsia.googlesource.com/magenta/+/HEAD/docs/getting_started.md "Magenta"
diff --git a/getting_started.md b/getting_started.md
index 63ebe47a8982fe8ff7641993e66c235899ea4f1b..cf132399893fdca169f03463b72696a8c079288d 100644
--- a/getting_started.md
+++ b/getting_started.md
@@ -15,7 +15,12 @@ Get the Fuchsia source by following these two steps and then return to this docu
### Magenta Prerequisites
-The Fuchsia source includes [Magenta](https://fuchsia.googlesource.com/magenta), the core platform which underpins Fuchsia. Follow this step to install the Magenta build prerequisites and then return to this document. (You can ignore the toolchain installation instructions unless you want to build your own; the Fuchsia manifest will automatically obtain a prebuilt toolchain.)
+The Fuchsia source
+includes [Magenta](https://fuchsia.googlesource.com/magenta/+/HEAD/README.md),
+the core platform which underpins Fuchsia. Follow this step to install the
+Magenta build prerequisites and then return to this document. (You can ignore
+the toolchain installation instructions unless you want to build your own; the
+Fuchsia manifest will automatically obtain a prebuilt toolchain.)
* [Preparing the Magenta build environment](https://fuchsia.googlesource.com/magenta/+/master/docs/getting_started.md#Preparing-the-build-environment).
@@ -24,17 +29,25 @@ The Fuchsia source includes [Magenta](https://fuchsia.googlesource.com/magenta)
Ensure `goma` is installed on your machine for faster builds.
## Build Fuchsia
+
### Setup Build Environment
-Source the `env.sh` script, which provides helpful shell functions for Fuchsia development. The following command also changes the command prompt and sets up for a x86-64 build.
+Source the [`env.sh`](scripts/env.sh) script, which provides helpful shell
+functions for Fuchsia development. The following command also changes the
+command prompt and sets up for a x86-64 build.
```
source scripts/env.sh && envprompt && fset x86-64
```
-Run `envhelp` to see other useful shell functions, and `envhelp <function>` for specific usage information.
+Alternatively, you may [use the underlying build scripts](build_system.md).
+
+Run `envhelp` to see other useful shell functions, and `envhelp <function>` for
+specific usage information.
-[optional] You might find it useful to add a shell function `fuchsia` as a shortcut to setup the build environment. For that, add this your shell startup script (e.g. `~/.bashrc`):
+Optionally, you might find it useful to add a shell function `fuchsia` as a
+shortcut to setup the build environment. For that, add this your shell startup
+script (e.g. `~/.bashrc`):
```
export FUCHSIA_ROOT=/path/to/my/fuchsia/source
@@ -43,12 +56,14 @@ function fuchsia() {
}
```
-
### [optional] Customize Build Environment
-By default you will get a x86-64 debug build, and you can skip this step unless you want something else.
+By default you will get a x86-64 debug build, and you can skip this step unless
+you want something else.
-[Googlers only: If you have `goma` installed, it will also be used by default. Prefer `goma` over `ccache`]
+[Googlers only: If you have `goma` installed, it will also be used by default.
+Prefer `goma` over `ccache`. Note: to use `ccache` or `goma` you must install
+them first.]
Run `fset-usage` to see a list of build options. Some examples:
@@ -59,22 +74,23 @@ fset x86-64 --release # x86-64 release build, no goma, no ccache
fset x86-64 --ccache # x86-64 debug build, ccache enabled
```
-Note: to use `ccache` or `goma` you must install them first.
-
### Build Fuchsia
Once you have setup your build environment, simply run:
+
```
fbuild
```
This builds Magenta, the sysroot, and the default Fuchsia build.
-After Fuchsia is built, you will have a Magenta (`magenta.bin`) image and a `user.bootfs` file in `out/debug-{arch}/`.
+After Fuchsia is built, you will have a Magenta (`magenta.bin`) image and a
+`user.bootfs` file in `out/debug-{arch}/`.
### Run Fuchsia in QEMU
-You can run Fuchsia under emulation using [QEMU](https://fuchsia.googlesource.com/magenta/+/HEAD/docs/qemu.md).
+You can run Fuchsia under emulation
+using [QEMU](https://fuchsia.googlesource.com/magenta/+/HEAD/docs/qemu.md).
Fuchsia includes prebuilt binaries for QEMU under `buildtools/qemu`.
The `frun` command will launch Magenta within QEMU, using the locally built
@@ -84,10 +100,12 @@ The `frun` command will launch Magenta within QEMU, using the locally built
frun
```
-There are various flags for `frun` to control QEMU's configuration. The `-m`
-flag sets QEMU's memory size in MB, while `-g` and `-N` enable graphics and
-networking, respectively (see below). Use `frun -h` to see all available
-options.
+There are various flags for `frun` to control QEMU's configuration:
+* `-m` sets QEMU's memory size in MB.
+* `-g` enables graphics (see below).
+* `-N` enables networking (see below).
+
+Use `frun -h` to see all available options.
When Fuchsia has booted and started an MXCONSOLE, you can run programs!
@@ -99,8 +117,8 @@ fortune
#### Working with Fuchsia system components
-The `bootstrap` utility sets up the environment and system services required
-to use and develop Fuchsia applications. You can run individual Fuchsia
+The `bootstrap` utility sets up the environment and system services required to
+use and develop Fuchsia applications. You can run individual Fuchsia
applications invoking their url:
@ bootstrap [args...] <app url> <app args...>
@@ -114,7 +132,8 @@ environment by specifying the `boot` scope:
@boot <app url> <app args...>
-More information on bootstrap and its uses can be found [here](https://fuchsia.googlesource.com/modular/+/HEAD/src/bootstrap/)
+More information on bootstrap and its uses can be
+found [here](https://fuchsia.googlesource.com/modular/+/HEAD/src/bootstrap/).
#### Enabling Graphics
@@ -124,8 +143,9 @@ To enable graphics, add the `-g` flag to `frun`:
frun -g
```
-Run graphical applications (using [mozart](https://fuchsia.googlesource.com/mozart))
-in `/system/apps` like this:
+Run graphical applications
+using [mozart](https://fuchsia.googlesource.com/mozart) in `/system/apps` like
+this:
```
@ bootstrap launch spinning_square_view
@@ -137,15 +157,18 @@ Some more mozart example apps are [here](https://fuchsia.googlesource.com/mozart
Note: Networking support within QEMU is only available under x86_64.
-First, [configure](https://fuchsia.googlesource.com/magenta/+/master/docs/qemu.md#Enabling-Networking-under-Qemu-x86_64-only)
+First, [configure](https://fuchsia.googlesource.com/magenta/+/master/docs/qemu.md#Enabling-Networking-under-QEMU-x86_64-only)
a virtual interface for QEMU's use.
-Once this is done you can add the -N flag to `frun`:
+Once this is done you can add the -N and -u flags to `frun`:
```
-frun -N
+frun -N -u $FUCHSIA_SCRIPTS_DIR/start-dhcp-server.sh
```
+The `-u` flag runs a script that sets up a local DHCP server and NAT to
+configure the IPv4 interface and routing.
+
### Run Fuchsia on hardware
* [Acer Switch Alpha 12](https://fuchsia.googlesource.com/magenta/+/master/docs/targets/acer12.md)
@@ -154,7 +177,6 @@ frun -N
## Additional helpful documents
-
* [Fuchsia documentation](https://fuchsia.googlesource.com/docs) hub.
* [Contributing changes](https://fuchsia.googlesource.com/manifest/+/HEAD/README.md#Submitting-changes).
-* More about the [build commands](https://fuchsia.googlesource.com/docs/+/master/build_system.md) called under-the-hood by `fbuild`.
+* More about the [build commands](build_system.md) called under-the-hood by `fbuild`.