Merge #531

531: Rust Analyzer documentation r=Dirbaio a=huntc

Intends to clarify how to make Embassy usable from within Visual Studio Code by assuming the presence of the Rust Analyzer.

Note that IntelliJ does not support the Rust Analyzer, so an open question remains as to the whether this is a good move. If it turns out not to be a good move then we should still look at clarifying the use of a workspace file.

Co-authored-by: huntc <huntchr@gmail.com>

.vscode/settings.json

@@ -16,7 +16,8 @@
     //"embassy-net/pool-16",
   ],
   "rust-analyzer.linkedProjects": [
-    "examples/stm32f1/Cargo.toml"
+    // Declare for the target you wish to develop
+    "examples/nrf/Cargo.toml"
   ],
   "rust-analyzer.procMacro.enable": true,
   "rust-analyzer.cargo.runBuildScripts": true,

Cargo.example.toml

@@ -1,93 +0,0 @@
-# This file is a template for a Cargo workspace for developer convenience.
-#
-# Since Cargo resolves all features for all crates in the workspace together, 
-# it is not possible to have a workspace with all the crates together, since they
-# enable incompatible features. For example, nrf crates enable embassy-macros/nrf
-# and stm32 crates enable embassy-macros/stm32. embassy-macros doesn't support having
-# both of these features on at the same time, because it makes no sense.
-#
-# Instead, we provide this template so you can enable only the crates you're going to
-# work on. This makes eg rust-analyzer check-on-save and autocomplete work, but only 
-# in these crates, without any feature conflict.
-#
-# Copy this file to `Cargo.toml` and uncomment one group of crates below.
-#
-# `/Cargo.toml` is already in .gitignore, so you don't commit it accidentally.
-
-[workspace]
-resolver = "2"
-
-members = [
-    "embassy",
-    "embassy-traits",
-    "embassy-macros",
-    "embassy-hal-common",
-    "embassy-net",
-
-    # Uncomment ONLY ONE of the groups below.
-
-    # nRF
-    #"embassy-nrf",
-    #"examples/nrf",
-
-    # stm32
-    #"embassy-stm32",
-    #"stm32-metapac",
-    # uncomment ONLY ONE example crate.
-    #"examples/stm32f0",
-    #"examples/stm32f1",
-    #"examples/stm32f4",
-    #"examples/stm32f7",
-    #"examples/stm32g0",
-    #"examples/stm32h7",
-    #"examples/stm32l0",
-    #"examples/stm32l1",
-    #"examples/stm32l4",
-    #"examples/stm32wb55",
-    #"examples/stm32wl55",
-
-    # rp2040
-    #"embassy-rp",
-    #"examples/rp",
-
-    # std
-    #"examples/std",
-]
-
-exclude = [
-    # This is only built as a build-dependency, for the host. It shouldn't
-    # get built for the target.
-    "stm32-metapac-gen"
-]
-
-[profile.dev]
-codegen-units = 1
-debug = 2
-debug-assertions = true
-incremental = false
-opt-level = 3
-overflow-checks = true
-
-[profile.release]
-codegen-units = 1
-debug = 2
-debug-assertions = false
-incremental = false
-lto = "fat"
-opt-level = 's'
-overflow-checks = false
-
-# do not optimize proc-macro crates = faster builds from scratch
-[profile.dev.build-override]
-codegen-units = 8
-debug = false
-debug-assertions = false
-opt-level = 0
-overflow-checks = false
-
-[profile.release.build-override]
-codegen-units = 8
-debug = false
-debug-assertions = false
-opt-level = 0
-overflow-checks = false

README.md

@@ -28,9 +28,10 @@ The `embassy::executor` module provides an async/await executor designed for emb
 
 `embassy::util` contains some lightweight async/await utilities, mainly helpful for async driver development (signaling a task that an interrupt has occured, for example).
 
-## embassy-nrf
+## HALs
 
-The `embassy-nrf` crate contains implementations for nRF 52 series SoCs.
+Hardware Absraction Layers with asynchronous behaviors are provided for a variety of platforms.
+For example, the `embassy-nrf` crate contains implementations for nRF 52 series SoCs.
 
 - `uarte`: UARTE driver implementing `AsyncBufRead` and `AsyncWrite`.
 - `qspi`: QSPI driver implementing `Flash`.
@@ -41,7 +42,8 @@ The `embassy-nrf` crate contains implementations for nRF 52 series SoCs.
 
 ## Examples
 
-Examples are found in the `examples/` folder seperated by the chip manufacturer they are designed to run on:
+Examples are found in the `examples/` folder seperated by the chip manufacturer they are designed to run on. For example:
+
 *   `examples/nrf` are designed to run on the `nrf52840-dk` board (PCA10056) but should be easily adaptable to other nRF52 chips and boards.
 *   `examples/rp` are for the RP2040 chip.
 *   `examples/stm32` are designed for the STM32F429ZI chip but should be easily adaptable to other STM32F4xx chips.
@@ -61,12 +63,27 @@ git submodule update
 cargo install probe-run
 ```
 
-- Run the example
+- Change directory to the sample's base directory. For example:
 
 ```
-cargo run --bin rtc_async
+cd examples/nrf
 ```
 
+- Run the example
+
+For example:
+
+```
+cargo run --bin blinky
+```
+
+## Developing Embassy with Rust Analyzer based editors
+
+The [Rust Analyzer](https://rust-analyzer.github.io/) is used by [Visual Studio Code](https://code.visualstudio.com/)
+and others. Given the multiple targets that Embassy serves, there is no Cargo workspace file. Instead, the Rust Analyzer 
+must be told of the target project to work with. In the case of Visual Studio Code, 
+please refer to the `.vscode/settings.json` file's `rust-analyzer.linkedProjects`setting.
+
 ## Minimum supported Rust version (MSRV)
 
 Required nightly version is specified in the `rust-toolchain.toml` file. Nightly is required for: