From 1b5c292b0566d14c0daf1d1d60853f87a2edc2b2 Mon Sep 17 00:00:00 2001 From: bunnie Date: Tue, 18 Feb 2025 10:14:34 +0800 Subject: [PATCH] note requirement of --doc-deps to build documentation 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` --- README.md | 23 ++++++++++++++++------- RELEASE-v0.9.md | 8 +++++++- 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ba7598ef8..1a4779380 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,15 @@ from source. It consists of the following projects: - Some system packages are needed, which can be installed with `sudo apt install libssl-dev libxkbcommon-dev` or similar - If you receive an error about `feature resolver is required`, try installing a newer version of `rustc` and `cargo` via [rustup](https://rustup.rs) +## Building Documentation +A flag of `--feature doc-deps` must be passed when running `cargo doc`, like this: + +`cargo doc --no-deps --feature doc-deps` + +This flag is required because Xous requires a target board to be specified in +all build configurations. `doc-deps` specifies a set of dummy dependencies +that satisfy board requirements for the purpose of building documentation. + ## Local-vs-crates.io Verification By default the `xtask` resolver runs a check to confirm that your local files match the ones referenced in `crates.io`. For a handful of core crates, the @@ -59,13 +68,13 @@ will begin scrolling in your terminal. ### Hosted Mode UI navigation -| Precursor | Host | -| --------- | ---- | -| D-pad middle button | Home | -| D-pad up | up arrow | -| D-pad down | down arrow | -| D-pad left | left arrow | -| D-pad right | right arrow | +| Precursor | Host | +| ------------------- | ----------- | +| D-pad middle button | Home | +| D-pad up | up arrow | +| D-pad down | down arrow | +| D-pad left | left arrow | +| D-pad right | right arrow | ## Quickstart using an emulator diff --git a/RELEASE-v0.9.md b/RELEASE-v0.9.md index 833037231..174506d95 100644 --- a/RELEASE-v0.9.md +++ b/RELEASE-v0.9.md @@ -506,7 +506,13 @@ perform the Xous firmware upgrade. This requires running manual update commands, - Number of pages to allocate could be automated inside the `xous-ipc` crate, but this will be delegated to a future time with a new API. - Most applications were forward-ported, except for `app-loader` which has already bit-rotted for other reasons and may be deprecated because we can use "swap" space to effectively do app loading (to be made available in future hardware revs) - Serialization is a bit easier now with the new `rkyv`, we don't have to track a `pos` explicitly; all of the archival metadata is now stuck at the end of the archive, so all you need to know is the final length of the serialized record and you're done. - +- Refactor `blitstr2` to be in its own `libs` crate, allowing it to be re-used across multiple configurations +- Clean up the board vs soc abstraction. There are still places that don't adhere to this distinction, but: + - 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` ## Roadmap - Lots of testing and bug fixes