In order to develop applications 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 running the following command:
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.
- MSVC: This 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
rustupand expect that the user takes care of properly installing it.
ldproxy crate is required when building applications using the Rust standard library,
std. To install:
cargo install ldproxy
This tool is required for
std applications regardless of the target architecture.
If you only want to target
RISC-V chips, installation is simpler. In order to build
RISC-V targets we need to use a Rust nightly toolchain with the
rust-src component, both things can be installed with:
rustup toolchain install nightly --component rust-src
There are two suitable targets for this chip:
- For bare-metal (
no_std) applications, use
- For applications that require
The bare-metal target can be installed by running:
rustup target add riscv32imc-unknown-none-elf
std applications, the
riscv32imc-esp-espidf target is currently Tier 3 and does not have prebuilt objects distributed through rustup, therefore, it does not need to be installed as
-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 takes care of this.
Also, when building
std applications, make sure you have
ldproxy installed. ESP-IDF will be installed by
esp-idf-sys altough you can also use an existing installation, see ESP-IDF installation note.
At this point, you are ready to build applications for all the Espressif chips based on RISC-V architecture.
The installation of Rust for ESP
RISC-V targets can also be handled by
espup, a tool that will be introduced
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 recommended one is using esp-rs/espup. See
espupsection 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
Xtensasupport 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.
esp-rs/espup is a tool for installing and maintaining the required ecosystem to develop applications in Rust for Espressif SoC's (both
espup takes care of installing the proper Rust compiler (our fork in case of
Xtensa targets, and the
nightly toolchain with the necessary target for
GCC toolchains, and many other things. For more details, see Usage section of the
In order to install
cargo install espup
espup is installed you can simply run:
And it will install all the necessary tools to develop Rust applications for all supported ESP targets.
espup will create and export file, by default called
export-esp.sh on Unix systems
export-esp.ps1 on Windows, this file contains the required environment variables. Please, make sure to source in every terminal before building any application:
# Unix . $HOME/export-esp.sh # Windows %USERPROFILE%\export-esp.ps1
We already mentioned that ESP-IDF is required when building
stdapplications but, so far, no instructions on how to install ESP-IDF have been mentioned. That is because
esp-idf-sys, a crate that all
stdapplications will use, already takes care of installing the necessary ESP-IDF version. By default, this installation will take place under an
.embuildfolder inside the project directory.
espup installhas a
--espidf-versionoption that allows installing the desired ESP-IDF version, see Install subcommand instructions. When using this argument:
ldproxywill be installed if not present already.
- The export file will include the necessary environment variables for ESP-IDF
- When building
stdapplications that use the installed version of ESP-IDF,
esp-idf-syswill recognize there is an activated ESP-IDF environment and will use it instead of downloading and installing it.
- This is very helpful when we want to build several projects with the same ESP-IDF version as it saves time and space.
- Be aware that if you source the environment with an ESP-IDF version and you try to build and
stdapplication that uses a different version it will fail to build.
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:
Espressif provides the idf-rust container image which contains several tags (generated both for
linux/amd64) for every Rust release:
stdapplications, the following naming convention is applied:
esp32s3_v4.4_184.108.40.206contains the ecosystem for developing
stdapplications based on ESP-IDF release/v4.4 for
no_stdapplications, the naming convention is:
esp32_220.127.116.11contains the ecosystem for developing
There is an
<chip> for both
no_std tags that contains the environment required for all the ESP targets.