Update qemu.md project-creation section to reference app-template - #418
Open
mehmethekim wants to merge 1 commit into
Open
Update qemu.md project-creation section to reference app-template#418mehmethekim wants to merge 1 commit into
mehmethekim wants to merge 1 commit into
Conversation
cortex-m-quickstart was deprecated and emptied by its author (see rust-embedded#396). The cargo-generate command in this section already pointed at app-template, but the surrounding prose and the git-clone/zip-download alternatives still referenced the now-archived cortex-m-quickstart repo, whose git history was wiped down to a README.
mehmethekim
force-pushed
the
fix/qemu-app-template-refs
branch
from
August 17, 2026 11:19
f31d86a to
1d5df48
Compare
webbgamers
added a commit
to webbgamers/book
that referenced
this pull request
Sep 1, 2026
The `cargo-generate` command in this chapter switched to knurling's `app-template` (and rust-embedded#418 updates the surrounding project-creation prose to match), but everything downstream of project creation still describes `cortex-m-quickstart` and the pre-`defmt` `hprintln!` workflow. Following the chapter as written does not currently produce a running program. Program Overview: show `src/bin/hello.rs` rather than a `src/main.rs` that the template does not have, and explain `use app as _;` instead of `panic_halt`. Cross compiling: the template defaults to `thumbv6m-none-eabi`, so add the missing step of switching TODO(3) to `thumbv7m-none-eabi`. The listing shown before was quickstart's, which had the Cortex-M3 target already selected. Inspecting: the template builds no binary named after the project, so `cargo readobj --bin app` fails; use `--bin hello`. Refresh the captured output and document the `.defmt` and `.uninit` sections and flip-link's inverted RAM layout, which is what readers will actually see. Running: plain `qemu-system-arm` cannot decode `defmt`, as the chapter itself says two paragraphs earlier, so it can't be the runner and doesn't print "Hello, world!" -- it prints four bytes of binary frame. Set `qemu-run` as the runner instead, under the cfg() table the template actually uses. Install `qemu-run` from crates.io rather than cloning the `defmt` repo; the clone snippet also used an SSH URL and a `../qemu-rs/` path that does not exist. Fix `--example hello` to `--bin hello`. Debugging: pass the GDB flags through `qemu-run` so the log output is still decoded, correct the `examples/hello` paths, and replace the `hprintln!` / `debug::exit` listing with the program the template ships. `cortex-m-rt` writes Reset in assembly now, so GDB stops at a bare address with a misattributed symbol rather than at `cortex-m-rt-0.6.1/src/lib.rs:473`. install/tooling: add `flip-link`, which the template sets as its linker and without which the build fails, and `qemu-run`. Neither was mentioned anywhere. All commands and output were re-run against a fresh `app-template` project. Semihosting, Panicking and Exceptions still print with `hprintln!`, and `qemu-run` swallows that plain text silently rather than erroring, so the chapter now tells readers to switch the runner back to plain `qemu-system-arm` before those chapters. Migrating them to `defmt` would remove the caveat and is probably worth doing, but is left out of this change.
webbgamers
added a commit
to webbgamers/book
that referenced
this pull request
Sep 1, 2026
The `cargo-generate` command in this chapter switched to knurling's `app-template` (and rust-embedded#418 updates the surrounding project-creation prose to match), but everything downstream of project creation still describes `cortex-m-quickstart` and the pre-`defmt` `hprintln!` workflow. Following the chapter as written does not currently produce a running program. Program Overview: show `src/bin/hello.rs` rather than a `src/main.rs` that the template does not have, and explain `use app as _;` instead of `panic_halt`. Cross compiling: the template defaults to `thumbv6m-none-eabi`, so add the missing step of switching TODO(3) to `thumbv7m-none-eabi`. The listing shown before was quickstart's, which had the Cortex-M3 target already selected. Inspecting: the template builds no binary named after the project, so `cargo readobj --bin app` fails; use `--bin hello`. Refresh the captured output and document the `.defmt` and `.uninit` sections and flip-link's inverted RAM layout, which is what readers will actually see. Running: plain `qemu-system-arm` cannot decode `defmt`, as the chapter itself says two paragraphs earlier, so it can't be the runner and doesn't print "Hello, world!" -- it prints four bytes of binary frame. Set `qemu-run` as the runner instead, under the cfg() table the template actually uses. Install `qemu-run` from crates.io rather than cloning the `defmt` repo; the clone snippet also used an SSH URL and a `../qemu-rs/` path that does not exist. Fix `--example hello` to `--bin hello`. Debugging: pass the GDB flags through `qemu-run` so the log output is still decoded, correct the `examples/hello` paths, and replace the `hprintln!` / `debug::exit` listing with the program the template ships. `cortex-m-rt` writes Reset in assembly now, so GDB stops at a bare address with a misattributed symbol rather than at `cortex-m-rt-0.6.1/src/lib.rs:473`. install/tooling: add `flip-link`, which the template sets as its linker and without which the build fails, and `qemu-run`. Neither was mentioned anywhere. All commands and output were re-run against a fresh `app-template` project. Semihosting, Panicking and Exceptions still print with `hprintln!`, and `qemu-run` swallows that plain text silently rather than erroring, so the chapter now tells readers to switch the runner back to plain `qemu-system-arm` before those chapters. Migrating them to `defmt` would remove the caveat and is probably worth doing, but is left out of this change. The `entry` link also now points at `cortex-m-rt`'s re-export rather than the `cortex-m-rt-macros` page, which carries no documentation of its own.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
cortex-m-quickstartwas deprecated and emptied by its author (see #396).The repo's git history was wiped down to a README pointing users at
app-templateinstead.#403 already updated the "Running" section of this chapter to use
app-template'sdefmt/qemu-runworkflow, and thecargo-generatecommand in "Creating a non standard Rust program" already pointed at
app-template. But the surrounding prose and the two alternativeinstall methods were never updated:
cortex-m-quickstartproject template..." and referred to an
examplesdirectory (app-templateuses
src/bin).git" clonedrust-embedded/cortex-m-quickstart, which nowcontains only a README.
This is a partial fix for #396.