Book update

README.md

@@ -7,15 +7,15 @@ This book is a work in progress.
 This book is generated using [mdbook], and additionally uses the [mdbook-mermaid] preprocessor to add support for diagrams. To install these tools:
 
 ```shell
-$ cargo install mdbook mdbook-mermaid
+cargo install mdbook mdbook-mermaid
 ```
 
 With `mdbook` and `mdbook-mermaid` installed you can clone the respository and start a development server by running:
 
 ```shell
-$ git clone https://github.com/esp-rs/book
-$ cd book/
-$ mdbook serve
+git clone https://github.com/esp-rs/book
+cd book/
+mdbook serve
 ```
 
 [mdbook]: https://github.com/rust-lang/mdBook

src/SUMMARY.md

@@ -7,7 +7,6 @@
   - [Comparing `std` and `no_std`](./overview/comparing-std-and-no_std.md)
 - [Required Dependencies](./dependencies/index.md)
   - [Installing Rust](./dependencies/installing-rust.md)
-  - [Build Tools](./dependencies/build-tools.md)
 - [Tooling]()
   - [Text Editors and IDEs](./tooling/text-editors-and-ides.md)
   - [espflash](./tooling/espflash.md)
@@ -16,11 +15,14 @@
     - [probe-rs](./tooling/debugging/probe-rs.md)
     - [OpenOCD](./tooling/debugging/openocd.md)
     - [Debugging in Visual Studio Code](./tooling/debugging/vscode-debugging.md)
-- [Writing Your Application]()
-  - [Generate Project from Template](./writing-your-application/generate-project-from-template.md)
-  - [Writing `std` Applications](./writing-your-application/writing-std-applications.md)
+  - [Simulating](./tooling/simulating/index.md)
+    - [Wokwi](./tooling/simulating/wokwi.md)
+    - [QEMU](tooling/simulating/qemu.md)
+- [Writing Your Own Application](./writing-your-own-application/index.md)
+  - [Generate Project from Template](./writing-your-own-application/generate-project-from-template.md)
+  - [Writing `std` Applications](./writing-your-own-application/writing-std-applications.md)
   - [Writing `no_std` Applications (TODO)]()
-
+- [Resources](./resources.md)
 ---
 
 [Appendix A: Glossary](./misc/glossary.md)

src/dependencies/index.md

@@ -1,7 +1,56 @@
 # Required Dependencies
 
-With an understanding of the ecosystem surrounding Rust on Espressif chips, we're able to move on to actual development. If you are not aware of the two possible development approaches, or do not understand the differences between writing `std` and `no_std` applications, please first read the [Ecosystem Overview] chapter.
+With an understanding of the ecosystem surrounding Rust on Espressif chips, we're able to move on to actual development. If you are not aware of the two possible development approaches or do not understand the differences between writing `std` and `no_std` applications, please first read the [Ecosystem Overview] chapter.
 
-In this chapter we will cover the installation of the correct Rust compiler and toolchain as well as creating applications.
 
