-
Notifications
You must be signed in to change notification settings - Fork 55
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
20e2ae1
commit 8395df7
Showing
7 changed files
with
190 additions
and
187 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| # 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. | ||
|
|
||
| ### 1. Install `espup` | ||
|
|
||
| To install `espup`, run: | ||
| ```shell | ||
| cargo install espup | ||
| ``` | ||
|
|
||
| You can also directly download pre-compiled [release binaries] or use [cargo-binstall]. | ||
|
|
||
| [espup-github]: https://github.com/esp-rs/espup | ||
| [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: | ||
| ```shell | ||
| espup install | ||
| ``` | ||
|
|
||
| > ⚠️ **Note**: `std` applications require installing additional software covered in [`std` Development Requirements][rust-esp-book-std-requirements] | ||
| [rust-esp-book-std-requirements]: ./std-requirements.md | ||
|
|
||
| ### 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. | ||
| If you run into an error, please, check the [Troubleshooting][troubleshooting] chapter. | ||
|
|
||
| [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 | ||
| [troubleshooting]: ../misc/troubleshooting.md | ||
|
|
||
| ### 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # 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]: | ||
|
|
||
| ```shell | ||
| rustup toolchain install nightly --component rust-src | ||
| ``` | ||
| 2. Set the target: | ||
| - For `no_std` (bare-metal) applications, run: | ||
|
|
||
| ```shell | ||
| 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 SoCs which do not support atomics, like ESP32-C2 and ESP32-C3 | ||
| - `riscv32imac-esp-espidf` for SoCs which support atomics, like ESP32-C6, ESP32-H2, and ESP32-P4 | ||
| 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. | ||
| Now you should be able to build and run projects on the Espressif's `RISC-V` chips. | ||
|
|
||
| [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 | ||
| [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 | ||
| [llvm-website]: https://llvm.org/ | ||
| [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 | ||
| [rust-esp-book-std-requirements]: ./std-requirements.md |
Oops, something went wrong.