---
# System prepended metadata

title: Setting Up a Development Environment

---

# 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
