# Setting Up a Development Environment At the moment, Espressif SoCs are based on two different architectures – `RISC-V` and `Xtensa` – each supporting the `std` and `no_std` application development. Depending on which architectures are relevant for you, choose the Rust installer and follow the guidelines in the respective section below. | Rust Installer | `RISC-V` | `Xtensa` | | :-----------------: | :------: | :------: | | [`rustup`](#rustup) | ✓ | ✘ | | [`espup`](#espup) | ✓ | ✓ | Alternatively, you can host the development environment in a [container](#using-containers). ## rustup With `rustup`, you can easily install the official Rust tools. Please, note that it provides support for `RISC-V` targets only. ### Installation and Usage See [installation instructions]([`rustup`]) and Usage. > **Note**: If you run Windows on your host machine, make sure you have installed one of the ABIs listed below. For more details, see [The rustup book > Chapter _Windows_] > - **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. ### Configuration To build Rust applications for the Espressif chips based on `RISC-V` architecture, do the following configuration 1. Install a [`nightly`] toolchain with the `rust-src` [component]: ```bash rustup toolchain install nightly --component rust-src ``` 2. Set the target: - For `no_std` (bare-metal) applications, run: ```bash rustup target add riscv32imc-unknown-none-elf ``` This target is currently [Tier 2]; note the different flavors of `riscv32` target in Rust covering different [`RISC-V` extensions]. - For `std` applications, use the target `riscv32imc-esp-espidf`. Since this target is currently [Tier 3], it does not have pre-built objects distributed through `rustup`, and **it does not need to be installed** as the `no_std` target. 3. To build `std` projects, you also need to install: - [`LLVM`] compiler infrastructure - Other [requirements] for `std` development - In your project's file `.cargo/config.toml`, add the unstable Cargo [feature] `-Z build-std`. Our [template projects] that are discussed later in this book already have it added. Now you should be able to build and run projects on the Espressif's `RISC-V` chips. ## espup [esp-rs/espup] is a tool similar to `rustup` and maintained by Espressif. It simplifies installing and updating the components required to build Rust applications for both Espressif's `Xtensa` and `RISC-V` architectures. ### Installation and Usage See [Installation] and [Usage]. After installing `espup`: - `no_std` (bare-metal) applications should work out of the box - `std` applications require additional software covered in [`std` Development](#std-development) #### What espup Installs To allow support for`Xtensa` targets, `espup` installs the following tools: - Rust compiler(s) (rustup?) - Espressif fork for `Xtensa` targets - `nightly` toolchain with the necessary `RISC-V` targets - `LLVM` [fork] that supports `Xtensa` targets - [GCC toolchain] as a custom linker that allows `LLVM` to support `Xtensa` targets The Xtensa Rust can coexist with the standard Rust, allowing both to be installed on your system. The forked compiler is invoked when using the `esp` [channel] instead of the defaults, `stable` or `nightly`. > **Note**: We are making efforts to upstream our forks > 1. Changes in `LLVM` fork. Already in progress, see the status in this [tracking issue]. > 2. Rust compiler forks. If `LLVM` changes are accepted, we will proceed with the Rust compiler changes. [Ecosystem Overview]: ../overview/index.md [`espup`]: https://github.com/esp-rs/espup [covered later]: #espup [`rustup`]: https://rustup.rs/ [running Windows as your host operating system, make sure you have installed one of the ABIs listed below]: https://rust-lang.github.io/rustup/installation/windows.html [The rustup book > Chapter _Windows_]: https://rust-lang.github.io/rustup/installation/windows.html [flavors]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-2 [`nightly`]: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust [component]: https://rust-lang.github.io/rustup/concepts/components.html [template projects]: ../writing-your-own-application/generate-project-from-template.md [feature]: https://doc.rust-lang.org/cargo/reference/unstable.html [`LLVM`]: https://llvm.org/ [`RISC-V` extensions]: https://en.wikichip.org/wiki/risc-v/standard_extensions [Tier 2]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-2 [Tier 3]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-3 [`esp-idf-sys`]: https://github.com/esp-rs/esp-idf-sys [#]: #requirements-for-std-development [esp-rs/rust]: https://github.com/esp-rs/rust [fork]: https://github.com/espressif/llvm-project [GCC toolchain]: https://github.com/espressif/crosstool-NG/ [tracking issue]: https://github.com/espressif/llvm-project/issues/4 [channel]: https://rust-lang.github.io/rustup/concepts/channels.html [requirements]: https://github.com/esp-rs/espup#requirements [esp-rs/espup]: https://github.com/esp-rs/espup [Usage]: https://github.com/esp-rs/espup#usage [Installation]: https://github.com/esp-rs/espup#installation [release binaries]: https://github.com/esp-rs/espup/releases [cargo-binstall]: https://github.com/cargo-bins/cargo-binstall ## `std` Development Regardless of the target architecture make sure you have the following required tools installed to build [`std`] applications: - [`python`]: Required by ESP-IDF - [`git`]: Required by ESP-IDF - [`ldproxy`] crate: Simple tool to pass the `ldproxy` linker arguments to the actual linker executable. Install it by running - `cargo install ldproxy` The `std` runtime uses [ESP-IDF] (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`], a crate that all `std` projects need to use, when building a `std` application. [`std`]: ../overview/using-the-standard-library.md [`git`]: https://git-scm.com/downloads [`python`]: https://www.python.org/downloads/ [`ldproxy`]: https://github.com/esp-rs/embuild/tree/master/ldproxy [ESP-IDF]: https://github.com/espressif/esp-idf [`esp-idf-sys`]: https://github.com/esp-rs/esp-idf-sys ## 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`.(?) For each Rust release, we generate the tag `<chip>_<xtensa-version>`: - `<chip>` indicates the target for which the tag contains the environment - `all` indicates compatibility with all ESP targets - `<xtensa-version>` - version of the `Xtensa` Rust toolchain - `latest` indicates the latest release (?)There are several container runtimes available, and the runtime you choose will depend on your operating system. Some popular options include: - [Docker] \(non-commercial use only without a license\) - [Podman] - [Lima] -- MacOS [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