Need help? Join the esp-rs room on matrix, https://matrix.to/#/#esp-rs:matrix.org.

ESP32 and ESP8266 chips come with one or two Xtensa CPUs, which (unlike x86 or ARM) are not supported by the official Rust compiler.

These instructions describe how to build Rust compiler (from LLVM and rustc) that supports Xtensa architecture, as well as how to build and flash blinking LED program to the ESP32.

Building Rust compiler is CPU and memory intense process. The compilation can take up to 15 minutes on higher-grade CPUs and even several hours on resource-starved VMs. Besides that, the compilation may fail on systems with less than 6GB of RAM.

The required software components and resulting artefacts can take up to 10GB of disk space.

Make sure you have a working copy of rust already installed. If not, follow the Install Rust instructions.

The fork now uses the xtensa enabled fork as its llvm submodule, so its now possible to build the entire toolchain in a few commands.

All that is required to build rustc for linux is the steps below.

$ git clone --depth 1 --recurse-submodules --shallow-submodules https://github.com/MabezDev/rust-xtensa
$ cd rust-xtensa
$ ./configure --experimental-targets=Xtensa
$ ./x.py build --stage 2

(The "shallow" git clone command above will save about 50% in storage space and download size over a full clone. If you plan on developing rust-xtensa itself,

$ git clone --recurse-submodules https://github.com/MabezDev/rust-xtensa

will give you the entire history of the repo and its subprojects.)

Before cross-compiling an xtensa target, you must set the following vars, which are set in the setenv script in this project:

XARGO_RUST_SRC=/path/to/rust-xtensa/library
RUSTC=/path/to/rust-xtensa/build/x86_64-unknown-linux-gnu/stage2/bin/rustc

After making sure you have Visual Studio Community and python3 installed, in a cmd.exe run:

$ git clone https://github.com/MabezDev/rust-xtensa
$ cd rust-xtensa
$ CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
$ python3 src/bootstrap/configure.py --experimental-targets=Xtensa
$ python3 x.py build --stage 2

Before cross-compiling an xtensa target, you must set the following vars either for your system or within your IDE:

XARGO_RUST_SRC=\path\to\rust-xtensa\library
RUSTC=\path\to\rust-xtensa\build\x86_64-pc-windows-msvc\stage2\bin\rustc

If you would like to build the llvm fork separately, follow the instructions below.

If you don't have them already, you'll first have to install ninja-build and a C++ compiler (such as g++). Please refer to LLVM project for more information.

$ git clone https://github.com/MabezDev/llvm-project
$ cd llvm-project/llvm
$ mkdir build
$ cd build
$ cmake .. -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD="Xtensa" -DCMAKE_BUILD_TYPE=Release -G "Ninja"
$ cmake --build .

Please refer to the rust-xtensa project for authoratative instructions.

Assuming you built llvm in your home directory:

$ git clone https://github.com/MabezDev/rust-xtensa
$ cd rust-xtensa
$ ./configure --llvm-root=$HOME/llvm-project/llvm/build
$ ./x.py build

Instructions can be found on Espressif's web site and the latest tool toolchain can be downloaded from here.

Extract it to the directory of your choice. Then add the toolchain's bin/ directory to your $PATH. For example:

$ mkdir ~/esp
$ tar -xzf ~/Downloads/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-linux-amd64.tar.gz -C ~/esp
$ PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"

Old instructions can be found on Espressif's web site.

Install the xtensa-lx106-elf toolchain from the espressif web site.

$ mkdir ~/esp
$ tar -xzf ~/Downloads/xtensa-lx106-elf-linux64-1.22.0-100-ge567ec7-5.2.0.tar.gz -C ~/esp
$ PATH="$PATH:$HOME/esp/xtensa-lx106-elf/bin"

Run

$ cargo install cargo-xbuild

The preferred method of flashing is to use cargo-espflash. Otherwise you will have to invoke Espressif's esptool.py to flash the binaries manually.

    $ cargo install cargo-espflash

Esptool is python-based command line tool for flashing ESP32 and ESP8266 chips. Full installation instructions are available on the website, but it's usually as straightforward as:

Python alternative:

    $ pip install esptool

    $ git clone https://github.com/MabezDev/xtensa-rust-quickstart

By default this code blinks using GPIO #2. Edit the code under examples/esp32.rs or examples/esp8266.rs to change the port as required.

For example:

let mut led = pins.gpio13.into_push_pull_output();

Update CUSTOM_RUSTC in setenv to point to the version of rust you compiled earlier. Then load the environment variables with:

$ source setenv

Note: Flash operation will also conduct a build.

cargo xbuild --features="xtensa-lx-rt/lx6,xtensa-lx/lx6,esp32-hal"

Example for the ESP32, remember to use target = xtensa-esp32-none-elf inside .cargo/config:

$ cargo espflash --chip esp32 --example esp32 --speed 460800 --features="xtensa-lx-rt/lx6,xtensa-lx/lx6,esp32-hal" /dev/ttyUSB0

Example for the ESP8266, remember to use target = xtensa-esp8266-none-elf inside .cargo/config:

$ cargo espflash --chip esp8266 --example esp8266 --features="xtensa-lx-rt/lx106 xtensa-lx/lx106 esp8266-hal" /dev/ttyUSB0

• The esp-rs organization has been formed to develop runtime, pac and hal crates for the esp32 and eventually esp8266.
• Checkout @lexxvir's project for an example of using the esp-idf bindings in a Rust application.

• error: intermittent IO error while iterating directory - try creating that directory
• undefined reference to .L see this issue

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.