-[ecosystem overview]: ../overview/index.md
+To build Rust applications for ESP Chips we need:
+- GCC Toolchain: To serve as a C compiler.
+- Rust Toolchain: Used to compile our Rust code.
+  - `LLVM`: The Rust compiler uses `LLVM` as codegen backend.
+- For `std` applications:
+  - [ESP-IDF]: The Espressif IoT Development Framework is required in `std` project as we have seen in the [`std` overview].
+  - [ldproxy] crate:  Simple tool to forward linker arguments given to [ldproxy] to the actual linker executable. The crate can be found in the [esp-rs/embuild] repository.
+
+Let's discuss more in detail the Rust support for the architectures of the Espressif chips.
+
+## Rust in RISC-V
+
+The `RISC-V` architecture has support in the mainline Rust compiler so setup is relatively simple, all we must do is add the appropriate compilation target.
+
+
+There are two suitable targets for this chip:
+
+- For bare-metal (`no_std`) applications, use `riscv32imc-unknown-none-elf`
+- For applications that require `std`, use `riscv32imc-esp-espidf`
+
+The standard library target (`riscv32imc-esp-espidf`) is currently [Tier 3] and does not have prebuilt objects distributed through `rustup`.
+
+
+## Rust in Xtensa
+To this day, there is no `Xtensa` support in the mainline Rust compiler, for this reason, we maintain the [esp-rs/rust] fork that adds support four our `Xtensa` targets.
+
+`Xtensa` not being supported on Rust mainline is mainly a consequence of `LLVM` not supporting `Xtensa` targets. We also maintain an LLVM fork with support for Espressif `Xtensa` targets in [espressif/llvm-project]
+
+> #### A note in upstreaming our forks.
+>
+> We are trying to upstream the changes in both our `LLVM` and Rust fork.
+> The first step is to upstream the `LLVM` project, this is already in progress
+> and you can see the status at this [tracking issue].
+> If `LLVM` changes are accepted in `LLVM` mainline, we will proceed with trying
+> to upstream the Rust compiler changes.
+
+The forked compiler can coexist with the standard Rust compiler, so it is possible to have both installed on your system. The forked compiler is invoked when using the `esp` [channel] instead of the defaults, `stable` or `nightly`.
+
+[esp-rs/rust]: https://github.com/esp-rs/rust
+
+In this chapter, we will cover the installation of the correct Rust compiler and toolchain.
+
+[Ecosystem Overview]: ../overview/index.md
+[ESP-IDF]: https://github.com/espressif/esp-idf
+[`std` overview]: src\overview\using-the-standard-library.md
+[ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy
+[esp-rs/embuild]: https://github.com/esp-rs/embuild
+[Tier 3]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-3
+[espressif/llvm-project]: https://github.com/espressif/llvm-project
+[tracking issue]: https://github.com/espressif/llvm-project/issues/4
+[channel]: https://rust-lang.github.io/rustup/concepts/channels.html

src/dependencies/installing-rust.md

@@ -1,176 +1,133 @@
 # Installing Rust
 
-In order to develop for ESP devices using Rust you must first install the Rust compiler along with the appropriate toolchain and target(s). Depending on your device it may be one of two architectures, each requiring different setup.
+In order to develop for ESP devices using Rust you must first install the Rust compiler along with the appropriate toolchain and target(s). Depending on your device it may be one of two architectures, each requiring a different setup.
 
-If you have not yet installed Rust on your system, you can do so easily using [rustup]. For _macOS_ and _Linux_ it can be installed by runing the following command:
+If you have not yet installed Rust on your system, you can do so easily using [rustup]. For _macOS_ and _Linux_ it can be installed by running the following command:
 
 ```bash
-$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
 For installation on Windows or alternative installation methods, please refer to the instructions on the [rustup] website.
 
-With Rust installed we next need to ensure that the `nightly` toolchain is installed and set as the default:
+If you are [running Windows as your host operating system, you must also install one of the available ABIs]:
+- MSVC: Is the recommended ABI. When installing `rustup`, it will check if all the requirements are installed, and, if they are not, it allows the user to install them.
+- GNU: No checks are done in `rustup` and expect that the user takes care of properly installing it.
 
-```bash
-$ rustup toolchain install nightly
-$ rustup default nightly
-```
-
-You can read more about toolchains in the [rustup book].
-
-[rustup]: https://rustup.rs/
-[rustup book]: https://rust-lang.github.io/rustup/concepts/toolchains.html
-
-## Prerequisites
-
-### git
-
-`git` must be installed on your system in order to clone repositories. This should be available via your system's package manager, or for Windows users [Git for Windows] can be used.
-
-[git for windows]: https://gitforwindows.org/
-
-### Visual Studio Build Tools
-
-If you are running Windows as your host operating system, you must install the Visual Studio Build Tools, which can be downloaded from the [Microsoft website].
-
-[microsoft website]: https://visualstudio.microsoft.com/downloads/
-
-### Xtensa Toolchain
+## ldproxy
 
-If you are developing for an Xtensa chip (_ESP32_, _ESP32-S2_, _ESP32-S3_) you must also install the appropriate Xtensa toolchain. Pre-built toolchains can be downloaded from the [crosstool-NG] repository for the most common operating systems and architectures.
-
-Ensure that you have downloaded the required toolchain and added its directory to your `PATH` environment variable prior to building your application.
-
-[crosstool-ng]: https://github.com/espressif/crosstool-NG
-
-## RISC-V (ESP32-C3)
+As seen in the previous [Required dependencies section], `ldproxy` is required when building applications using the Rust standard library, `std`. To install:
+```sh
+cargo install ldproxy
+```
 
-The `RISC-V` architecture has support in the mainline Rust compiler so setup is relatively simple, all we must do is add the appropriate compilation target.
+This tool is required regardless of the target architecture.
 
-There are two suitable targets for this chip:
+[Required dependencies section]: index.md#required-dependencies
 
-- For bare-metal (`no_std`) applications, use `riscv32imc-unknown-none-elf`
-- For applications which require `std`, use `riscv32imc-esp-espidf`
+## RISC-V
 
-The bare-metal target can be installed by running:
+If you only want to target `RISC-V` chips, installation is simpler. In order to build
+applications for `RISC-V` targets we need to use a [Rust nightly toolchain] with the `rust-src` [component], both things can be installed with:
 
 ```bash
-$ rustup target add riscv32imc-unknown-none-elf
+rustup toolchain install nightly --component rust-src
 ```
 
-The standard library target (`riscv32imc-esp-espidf`) is currently Tier 3, and does not have prebuilt objects distributed through `rustup`, therefore the `-Z build-std` unstable cargo feature is required within your project. See an example usage in [rust-esp32-std-mini](https://github.com/ivmarkov/rust-esp32-std-mini/blob/5fe3a5d75b16c6cee63e4c36b87f936744151494/.cargo/config.toml#L25-L26).
-
-At this point you are ready to build applications for the ESP32-C3.
-
-[rustup]: https://rustup.rs/
-[esp-idf]: https://github.com/espressif/esp-idf
-
-## Xtensa (ESP32, ESP32-S2, ESP32-S3)
-
-Because there is no `Xtensa` support in the mainline Rust compiler you must use the [esp-rs/rust] fork instead. There are a few options available for installing this compiler fork.
-
-The forked compiler can coexist with the standard Rust compiler, so it is possible to have both installed on your system. The forked compiler is invoked when using the `esp` channel instead of the defaults, `stable` or `nightly`.
-
-[esp-rs/rust]: https://github.com/esp-rs/rust
-
-### Using a Pre-Built Release
-
-Pre-built releases are available for a number of platforms on GitHub under the [esp-rs/rust-build] repository. The following operating systems and architectures are currently supported:
-
-- macOS (`x86_64`, `aarch64`)
-- Windows (`x86_64`)
-- Linux (`x86_64`)
-
-The aforementioned repository also contains Bash and PowerShell scripts to automate the installation process.
-
-#### macOS and Linux
+For bare-metal, target can be installed by running:
 
 ```bash
-$ curl -LO https://raw.githubusercontent.com/esp-rs/rust-build/main/install-rust-toolchain.sh
-$ chmod +x install-rust-toolchain.sh
-$ ./install-rust-toolchain.sh
+rustup target add riscv32imc-unknown-none-elf
 ```
 
-#### Windows
+For `std` applications, the `riscv32imc-esp-espidf` target does not have prebuilt objects distributed through rustup, therefore the `-Z build-std` [unstable cargo feature] is required within your project. This [unstable cargo feature] can also be added to `.cargo/config.toml` of your project. Our [template projects] ,which we will later discuss, already take care of this.
 
-With GUI installer: [https://github.com/espressif/idf-installer/releases]
+Also, when building `std` applications, make sure you have [`LLVM`] installed.
 
-With PowerShell:
+At this point, you are ready to build applications for all the Espressif chips based on RISC-V architecture.
 
-```powershell
-PS> Invoke-WebRequest https://raw.githubusercontent.com/esp-rs/rust-build/main/Install-RustToolchain.ps1 -OutFile Install-RustToolchain.ps1
-PS> Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
-PS> ./Install-RustToolchain.ps1
-```
-
-To confirm the `esp` toolchain has been installed:
+The installation of `RISC-V` targets can also, be handled by `espup`, a tool that will be introduced
+in the [`espup` section].
 
-```bash
-$ rustup toolchain list
-stable-x86_64-apple-darwin
-nightly-x86_64-apple-darwin (default)
-esp
-```
+## Xtensa
 
-[esp-rs/rust-build]: https://github.com/esp-rs/rust-build
-[https://github.com/espressif/idf-installer/releases]: https://github.com/espressif/idf-installer/releases
+Because there is no `Xtensa` support in the mainline Rust compiler you must use the [esp-rs/rust] fork instead. There are a few options available for installing this compiler fork.
 
-### Building From Source
+The forked compiler can coexist with the standard Rust compiler, so it is possible to have both installed on your system. The forked compiler is invoked when using the `esp` channel instead of the defaults, `stable` or `nightly`.
 
-You can also build the Rust compiler with `Xtensa` support from source. This process is computationally expensive and can take one or more hours to complete depending on your system. It is recommended that you have _at least_ 6GB of RAM and 25GB+ of available storage space.
 
-To check out the repository and build the compiler:
+There are several ways of installing our Xtensa Rust toolchain:
+- The recommended one is using `espup`. See [`espup` section] for more details.
+- Using [esp-rs/rust-build] installation scripts. This was the recommended way in the past, but now, the installation scripts are feature frozen and all the new features will only be included in `espup`. See the repository readme for instructions.
+- Building the Rust compiler with Xtensa support from source. This process is computationally expensive and can take one or more hours to complete depending on your system, for this reason, is not recommended unless there is a major reason to go for this approach. See instructions in the [Installing from Source section of the esp-rs/rust repository].
 
-```bash
-$ git clone https://github.com/esp-rs/rust
-$ cd rust
-$ ./configure --experimental-targets=Xtensa
-$ ./x.py build --stage 2
-```
+## espup
 
-Note that you should _not_ rename the `rust` directory to avoid issues while building.
+[esp-rs/espup] is a tool for installing and maintaining the required ecosystem to develop applications in Rust for Espressif SoC's (both `Xtensa` and `RISC-V` targets).
 
-Once the build has completed, you can link the toolchain using rustup (your architecture/operating system may be different):
+`espup` takes care of installing our forked Rust compiler, the necessary GCC toolchains for ESP chips, and many other things. For more details, [see Usage section of the `espup` Readme].
 
-```bash
-$ rustup toolchain link esp $PWD/build/x86_64-apple-darwin/stage2
+In order to install `espup`:
+```sh
+cargo install espup --git https://github.com/esp-rs/espup
 ```
 
-Once the compiler fork has been installed using one of the above methods, to confirm the `esp` toolchain has been installed:
+It's also possible to directly download the pre-compiled [release binaries] or to use [cargo-binstall].
 
-```bash
-$ rustup toolchain list
-stable-x86_64-apple-darwin
-nightly-x86_64-apple-darwin (default)
-esp
+Once that `espup` is installed you can simply run:
+```sh
+espup install
 ```
 
-To view the installed `Xtensa` targets:
+And it will all the necesary tools to develop Rust applications for ESP targets.
 
-```bash
-$ rustc +esp --print target-list | grep xtensa
-xtensa-esp32-espidf
-xtensa-esp32-none-elf
-xtensa-esp32s2-espidf
-xtensa-esp32s2-none-elf
-xtensa-esp8266-none-elf
-xtensa-none-elf
+`espup` will create and export file, by default called `export-esp.sh` on Unix systems
+and `export-esp.ps1` on Windows, this file contains the required environment variables. Please, make sure to source in every terminal before building any application.
+
+```sh
+# Unix
+. ./export-esp.sh
+# Windows
+.\export-esp.ps1
 ```
 
-### Using Containers
+## Using Containers
 
 As an alternative to installing the compiler fork to your local system directly, it's also possible to run it inside of a container.
 
 A number of container runtimes are available, and which should be used depends on your operating system. Some of the popular options are:
 
-- [Docker] (non-commerial use only without a license)
+- [Docker] (non-commercial use only without a license)
 - [Podman]
 - [Lima]
 
-Espressif provides the [idf-rust] container image which contains [esp-idf] and the pre-built Rust compiler fork.
+Espressif provides the [idf-rust] container image which contains several tags (generated both for `linux/arm64` and `linux/amd64`) for every Rust release:
+- For `std` applications the following naming convention is applied: `<chip>_<esp-idf-version>_<rust-toolchain-version>` . E.g., [`esp32s3_v4.4_1.64.0.0`] contains the ecosystem for developing `std` applications based on [ESP-IDF release/v4.4] for `ESP32-S3` with the `1.64.0.0` Rust toolchain.
+- For `no_std` applications, the naming convention is: `<chip>_<rust-toolchain-version>`. E.g., [`esp32_1.64.0.0`] contains the ecosystem for developing `non_std` aplications for `ESP32` with the `1.64.0.0` Rust toolchain.
+
+There is an `all` `<chip>` for both `std` and `no_std` tags which contains the environment required for all the ESP targets.
+
 
-[docker]: https://www.docker.com/
-[podman]: https://podman.io/
-[lima]: https://github.com/lima-vm/lima
-[idf-rust]: https://hub.docker.com/r/espressif/idf-rust
+[rustup]: https://rustup.rs/
+[running Windows as your host operating system, you must also install one of the available ABIs]: https://rust-lang.github.io/rustup/installation/windows.html
+[Rust nightly toolchain]: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust
+[component]: https://rust-lang.github.io/rustup/concepts/components.html
+[unstable cargo feature]: https://doc.rust-lang.org/cargo/reference/unstable.html
+[template projects]: ../writing-your-own-application/generate-project-from-template.md
+[`LLVM`]: https://llvm.org/
+[`espup` section]: #espup
+[esp-rs/rust]: https://github.com/esp-rs/rust
+[`espup` section]: #espup
+[esp-rs/rust-build]: https://github.com/esp-rs/rust-build
+[Installing from Source section of the esp-rs/rust repository]: https://github.com/esp-rs/rust#installing-from-source
+[esp-rs/espup]: https://github.com/esp-rs/espup
+[see Usage section of the `espup` Readme]: https://github.com/esp-rs/espup#usage
+[release binaries]: https://github.com/esp-rs/espup/releases
+[cargo-binstall]: https://github.com/cargo-bins/cargo-binstall
+[Docker]: https://www.docker.com/
+[Podman]: https://podman.io/
+[Lima]: https://github.com/lima-vm/lima
+[idf-rust]: https://hub.docker.com/r/espressif/idf-rust/tags
+[`esp32s3_v4.4_1.64.0.0`]: https://hub.docker.com/layers/espressif/idf-rust/esp32s3_v4.4_1.64.0.0/images/sha256-6fa1e98d770e3edc67cbd565893aa04e5573024b1e3e373fae50907435e841e4?context=explore
+[ESP-IDF release/v4.4]: https://github.com/espressif/esp-idf/tree/release/v4.4
+[`esp32_1.64.0.0`]: https://hub.docker.com/layers/espressif/idf-rust/esp32_1.64.0.0/images/sha256-cc026ff9278a876f171d48978988e131940c07659485937a37cf750c44b28dfd?context=explore