fix included examples and markdown(book) (#912)

* fix included examples and markdown(book)

fixes: #911

* fix footnote pre_init

* more example link updates

* Restore pool example name

* Example: pool: Upgrade to heapless v0.8

* Example: pool: thumbv6 unsupported: wild cfg-if

Experiment with multi-backend example contained in the example

* Example: lm3s6965: Updated cargo.lock

* Book: Use cargo xtask for by-example

* Docs: Contributing: cargo xtask

---------

Co-authored-by: Henrik Tjäder <henrik@tjaders.com>

1 files changed, 75 insertions, 14 deletions

diff --git a/book/en/src/by-example.md b/book/en/src/by-example.md
index e5cf67a..4d3f537 100644
--- a/book/en/src/by-example.md
+++ b/book/en/src/by-example.md
@@ -2,8 +2,8 @@
 
 This part of the book introduces the RTIC framework to new users by walking them through examples of increasing complexity.
 
-All examples in this part of the book are accessible at the
-[GitHub repository][repoexamples].
+All examples in this part of the book are part of the
+[RTIC repository][repoexamples], found in the `examples` directory.
 The examples are runnable on QEMU (emulating a Cortex M3 target),
 thus no special hardware required to follow along.
 
@@ -17,24 +17,85 @@ embedded development environment that includes QEMU.
 
 [the embedded Rust book]: https://rust-embedded.github.io/book/intro/install.html
 
-To run the examples found in `examples/` locally, cargo needs a supported `target` and
-either `--examples` (run all examples) or `--example NAME` to run a specific example.
+To run the examples found in `examples/` locally using QEMU:
+
+```
+cargo xtask qemu
+```
+
+This runs all of the examples against the default `thumbv7m-none-eabi` device `lm3s6965`.
+
+To limit which examples are being run, use the flag `--example <example name>`, the name being the filename of the example.
 
 Assuming dependencies in place, running:
 
-``` console
-$ cargo run --target thumbv7m-none-eabi --example locals
+```console
+$ cargo xtask qemu --example locals
 ```
 
 Yields this output:
 
-``` console
-{{#include ../../../rtic/ci/expected/locals.run}}
+```console
+   Finished dev [unoptimized + debuginfo] target(s) in 0.07s
+    Running `target/debug/xtask qemu --example locals`
+INFO  xtask > Testing for platform: Lm3s6965, backend: Thumbv7
+INFO  xtask::run > 👟 Build example locals (thumbv7m-none-eabi, release, "test-critical-section,thumbv7-backend", in examples/lm3s6965)
+INFO  xtask::run > ✅ Success.
+INFO  xtask::run > 👟 Run example locals in QEMU (thumbv7m-none-eabi, release, "test-critical-section,thumbv7-backend", in examples/lm3s6965)
+INFO  xtask::run > ✅ Success.
+INFO  xtask::results > ✅ Success: Build example locals (thumbv7m-none-eabi, release, "test-critical-section,thumbv7-backend", in examples/lm3s6965)
+INFO  xtask::results > ✅ Success: Run example locals in QEMU (thumbv7m-none-eabi, release, "test-critical-section,thumbv7-backend", in examples/lm3s6965)
+INFO  xtask::results > 🚀🚀🚀 All tasks succeeded 🚀🚀🚀
+```
+
+It is great that examples are passing and this is part of the RTIC CI setup too, but for the purposes of this book we must add the `--verbose` flag, or `-v` for short to see the actual program output:
+
+```console
+❯ cargo xtask qemu --verbose --example locals
+    Finished dev [unoptimized + debuginfo] target(s) in 0.03s
+     Running `target/debug/xtask qemu --example locals --verbose`
+ DEBUG xtask > Stderr of child processes is inherited: false
+ DEBUG xtask > Partial features: false
+ INFO  xtask > Testing for platform: Lm3s6965, backend: Thumbv7
+ INFO  xtask::run > 👟 Build example locals (thumbv7m-none-eabi, release, "test-critical-section,thumbv7-backend", in examples/lm3s6965)
+ INFO  xtask::run > ✅ Success.
+ INFO  xtask::run > 👟 Run example locals in QEMU (thumbv7m-none-eabi, release, "test-critical-section,thumbv7-backend", in examples/lm3s6965)
+ INFO  xtask::run > ✅ Success.
+ INFO  xtask::results > ✅ Success: Build example locals (thumbv7m-none-eabi, release, "test-critical-section,thumbv7-backend", in examples/lm3s6965)
+    cd examples/lm3s6965 && cargo build --target thumbv7m-none-eabi --features test-critical-section,thumbv7-backend --release --example locals
+ DEBUG xtask::results >
+cd examples/lm3s6965 && cargo build --target thumbv7m-none-eabi --features test-critical-section,thumbv7-backend --release --example locals
+Stderr:
+    Finished release [optimized] target(s) in 0.02s
+ INFO  xtask::results > ✅ Success: Run example locals in QEMU (thumbv7m-none-eabi, release, "test-critical-section,thumbv7-backend", in examples/lm3s6965)
+    cd examples/lm3s6965 && cargo run --target thumbv7m-none-eabi --features test-critical-section,thumbv7-backend --release --example locals
+ DEBUG xtask::results >
+cd examples/lm3s6965 && cargo run --target thumbv7m-none-eabi --features test-critical-section,thumbv7-backend --release --example locals
+Stdout:
+bar: local_to_bar = 1
+foo: local_to_foo = 1
+idle: local_to_idle = 1
+
+Stderr:
+    Finished release [optimized] target(s) in 0.02s
+     Running `qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel target/thumbv7m-none-eabi/release/examples/locals`
+Timer with period zero, disabling
+
+ INFO  xtask::results > 🚀🚀🚀 All tasks succeeded 🚀🚀🚀
+```
+
+Look for the content following `Stdout:` towards the end ouf the output, the program output should have these lines:
+
+```console
+{{#include ../../../ci/expected/lm3s6965/locals.run}}
 ```
 
-> **NOTE**: You can choose target device by passing a target
-> triple to cargo (e.g. `cargo run --example init --target thumbv7m-none-eabi`) or
-> configure a default target in `.cargo/config.toml`.
->
-> For running the examples, we (typically) use a Cortex M3 emulated in QEMU, so the target is `thumbv7m-none-eabi`.
-> Since the M3 architecture is backwards compatible to the M0/M0+ architecture, you may also use the `thumbv6m-none-eabi`, in case you want to inspect generated assembly code for the M0/M0+ architecture.
+> **NOTE**: 
+> For other useful options to `cargo xtask`, see:
+> ```
+> cargo xtask qemu --help
+> ```
+> 
+> The `--platform` flag allows changing which device examples are run on,
+> currently `lm3s6965` is the best supported, work is ongoing to 
+> increase support for other devices, including both ARM and RISC-V