diff --git a/.cargo/config.toml b/.cargo/config.toml index 24903bd..dc1475c 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -1,6 +1,5 @@ [target.'cfg(all(target_arch = "arm", target_os = "none"))'] -# TODO(2) replace `$CHIP` with your chip's name (see `probe-run --list-chips` output) -runner = "probe-run --chip $CHIP" +runner = "probe-run --chip {{chip}}" rustflags = [ "-C", "linker=flip-link", "-C", "link-arg=-Tlink.x", @@ -11,13 +10,7 @@ rustflags = [ ] [build] -# TODO(3) Adjust the compilation target. -# (`thumbv6m-*` is compatible with all ARM Cortex-M chips but using the right -# target improves performance) -target = "thumbv6m-none-eabi" # Cortex-M0 and Cortex-M0+ -# target = "thumbv7m-none-eabi" # Cortex-M3 -# target = "thumbv7em-none-eabi" # Cortex-M4 and Cortex-M7 (no FPU) -# target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU) +target = "{{ target | split(pat=' ') | first }}" [alias] rb = "run --bin" diff --git a/.genignore b/.genignore deleted file mode 100644 index 8d1e189..0000000 --- a/.genignore +++ /dev/null @@ -1 +0,0 @@ -.github/FUNDING.yml diff --git a/Cargo.toml b/Cargo.toml index 6c72b7d..893a12f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,6 @@ [package] -# TODO(1) fix `authors` and `name` if you didn't use `cargo-generate` authors = ["{{authors}}"] -name = "{{project-name}}" +name = "{{project_name}}" edition = "2018" version = "0.1.0" @@ -14,8 +13,9 @@ cortex-m-rt = "0.6.13" defmt = "0.1.2" defmt-rtt = "0.1.0" panic-probe = { version = "0.1.0", features = ["print-defmt"] } -# TODO(4) enter your HAL here -# some-hal = "1.2.3" +{% if use_hal == "yes" %} +{{hal_crate}}="{{hal_crate_version}}" +{% endif %} [features] # set logging levels here diff --git a/README.md b/README.md index df7cef6..9c51eaa 100644 --- a/README.md +++ b/README.md @@ -20,86 +20,28 @@ $ cargo install flip-link $ cargo install probe-run ``` -#### 3. [`cargo-generate`]: +#### 3. [`kickstart`]: ``` -$ cargo install cargo-generate +$ cargo install kickstart ``` -[`cargo-generate`]: https://crates.io/crates/cargo-generate +[`kickstart`]: https://github.com/Keats/kickstart -> *Note:* You can also just clone this repository instead of using `cargo-generate`, but this involves additional manual adjustments. +> *Note:* You can also just clone this repository instead of using `kickstart`, but this involves additional manual adjustments. ## Setup #### 1. Initialize the project template ``` console -$ cargo generate \ - --git https://github.com/knurling-rs/app-template \ - --branch main \ - --name my-app +$ kickstart https://github.com/knurling-rs/app-template ``` -If you look into your new `my-app` folder, you'll find that there are a few `TODO`s in the files marking the properties you need to set. +Answer the questions (or use defaults) to generate your project. -Let's walk through them together now. -#### 2. Set `probe-run` chip - -Pick a chip from `probe-run --list-chips` and enter it into `.cargo/config.toml`. - -If, for example, you have a nRF52840 Development Kit from one of [our workshops], replace `{{chip}}` with `nRF52840_xxAA`. - -[our workshops]: https://github.com/ferrous-systems/embedded-trainings-2020 - -``` diff - # .cargo/config.toml - [target.'cfg(all(target_arch = "arm", target_os = "none"))'] --runner = "probe-run --chip {{chip}} --defmt" -+runner = "probe-run --chip nRF52840_xxAA --defmt" -``` - -#### 3. Adjust the compilation target - -In `.cargo/config.toml`, pick the right compilation target for your board. - -``` diff - # .cargo/config.toml - [build] --target = "thumbv6m-none-eabi" # Cortex-M0 and Cortex-M0+ --# target = "thumbv7m-none-eabi" # Cortex-M3 --# target = "thumbv7em-none-eabi" # Cortex-M4 and Cortex-M7 (no FPU) --# target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU) -+target = "thumbv7em-none-eabihf" # Cortex-M4F (with FPU) -``` - -#### 4. Add a HAL as a dependency - -In `Cargo.toml`, list the Hardware Abstraction Layer (HAL) for your board as a dependency. - -For the nRF52840 you'll want to use the [`nrf52840-hal`]. - -[`nrf52840-hal`]: https://crates.io/crates/nrf52840-hal - -``` diff - # Cargo.toml - [dependencies] --# some-hal = "1.2.3" -+nrf52840-hal = "0.11.0" -``` - -#### 5. Import your HAL - -Now that you have selected a HAL, fix the HAL import in `src/lib.rs` - -``` diff - // my-app/src/lib.rs --// use some_hal as _; // memory layout -+use nrf52840_hal as _; // memory layout -``` - -#### (6. Get a linker script) +#### 2. Get a linker script Some HAL crates require that you manually copy over a file called `memory.x` from the HAL to the root of your project. For nrf52840-hal, this is done automatically so no action is needed. For other HAL crates, you can get it from your local Cargo folder, the default location is under: @@ -110,7 +52,7 @@ Some HAL crates require that you manually copy over a file called `memory.x` fro Not all HALs provide a memory.x file, you may need to write it yourself. Check the documentation for the HAL you are using. -#### 7. Run! +#### 3. Run! You are now all set to `cargo-run` your first `defmt`-powered application! There are some examples in the `src/bin` directory. diff --git a/cargo-generate.toml b/cargo-generate.toml deleted file mode 100644 index 0c72b6c..0000000 --- a/cargo-generate.toml +++ /dev/null @@ -1,2 +0,0 @@ -[template] -exclude = ["README.md"] diff --git a/src/bin/bitfield.rs b/src/bin/bitfield.rs index f82c2a2..9cb1574 100644 --- a/src/bin/bitfield.rs +++ b/src/bin/bitfield.rs @@ -1,7 +1,7 @@ #![no_main] #![no_std] -use {{crate_name}} as _; // global logger + panicking-behavior + memory layout +use {{ project_name | replace(from="-", to="_") }} as _; // global logger + panicking-behavior + memory layout #[cortex_m_rt::entry] fn main() -> ! { @@ -9,5 +9,5 @@ fn main() -> ! { let frequency: u32 = 276; defmt::debug!("FREQUENCY: {0:0..7}, MAP: {0:8..9}", frequency); - {{crate_name}}::exit() + {{project_name | replace(from="-", to="_")}}::exit() } diff --git a/src/bin/format.rs b/src/bin/format.rs index aa8c35f..818adbb 100644 --- a/src/bin/format.rs +++ b/src/bin/format.rs @@ -1,7 +1,7 @@ #![no_main] #![no_std] -use {{crate_name}} as _; // global logger + panicking-behavior + memory layout +use {{ project_name | replace(from="-", to="_") }} as _; // global logger + panicking-behavior + memory layout use defmt::Format; // <- derive attribute #[derive(Format)] @@ -22,5 +22,5 @@ fn main() -> ! { let x = 42; defmt::info!("x={:u8}", x); - {{crate_name}}::exit() + {{project_name | replace(from="-", to="_")}}::exit() } diff --git a/src/bin/hello.rs b/src/bin/hello.rs index 4a39f24..42d2c9b 100644 --- a/src/bin/hello.rs +++ b/src/bin/hello.rs @@ -1,11 +1,11 @@ #![no_main] #![no_std] -use {{crate_name}} as _; // global logger + panicking-behavior + memory layout +use {{ project_name | replace(from="-", to="_") }} as _; // global logger + panicking-behavior + memory layout #[cortex_m_rt::entry] fn main() -> ! { defmt::info!("Hello, world!"); - {{crate_name}}::exit() + {{project_name | replace(from="-", to="_")}}::exit() } diff --git a/src/bin/levels.rs b/src/bin/levels.rs index a944130..7401bcc 100644 --- a/src/bin/levels.rs +++ b/src/bin/levels.rs @@ -1,7 +1,7 @@ #![no_main] #![no_std] -use {{crate_name}} as _; // global logger + panicking-behavior + memory layout +use {{ project_name | replace(from="-", to="_") }} as _; // global logger + panicking-behavior + memory layout #[cortex_m_rt::entry] fn main() -> ! { @@ -11,5 +11,5 @@ fn main() -> ! { defmt::debug!("debug"); defmt::error!("error"); - {{crate_name}}::exit() + {{project_name | replace(from="-", to="_")}}::exit() } diff --git a/src/bin/overflow.rs b/src/bin/overflow.rs index 03c2a47..f37ea8b 100644 --- a/src/bin/overflow.rs +++ b/src/bin/overflow.rs @@ -1,12 +1,12 @@ #![no_main] #![no_std] -use {{crate_name}} as _; // global logger + panicking-behavior + memory layout +use {{ project_name | replace(from="-", to="_") }} as _; // global logger + panicking-behavior + memory layout #[cortex_m_rt::entry] fn main() -> ! { ack(10, 10); - {{crate_name}}::exit() + {{project_name | replace(from="-", to="_")}}::exit() } fn ack(m: u32, n: u32) -> u32 { diff --git a/src/bin/panic.rs b/src/bin/panic.rs index de9298f..6147aac 100644 --- a/src/bin/panic.rs +++ b/src/bin/panic.rs @@ -1,7 +1,7 @@ #![no_main] #![no_std] -use {{crate_name}} as _; // global logger + panicking-behavior + memory layout +use {{ project_name | replace(from="-", to="_") }} as _; // global logger + panicking-behavior + memory layout #[cortex_m_rt::entry] fn main() -> ! { diff --git a/src/lib.rs b/src/lib.rs index 2905d1c..28ea1d9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -3,9 +3,9 @@ use core::sync::atomic::{AtomicUsize, Ordering}; use defmt_rtt as _; // global logger -// TODO(5) adjust HAL import -// use some_hal as _; // memory layout - +{% if use_hal == "yes" %} +use {{ hal_crate | replace(from="-", to="_") }} as _; // memory layout +{% endif %} use panic_probe as _; // same panicking *behavior* as `panic-probe` but doesn't print a panic message diff --git a/template.toml b/template.toml new file mode 100644 index 0000000..482389f --- /dev/null +++ b/template.toml @@ -0,0 +1,53 @@ +name = "MyEmbeddedApp" +description = "Quickly set up a probe-run + defmt + flip-link embedded project" +kickstart_version = 1 +ignore = [ + "README.md", + ".github/FUNDING.yml", +] +copy_without_render = [] + +[[variables]] +name = "authors" +default = "You " +prompt = "Author's name?" + +[[variables]] +name = "project_name" +prompt = "How to name your project's crate?" +default = "my-embedded-app" +validation = "^([a-zA-Z][a-zA-Z0-9_-]+)$" + +[[variables]] +name = "chip" +default = "nRF52840_xxAA" +prompt = "What's the name of the chip (see `probe-run --list-chips` output)?" + +[[variables]] +name = "target" +default = "thumbv6m-none-eabi" +prompt = "What's the target's name?" +choices = [ + "thumbv6m-none-eabi (Cortex-M0 and Cortex-M0+)", + "thumbv7m-none-eabi (Cortex-M3)", + "thumbv7em-none-eabi (Cortex-M4 and Cortex-M7 | no FPU)", + "thumbv7em-none-eabihf (Cortex-M4F and Cortex-M7F | with FPU)" +] + +[[variables]] +name = "use_hal" +default = "yes" +prompt = "Do you want to use an embedded-hal?" +choices = [ "yes", "no" ] + +[[variables]] +name = "hal_crate" +default = "nrf52840-hal" +prompt = "embedded-hal crate name?" +only_if = { name = "use_hal", value = "yes" } + +[[variables]] +name = "hal_crate_version" +default = "0.11.0" +prompt = "embedded-hal crate version?" +only_if = { name = "use_hal", value = "yes" } diff --git a/testsuite/Cargo.toml b/testsuite/Cargo.toml index 5a7766d..0a90bd2 100644 --- a/testsuite/Cargo.toml +++ b/testsuite/Cargo.toml @@ -1,5 +1,4 @@ [package] -# TODO(1) fix `authors` if you didn't use `cargo-generate` authors = ["{{authors}}"] name = "testsuite" publish = false @@ -11,7 +10,7 @@ name = "test" harness = false [dependencies] -{{project-name}} = { path = ".." } +{{project_name}} = { path = ".." } cortex-m = "0.6.3" cortex-m-rt = "0.6.12" defmt = "0.1.0" diff --git a/testsuite/tests/test.rs b/testsuite/tests/test.rs index b26f3bf..1056d08 100644 --- a/testsuite/tests/test.rs +++ b/testsuite/tests/test.rs @@ -1,7 +1,7 @@ #![no_std] #![no_main] -use {{crate_name}} as _; // memory layout + panic handler +use {{ project_name | replace(from="-", to="_") }} as _; // memory layout + panic handler // See https://crates.io/crates/defmt-test/0.1.0 for more documentation (e.g. about the 'state' // feature)