The hardware specification hierarchy is clarified to be as such:
- A `soc` flag specifies dependencies that are generic to a
system-on-chip (SoC). For example, the locations of registers, or
the extents of memory regions contained in the `soc`.
- A `board` flag specifies dependencies that are specific to a
board. For example, the resolution of displays, pin mappings to
peripherals, and sizes of external memory. Typically, a board
assumes a `soc`, so both a `board-*` and `*-soc` set of flags are
required to fully specify a build.
- Precursor (the first target for Xous) did not hold to this
abstraction and conflated the two, so it is a special case in the
build system.
- "Hosted" mode emulations are considered to be a `board` target; the
`soc` is assumed to be the host (linux, windows, etc.)
Since all builds require a `board` specifier, documentation now
requires a `doc-deps` flag to be passed. This effectively specifies a
set of dummy board dependencies so that the documentation can
build. Here is the recommended command line for building docs: `cargo
doc --no-deps --feature doc-deps`
Without these two packages, `cargo xtask run` failed for me on Debian 11 (bullseye).
The version of `cargo` and `rustc` provided by the apt package `rustc` also threw the error mentioned about `feature resolver is required`. With the install script from https://rustup.rs a much newer version was provided, `rustc 1.57.0 (f1edd0429 2021-11-29)`, compared to [`rustc (1.48.0+dfsg1-2`)](https://packages.debian.org/bullseye/rustc) provided by `apt install rustc`.
Signed-off-by: Lairs Johnstone <me@hkjn.me>
The `xtask` command has come a long way, and is the preferred method of
building this repositry. Document the fun ways it can be used.
Signed-off-by: Sean Cross <sean@xobs.io>
