Proofreading fixes (#109)

* feat: Proofreading fixes * docs: Add VsCode note and subsections in tips and tricks * docs: Update heading * docs: Fix typoi * docs: Address feedback * docs: Update main.rs explanation * docs: Update headers * fix: Fix format error * refactor: Rename files and add redirections * docs: Update linking format * docs: Format book links * docs: Update links * style: Format notes and warnings * style: Format codeblocks * style: Avoid having 2 empty lines * style: Remove unused ignore md tags * docs: Implement review suggestions * docs: Split installation chapter * docs: Implement review suggestions
esp-rs · Aug 1, 2023 · 838ed9a · 838ed9a
1 parent 1108c87
commit 838ed9a
Show file tree

Hide file tree

Showing 30 changed files with 645 additions and 746 deletions.
diff --git a/book.toml b/book.toml
@@ -11,5 +11,12 @@ edition = "2018"
 git-repository-url = "https://github.com/esp-rs/book"
 additional-js      = ["assets/mermaid.min.js", "assets/mermaid-init.js"]
 
+[output.html.redirect]
+"/overview/bare-metal.html"                                                         = "https://esp-rs.github.io/book/overview/using-the-core-library.html"
+"/tooling/text-editors-and-ides.html"                                               = "https://esp-rs.github.io/book/tooling/visual-studio-code.html"
+"/debugging/vscode-debugging.html"                                                  = "https://esp-rs.github.io/book/debugging/vscode.html"
+"/writing-your-own-application/no-std-applications/understanding-esp-template.html" = "https://esp-rs.github.io/book/writing-your-own-application/generate-project/esp-template.html"
+"installation/installation.html"                                                    = "https://esp-rs.github.io/book/installation/index.html"
+
 [preprocessor.mermaid]
 command = "mdbook-mermaid"
diff --git a/rust-doc-style-guide.md b/rust-doc-style-guide.md
@@ -41,7 +41,6 @@ The style guide is based on the best practices collected from the following book
   - [Documentation](#documentation)
   - [Code](#code)
 
-
 ## Heading Titles
 
 The books on Rust usually have the heading titles based on nouns or gerunds:
@@ -79,21 +78,20 @@ In hyphenated words, do not capitalize the parts following the hyphens.
 > **Built-in Targets**<br>
 > **Allowed-by-default Lints**
 
-
 ## Linking
 
 ### Adding Links
 
 To simplify link maintenance, follow the rules below:
 
 - Use [link variables][stackoverflow-link-var] with variable names that give a clue on where the link leads.
-- Define link variables right after the paragraphs where they are used.
+- Define link variables right before the end of the section/subsection where they are used.
 
 [stackoverflow-link-var]: https://stackoverflow.com/a/27784490/10308406
 
 Example:
 
-```
+```md
 [`espup`][espup-github] is a tool that simplifies installing and maintaining the components required to develop Rust applications.
 
 [espup-github]: https://github.com/esp-rs/espup
@@ -120,7 +118,7 @@ Also take into account the following
 - Do not provide a link to the same location repeatedly in the same or adjacent paragraphs without a good reason, especially using different link text.
 - Do not use the same link text to refer to different locations.
 
-  > `espup` might have a section in a book and a github repo. In this case, see the [`espup`](#espup) section and [`espup` repo](https://hackmd.io/-cf0jVTqRqm9O7GM5JgLiA?both).
+  > `espup` might have a section in a book and a github repo. In this case, see the [`espup`](https://esp-rs.github.io/book/installation/index.html#risc-v-and-xtensa-targets) section and [`espup` repo](https://github.com/esp-rs/espup).
 
 See also, the [Using `monospace`](#using-monospace) section.
 
@@ -165,7 +163,6 @@ The books on Rust usually use the following list formatting:
   -  For an example using bold font, see the list in the [Modules Cheat Sheet](https://doc.rust-lang.org/book/ch07-02-defining-modules-to-control-scope-and-privacy.html#modules-cheat-sheet) section in The Rust Programming Language book.
   -  For an example using monospace font, see the [Panicking](https://docs.rust-embedded.org/book/start/panicking.html#panicking) section in The Embedded Rust Book.
 
-
 ## Using `monospace`
 
 Use monospace font for the following items:
@@ -208,7 +205,6 @@ Monospace font can also be used in:
 
   > **A `no_std` Rust Environment**
 
-
 ## Using _Italics_
 
 - Introduce new terms
@@ -222,7 +218,6 @@ Monospace font can also be used in:
 
 - Do NOT use italics with Espressif product names, such as ESP32.
 
-
 ## Mode of Narration
 
 - Use _the first person_ (we) when introducing a tutorial or explaining how things will be done. The reader will feel like being on the same team with the authors working side by side.
@@ -243,7 +238,6 @@ Monospace font can also be used in:
 
   > A driver has to be initialized with an instance of type that implements a certain `trait` of the embedded-hal which is ensured via trait bound and provides its own type instance with a custom set of methods allowing to interact with the driven device.
 
-
 ## Terminology
 
 This chapter lists the terms that have inconsistencies in spelling, usage, etc.

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -1,23 +1,28 @@
 # Summary
 
 - [Introduction](./introduction.md)
-- [Ecosystem Overview](./overview/index.md)
+- [Overview of Development Approaches](./overview/index.md)
   - [Using the Standard Library (`std`)](./overview/using-the-standard-library.md)
-  - [Bare Metal (`no_std`)](./overview/bare-metal.md)
+  - [Using the Core Library (`no_std`)](./overview/using-the-core-library.md)
 - [Setting Up a Development Environment](./installation/index.md)
+  - [Rust installation](./installation/rust.md)
+  - [RISC-V targets only](./installation/riscv.md)
+  - [RISC-V and Xtensa targets](./installation/riscv-and-xtensa.md)
+  - [`std` Development Requirements](./installation/std-requirements.md)
+  - [Using Containers](./installation/using-containers.md)
 - [Writing Your Own Application](./writing-your-own-application/index.md)
   - [Generating Projects from Templates](./writing-your-own-application/generate-project/index.md)
     - [Understanding esp-template](./writing-your-own-application/generate-project/esp-template.md)
     - [Understanding esp-idf-template](./writing-your-own-application/generate-project/esp-idf-template.md)
   - [Writing `no_std` Applications](./writing-your-own-application/nostd.md)
   - [Writing `std` Applications](./writing-your-own-application/std.md)
 - [Tooling](./tooling/index.md)
-  - [Visual Studio Code](./tooling/text-editors-and-ides.md)
+  - [Visual Studio Code](./tooling/visual-studio-code.md)
   - [espflash](./tooling/espflash.md)
   - [Debugging](./tooling/debugging/index.md)
     - [probe-rs](./tooling/debugging/probe-rs.md)
     - [OpenOCD](./tooling/debugging/openocd.md)
-    - [Debugging in Visual Studio Code](./tooling/debugging/vscode-debugging.md)
+    - [Debugging in Visual Studio Code](./tooling/debugging/vscode.md)
   - [Simulating](./tooling/simulating/index.md)
     - [Wokwi](./tooling/simulating/wokwi.md)
     - [QEMU](tooling/simulating/qemu.md)

diff --git a/src/installation/index.md b/src/installation/index.md
@@ -9,207 +9,12 @@ To set up the development environment, do the following:
     - [`RISC-V` targets only][risc-v-targets]
     - [`RISC-V` and `Xtensa` targets][rics-v-xtensa-targets]
 
-As mentioned in the installation procedures below, for `std` development also don't forget to install [`std` Development Requirements][rust-esp-book-std-requirements].
+Regardless of the target architecture, for `std` development also don't forget to install [`std` Development Requirements][rust-esp-book-std-requirements].
 
 Please note that you can host the development environment in a [container][use-containers].
 
-[install-rust]: #install-rust
-[risc-v-targets]: #risc-v-targets-only
-[rics-v-xtensa-targets]: #risc-v-and-xtensa-targets
-[use-containers]: #using-containers
-
-## Install Rust
-
-Make sure you have [Rust][rust-lang-org] installed. If not, see the instructions on the [rustup][rustup.rs-website] website.
-
-When using Windows, make sure you have installed one of the ABIs listed below. For more details, see the [Windows][rustup-book-windows] chapter in The rustup book.
-- **MSVC**: Recommended ABI, included in the list of `rustup` default requirements. Use it for interoperability with the software produced by Visual Studio.
-- **GNU**: ABI used by the GCC toolchain. Install it yourself for interoperability with the software built with the MinGW/MSYS2 toolchain.
-
-> **Warning**: When using Unix based systems, installing Rust via a system package manager (e.g. `brew`, `apt`, `dnf`, etc.) can result in various issues and incompatibilities, so it's best to use [rustup][rustup.rs-website] instead.
-
-See also [alternative installation methods][rust-alt-installation].
-
-[rustup.rs-website]: https://rustup.rs/
-[rust-alt-installation]: https://rust-lang.github.io/rustup/installation/other.html
-[rustup-book-windows]: https://rust-lang.github.io/rustup/installation/windows.html
-[rust-lang-org]: https://www.rust-lang.org/
-
-## RISC-V targets only
-
-To build Rust applications for the Espressif chips based on `RISC-V` architecture, do the following:
-
-1. Install the [`nightly`][rustup-book-channel-nightly] toolchain with the `rust-src` [component][rustup-book-components]:
-
-    ```bash
-    rustup toolchain install nightly --component rust-src
-    ```
-
-[rustup-book-channel-nightly]: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust
-[rustup-book-components]: https://rust-lang.github.io/rustup/concepts/components.html
-
-
-2. Set the target:
-    - For `no_std` (bare-metal) applications, run:
-
-      ```bash
-      rustup target add riscv32imc-unknown-none-elf # For ESP32-C2 and ESP32-C3
-      rustup target add riscv32imac-unknown-none-elf # For ESP32-C6 and ESP32-H2
-      ```
-
-      This target is currently [Tier 2][rust-lang-book--platform-support-tier2]; note the different flavors of `riscv32` target in Rust covering different [`RISC-V` extensions][wiki-riscv-standard-extensions].
-
-    - For `std` applications:
-
-      Since this target is currently [Tier 3][rust-lang-book--platform-support-tier3], it does not have pre-built objects distributed through `rustup` and, unlike the `no_std` target, **nothing needs to be installed**. Refer to the [*-esp-idf][rust-lang-book--platform-support--esp-idf] section of the rustc book for the correct target for your device. 
-
-      - `riscv32imc-esp-espidf` for MCUs which do not support atomics, like ESP32-C2 and ESP32-C3
-      - `riscv32imac-esp-espidf` for MCUs which support atomics, like ESP32-C6, ESP32-H2, and ESP32-P4
-
-[rust-lang-book--platform-support-tier2]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-2
-[wiki-riscv-standard-extensions]: https://en.wikichip.org/wiki/risc-v/standard_extensions
-[rust-lang-book--platform-support-tier3]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-3
-[rust-lang-book--platform-support--esp-idf]: https://doc.rust-lang.org/nightly/rustc/platform-support/esp-idf.html
-
-
-3. To build `std` projects, you also need to install:
-    - [`LLVM`][llvm-website] compiler infrastructure
-    - Other [`std` development requirements][rust-esp-book-std-requirements]
-    - In your project's file `.cargo/config.toml`, add the unstable Cargo [feature][cargo-book-unstable-features] `-Z build-std`. Our [template projects][rust-esp-book-write-app-generate-project] that are discussed later in this book already include this.
-
-
-[llvm-website]: https://llvm.org/
-[rust-esp-book-std-requirements]: #std-development-requirements
-[cargo-book-unstable-features]: https://doc.rust-lang.org/cargo/reference/unstable.html
-[rust-esp-book-write-app-generate-project]: ../writing-your-own-application/generate-project/index.md
-
-
-Now you should be able to build and run projects on the Espressif's `RISC-V` chips.
-
-
-## RISC-V and Xtensa targets
-
-[`espup`][espup-github] is a tool that simplifies installing and maintaining the components required to develop Rust applications for the `Xtensa` and `RISC-V` architectures.
-
-[espup-github]: https://github.com/esp-rs/espup
-
-### 1. Install `espup`
-
-To install `espup`, run:
-```sh
-cargo install espup
-```
-
-You can also directly download pre-compiled [release binaries] or use [cargo-binstall].
-
-[release binaries]: https://github.com/esp-rs/espup/releases
-[cargo-binstall]: https://github.com/cargo-bins/cargo-binstall
-
-### 2. Install neccesary toolchains
-
-Install all the necessary tools to develop Rust applications for all supported Espressif targets by running:
-```sh
-espup install
-```
-
-> **Note**: `std` applications require installing additional software covered in [`std` Development Requirements][rust-esp-book-std-requirements]
-
-### 3. Set up the environment variables
-`espup` will create an export file that contains some environment variables required to build projects.
-
-On Windows (`%USERPROFILE%\export-esp.ps1`)
-  - There is **no need** to execute the file for Windows users. It is only created to show the modified environment variables.
-
-On Unix based systems (`$HOME/export-esp.sh`). There are different ways of sourcing the file:
-- Source this file in every terminal:
-   1. Source the export file: `. $HOME/export-esp.sh`
-
-   This approach requires running the command in every new shell.
-- Create an alias for executing the `export-esp.sh`:
-   1. Copy and paste the following command to your shell’s profile (`.profile`, `.bashrc`, `.zprofile`, etc.): `alias get_esprs='. $HOME/export-esp.sh'`
-   2. Refresh the configuration by restarting the terminal session or by running `source [path to profile]`, for example, `source ~/.bashrc`.
-
-   This approach requires running the alias in every new shell.
-- Add the environment variables to your shell's profile directly:
-   1. Add the content of `$HOME/export-esp.sh` to your shell ’s profile: `cat $HOME/export-esp.sh >> [path to profile]`, for example, `cat $HOME/export-esp.sh >> ~/.bashrc`.
-   2. Refresh the configuration by restarting the terminal session or by running `source [path to profile]`, for example, `source ~/.bashrc`.
-
-   This approach **does not** require any sourcing. The `export-esp.sh` script will be sourced automatically in every shell.
-
-
-### What espup Installs
-
-To enable support for Espressif targets, `espup` installs the following tools:
-
-- Espressif Rust fork with support for Espressif targets
-- `nightly` toolchain with support for `RISC-V` targets
-- `LLVM` [fork][llvm-github-fork] with support for `Xtensa` targets
-- [GCC toolchain][gcc-toolchain-github-fork] that links the final binary
-
-The forked compiler can coexist with the standard Rust compiler, allowing both to be installed on your system. The forked compiler is invoked when using any of the available [overriding methods][rustup-overrides].
-
-> **Note**: We are making efforts to upstream our forks
-> 1. Changes in `LLVM` fork. Already in progress, see the status in this [tracking issue][llvm-github-fork-upstream issue].
-> 2. Rust compiler forks. If `LLVM` changes are accepted, we will proceed with the Rust compiler changes.
-
-
-[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
-[llvm-github-fork-upstream issue]: https://github.com/espressif/llvm-project/issues/4
-
-
-### Other installation methods for Xtensa targets
-
-- 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 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. It is not recommended unless there is a major reason to go for this approach. Here is the repository to build it from source: [esp-rs/rust repository].
-
-[esp-rs/rust-build]: https://github.com/esp-rs/rust-build#download-installer-in-bash
-[esp-rs/rust repository]: https://github.com/esp-rs/rust
-
-
-## `std` Development Requirements
-
-Regardless of the target architecture, make sure you have the following required tools installed to build [`std`][rust-esp-book-overview-std] applications:
-
-- [`python`][python-website-download]: Required by ESP-IDF
-- [`git`][git-website-download]: Required by ESP-IDF
-- [`ldproxy`][embuild-github-ldproxy] binary crate: A tool that forwards linker arguments to the actual linker that is also given as an argument to `ldproxy`. Install it by running:
-    ```sh
-    cargo install ldproxy
-    ```
-
-The std runtime uses [ESP-IDF][esp-idf-github] (Espressif IoT Development Framework) as hosted environment but, users do not need to install it. ESP-IDF is automatically downloaded and installed by [esp-idf-sys][esp-idf-sys-github], a crate that all std projects need to use, when building a std application.
-
-
-[rust-esp-book-overview-std]: ../overview/using-the-standard-library.md
-[python-website-download]: https://www.python.org/downloads/
-[git-website-download]: https://git-scm.com/downloads
-[embuild-github-ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy
-[esp-idf-sys-github]: https://github.com/esp-rs/esp-idf-sys
-[esp-idf-github]: https://github.com/espressif/esp-idf
-
-
-## Using Containers
-
-Instead of installing directly on your local system, you can host the development environment inside a container. Espressif provides the [idf-rust] image that supports both `RISC-V` and `Xtensa` target architectures and enables both `std` and `no_std` development.
-
-You can find numerous tags for `linux/arm64`, and `linux/amd64` platforms.
-
-For each Rust release, we generate the tag with the following naming convention:
-
-- `<chip>_<rust-toolchain-version>`
-  - For example, `esp32_1.64.0.0` contains the ecosystem for developing `std`, and `no_std` applications for `ESP32` with the `1.64.0.0` Xtensa Rust toolchain.
-
-There are special cases
-
-- `<chip>` can be `all` which indicates compatibility with all Espressif targets
-- `<rust-toolchain-version>` can be `latest` which indicates the latest release of the `Xtensa` Rust toolchain
-
-Depending on your operating system, you can choose any container runtime, such as [Docker], [Podman], or [Lima].
-
-
-[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
+[install-rust]: ./rust.md
+[risc-v-targets]: ./riscv.md
+[rics-v-xtensa-targets]: ./riscv-and-xtensa.md
+[rust-esp-book-std-requirements]: ./std-requirements.md
+[use-containers]: ./using-containers.md