Rework Getting Started chapter
#202
Conversation
bjoernQ
force-pushed
the
rework-getting-started
branch
from
13b9ce2 to
564c866
Compare
bjoernQ
force-pushed
the
rework-getting-started
branch
from
29a3372 to
87fe2d5
Compare
| @@ -0,0 +1,52 @@ | |||
| # Using `esp-generate` | |||
|
|
|||
| With all the necessary tools installed, you're ready to create your first Rust project for ESP32. | |||
There was a problem hiding this comment.
Nitpick: "ESP32" migth be confusing, even though if they read the book until here they should already know that we support "all" the esp32 variants
|
|
||
| [cargo-binstall]: https://github.com/cargo-bins/cargo-binstall | ||
| [releases]: https://github.com/esp-rs/espflash/releases | ||
| [espflash]: https://github.com/esp-rs/espflash/tree/main/espflash/ |
There was a problem hiding this comment.
We have already defined [espflash] above, hence both links point to https://github.com/esp-rs/espflash
There was a problem hiding this comment.
Thanks for pointing this out 👍
(BTW I really dislike having links defined all over the place instead of in one place at the end of the document)
| esp-generate --chip esp32c3 your-project-name | ||
| ``` | ||
|
|
||
| <!-- 0.4.0 doesn't include the full interactive mode, yet ---> |
There was a problem hiding this comment.
0.5.0 is released now, we can remove this comment
| Make sure to replace the chip type and project name as needed. You can also leave them out and `esp-generate` will prompt you for them. | ||
|
|
||
| <!--- | ||
| I think a screenshot would make all this look a bit more interesting - but the drawback is it will "always" be outdated. |
There was a problem hiding this comment.
I SC will be handy, whilst more options might come (and some might go), the general structure is likely to stay the same for a long while. Let's add a SC.
| I think a screenshot would make all this look a bit more interesting - but the drawback is it will "always" be outdated. | ||
| ---> | ||
|
|
||
| > 💡 **Hint**: Prefer a non-interactive setup? You can specify configuration options directly using the `-o/--options` flag. |
There was a problem hiding this comment.
Eh, I feel like beyond us using it in CI, this isn't worth writing about.
src/getting-started/toolchain.md
Outdated
| <!--- | ||
| TODO: This needs some rework based on https://github.com/esp-rs/espup/issues/498 | ||
|
|
||
| In general in previous chapters we need to explain RISC-V vs Xtensa etc. |
There was a problem hiding this comment.
src/getting-started/toolchain.md
Outdated
| ## Toolchain Installation | ||
|
|
||
| <!--- | ||
| TODO: This needs some rework based on https://github.com/esp-rs/espup/issues/498 |
There was a problem hiding this comment.
It's really annoying that build-std isn't stable. If it were, I'd recommend that over any "rustup toolchain add" bits. Regardless of the outcome of that issue, we still need to document installing esp toolchain for xtensa chips. I would assume riscv as the happy path, and then follow on to mention xtensa for the esp32,esp32s2 and esp32s3
| @@ -94,9 +91,3 @@ The forked compiler can coexist with the standard Rust compiler, allowing both t | |||
| [llvm-github-fork]: https://github.com/espressif/llvm-project | |||
| [gcc-toolchain-github-fork]: https://github.com/espressif/crosstool-NG/ | |||
| [rustup-overrides]: https://rust-lang.github.io/rustup/overrides.html | |||
|
|
|||
| #### Building the Rust Compiler with Xtensa Support from Source | |||
There was a problem hiding this comment.
Given this is a "getting started" guide we should not even mention this IMHO
(We might or might not add something about this to a future advanced section - but even then we should tell people why they might consider this)
There was a problem hiding this comment.
I agree, no one should ever build this compiler (except for me I guess :D)
This is a rewrite of the "Getting Started" chapter based on the inputs from #177
Details about espflash and probe-rs are mostly removed ("We shouldn't be explaining what the flashing tools do and how to use them here in the getting started section.")
This way we get people to the point running their first lines of Rust code on ESP32 quicker without confusing them.
Before, we explained a lot of things which esp-generate takes care of. Also mentioning "espflash can be used as a library" is not useful at this stage. We don't mention
cargo-espflash,cargo-embedetc. anymore - users won't need them so why bothering them with thisThe toolchain installation needs rework (basically untouched here) once we explain things like RISC-V vs Xtensa in the previous chapters.
I added some comments here where I assume things need more discussion