Merge #741

741: Docs 2 r=korken89 a=datdenkikniet

Working on the migration guide and other docs

TODO:
- [x] Migration guide
- [x] Hardcoded examples should link to example code that is tested (this was already done, AFAICT)
- [x] Address #699 
- [x] Discuss: should we remove references to non-v2, apart from the migration guide and link to the book for v1? (Off-github conclusion: yes)
- [x] RTIC {vs,and} Embassy (important: distinction between embassy runtime & HALs)
- [x] More descriptive docs on how to implement & PR implementations of `Monotonic` to `rtic-monotonics` 


Co-authored-by: datdenkikniet <jcdra1@gmail.com>

1 files changed, 47 insertions, 0 deletions

diff --git a/book/en/src/by-example/tips/view_code.md b/book/en/src/by-example/tips/view_code.md
new file mode 100644
index 0000000..64af7ad
--- /dev/null
+++ b/book/en/src/by-example/tips/view_code.md
@@ -0,0 +1,47 @@
+# Inspecting generated code
+
+`#[rtic::app]` is a procedural macro that produces support code. If for some reason you need to inspect the code generated by this macro you have two options:
+
+You can inspect the file `rtic-expansion.rs` inside the `target` directory. This file contains the expansion of the `#[rtic::app]` item (not your whole program!) of the *last built* (via `cargo build` or `cargo check`) RTIC application. The expanded code is not pretty printed by default, so you'll want to run `rustfmt` on it before you read it.
+
+``` console
+$ cargo build --example smallest --target thumbv7m-none-eabi
+```
+
+``` console
+$ rustfmt target/rtic-expansion.rs
+```
+
+``` console
+$ tail target/rtic-expansion.rs
+```
+
+``` rust,noplayground
+#[doc = r" Implementation details"]
+mod app {
+    #[doc = r" Always include the device crate which contains the vector table"]
+    use lm3s6965 as _;
+    #[no_mangle]
+    unsafe extern "C" fn main() -> ! {
+        rtic::export::interrupt::disable();
+        let mut core: rtic::export::Peripherals = core::mem::transmute(());
+        core.SCB.scr.modify(|r| r | 1 << 1);
+        rtic::export::interrupt::enable();
+        loop {
+            rtic::export::wfi()
+        }
+    }
+}
+```
+
+Or, you can use the [`cargo-expand`] sub-command. This sub-command will expand *all* the macros, including the `#[rtic::app]` attribute, and modules in your crate and print the output to the console.
+
+[`cargo-expand`]: https://crates.io/crates/cargo-expand
+
+``` console
+# produces the same output as before
+```
+
+``` console
+cargo expand --example smallest | tail
+```