doc: Document the project creation process (#99)

* doc: Document the project creation process

* fix: typo in readme.md introduced in the previous commit

Co-authored-by: 9names <60134748+9names@users.noreply.github.com>

---------

Co-authored-by: 9names <60134748+9names@users.noreply.github.com>

.cargo/config.toml

@@ -5,8 +5,8 @@
 runner = "probe-rs run --chip RP2040 --protocol swd"
 # runner = "elf2uf2-rs -d"
 
+linker = "flip-link"
 rustflags = [
-  "-C", "linker=flip-link",
   "-C", "link-arg=--nmagic",
   "-C", "link-arg=-Tlink.x",
   "-C", "link-arg=-Tdefmt.x",

Cargo.toml

@@ -9,9 +9,9 @@ cortex-m = "0.7"
 cortex-m-rt = "0.7"
 embedded-hal = { version = "1.0.0" }
 
-defmt = "0.3"
-defmt-rtt = "0.4"
-panic-probe = { version = "0.3", features = ["print-defmt"] }
+defmt = "1"
+defmt-rtt = "1"
+panic-probe = { version = "1", features = ["print-defmt"] }
 
 # We're using a Pico by default on this template
 rp-pico = "0.9"
@@ -20,7 +20,7 @@ rp-pico = "0.9"
 # sparkfun-pro-micro-rp2040 = "0.8"
 
 # If you're not going to use a Board Support Package you'll need these:
-# rp2040-hal = { version="0.10", features=["rt", "critical-section-impl"] }
+# rp2040-hal = { version="0.11", features=["rt", "critical-section-impl"] }
 # rp2040-boot2 = "0.3"
 
 # cargo build/run

README.md

@@ -18,6 +18,7 @@ If you aren't using a debugger (or want to use other debugging configurations),
   <ol>
     <li><a href="#markdown-header-requirements">Requirements</a></li>
     <li><a href="#installation-of-development-dependencies">Installation of development dependencies</a></li>
+    <li><a href="#project-creation">Project Creation</a></li>
     <li><a href="#running">Running</a></li>
     <li><a href="#alternative-runners">Alternative runners</a></li>
     <li><a href="#notes-on-using-rp2040_boot2">Notes on using rp2040_boot2</a></li>
@@ -40,9 +41,8 @@ If you aren't using a debugger (or want to use other debugging configurations),
 
 - flip-link - this allows you to detect stack-overflows on the first core, which is the only supported target for now.
 
-- (by default) A [`probe-rs` installation](https://probe.rs/docs/getting-started/installation/)
-
-- A [`probe-rs` compatible](https://probe.rs/docs/getting-started/probe-setup/) probe
+- (by default) A [`probe-rs` installation](https://probe.rs/docs/getting-started/installation)
+- A [`probe-rs` compatible](https://probe.rs/docs/getting-started/probe-setup) probe
 
   You can use a second
   [Pico as a CMSIS-DAP debug probe](debug_probes.md#raspberry-pi-pico). Details
@@ -67,6 +67,31 @@ If you get the error ``binary `cargo-embed` already exists`` during installation
 
 </details>
 
+<!-- Creating the project -->
+<details open="open">
+  <summary><h2 style="display: inline-block" id="project-creation">Creating your project</h2></summary>
+
+### Using `cargo-generate`
+
+```sh
+cargo generate --git https://github.com/rp-rs/rp2040-project-template
+```
+
+Follow the wizard 🪄 and enjoy your new project.
+
+### Downloading as a zip file or using GitHub's template support
+
+Obtain a copy of the code, either by downloading this repository as a zip file or using GitHub's
+template feature, then apply the following:
+- Remove `debug_probes.md`.
+- Remove the `cargo-generate` directory.
+- Remove/edit `README.md`.
+- If using vscode update `.vscode/launch.json`;
+  Else: remove this file.
+- Edit `Cargo.toml` & adjust according to your project (especially its name).
+- Edit `.cargo/config.toml` to select your favorite runner.
+
+</details>
 
 <!-- Running -->
 <details open="open">
@@ -132,7 +157,7 @@ Some of the options for your `runner` are listed below:
 
 * **`cargo embed`**
   This is basically a more configurable version of `probe-rs run`, our default runner.
-  See [the `cargo-embed` tool docs page](https://probe.rs/docs/tools/cargo-embed/) for
+  See [the `cargo-embed` tool docs page](https://probe.rs/docs/tools/cargo-embed) for
   more information.
   
   *Step 1* - Install `cargo-embed`. This is part of the [`probe-rs`](https://crates.io/crates/probe-rs) tools:
@@ -262,7 +287,7 @@ The steps are:
 3. Make some changes to the code or documentation.
 4. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
 5. Push to the Feature Branch (`git push origin feature/AmazingFeature`)
-6. Create a [New Pull Request](https://github.com/rp-rs/rp-hal/pulls)
+6. Create a [New Pull Request](https://github.com/rp-rs/rp2040-project-template/pulls)
 7. An admin will review the Pull Request and discuss any changes that may be required.
 8. Once everyone is happy, the Pull Request can be merged by an admin, and your work is part of our project!
 
@@ -277,9 +302,8 @@ to intervene to uphold that code of conduct.
 
 ## License
 
-The contents of this repository are dual-licensed under the _MIT OR Apache
-2.0_ License. That means you can chose either the MIT licence or the
-Apache-2.0 licence when you re-use this code. See `MIT` or `APACHE2.0` for more
+The contents of this repository are dual-licensed under the _[MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE-2.0)_ License. That means you can chose either the MIT licence or the
+Apache-2.0 licence when you re-use this code. See [`LICENSE-MIT`](LICENSE-MIT) or [`LICENSE-APACHE-2.0`](LICENSE-APACHE-2.0) for more
 information on each specific licence.
 
 Any submissions to this project (e.g. as Pull Requests) must be made available

cargo-generate/Cargo.toml

@@ -9,9 +9,9 @@ cortex-m = "0.7"
 cortex-m-rt = "0.7"
 embedded-hal = { version = "1.0.0" }
 
-defmt = "0.3"
-defmt-rtt = "0.4"
-panic-probe = { version = "0.3", features = ["print-defmt"] }
+defmt = "1"
+defmt-rtt = "1"
+panic-probe = { version = "1", features = ["print-defmt"] }
 
 # We're using a Pico by default on this template
 rp-pico = "0.9"

cargo-generate/config.toml

@@ -15,8 +15,8 @@
       runner = "{{ flash_method_custom }}"
     {%- endif -%}
 {%- endcase %}
+linker = "flip-link"
 rustflags = [
-  "-C", "linker=flip-link",
   "-C", "link-arg=--nmagic",
   "-C", "link-arg=-Tlink.x",
   "-C", "link-arg=-Tdefmt.x",
@@ -25,7 +25,6 @@ rustflags = [
   #   trap unreachable can save a lot of space, but requires nightly compiler.
   #   uncomment the next line if you wish to enable it
   # "-Z", "trap-unreachable=no",
-  "-C", "inline-threshold=5",
   "-C", "no-vectorize-loops",
 ]
 

cargo-generate/launch.json

@@ -31,7 +31,7 @@
                     // "svdFile": "./.vscode/rp2040.svd",
                 }
             ],
-            "consoleLogLevel": "Info", //Error, Warn, Info, Debug, Trace
+            "consoleLogLevel": "Info", //Error, Warn, Info, Debug
             "wireProtocol": "Swd"
         }
     ]