regexident/rust-build

Installation tools and workflows for deploying/building Rust fork esp-rs/rust with Xtensa and RISC-V support

rust-build

This repository contains:

• workflows for building Rust fork esp-rs/rust with Xtensa support
• binary artifacts in Releases

Table of Contents

• Xtensa Installation
  • Linux and macOS
    • Prerequisites
    • Installation commands
  • Windows x64
    • Prerequisites
    • Installation commands for PowerShell
• RiscV Installation
• Building projects
  • Cargo first approach
  • Idf first approach
• Podman/Docker Rust ESP environment
• Devcontainers

Xtensa Installation

Download installer from Release section: https://github.com/esp-rs/rust-build/releases/tag/v1.61.0.0

Download installer

Download installer in Bash

curl -LO https://github.com/esp-rs/rust-build/releases/download/v1.61.0.0/install-rust-toolchain.sh
chmod a+x install-rust-toolchain.sh

Download installer in PowerShell

Invoke-WebRequest 'https://github.com/esp-rs/rust-build/releases/download/v1.61.0.0/Install-RustToolchain.ps1' -OutFile .\Install-RustToolchain.ps1

Linux and macOS

Following instructions are specific for ESP32 and ESP32-S series based on Xtensa architecture.

Instructions for ESP-C series based on RISC-V architecture are described in RiscV section.

Prerequisites

• Linux:
  • dependencies (command for Ubuntu/Debian):

    apt-get install -y git curl gcc ninja-build cmake libudev-dev \
      python3 python3-pip libusb-1.0-0 libssl-dev pkg-config libtinfo5

No prerequisites are needed for macOS

Installation commands

./install-rust-toolchain.sh

Run ./install-rust-toolchain.sh --help for more information about arguments.

Export variables are displayed at the end of the script.

Windows x64

Following instructions are specific for ESP32 and ESP32-S series based on Xtensa architecture.

Instructions for ESP-C series based on RISC-V architecture are described in RiscV section.

Prerequisites

• Visual Studio - installed with option Desktop development with C++ - components: MSVCv142 - VS2019 C++ x86/64 build tools, Windows 10 SDK

Installation of prerequisites with Chocolatey (run PowerShell as Administrator):

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
choco install cmake git ninja visualstudio2022-workload-vctools windows-sdk-10.0

Installation commands for PowerShell

./Install-RustToolchain.ps1

Export variables are displayed at the end of the output from the script.

Installation of different version of toolchain:

./Install-RustToolchain.sh --toolchain-version 1.61.0.0 --export-file Export-EspRust.ps1
source ./Export-EspRust.ps1

RiscV Installation

Following instructions are specific for ESP32-C based on RiscV architecture.

Install the RISCV target for Rust:

rustup target add riscv32i-unknown-none-elf

Building projects

Cargo first approach

1. Get example source code

   git clone https://github.com/ivmarkov/rust-esp32-std-demo.git
   cd rust-esp32-std-demo/

2. Build and flash:

   cargo espflash --target <TARGET> <SERIAL>

   Where TARGET can be:

   • xtensa-esp32-espidf for the ESP32(Xtensa architecture). [Default]
   • xtensa-esp32s2-espidf for the ESP32-S2(Xtensa architecture).
   • xtensa-esp32s3-espidf for the ESP32-S3(Xtensa architecture).
   • riscv32imc-esp-espidf for the ESP32-C3(RiscV architecture).

   And SERIAL is the serial port connected to the target device.

   cargo-espflash also allows opening a serial monitor after flashing with --monitor option, see Usage section for more information about arguments.

Idf first approach

1. Get example source code

   git clone https://github.com/espressif/rust-esp32-example.git
   cd rust-esp32-example-main

2. Select architecture for the build

   idf.py set-target <TARGET>

   Where TARGET can be:
   • esp32 for the ESP32(Xtensa architecture). [Default]
   • esp32s2 for the ESP32-S2(Xtensa architecture).
   • esp32s3 for the ESP32-S3(Xtensa architecture).
3. Build and flash

   idf.py build flash

Podman/Docker Rust ESP environment

Alternatively, some container images, with pre-installed Rust and ESP-IDF, are published to Dockerhub and can be used to build Rust projects for ESP boards:

• idf-rust - contains only the toolchain.
• idf-rust-examples - includes two examples: rust-esp32-example and rust-esp32-std-demo.

Podman example with mapping multiple /dev/ttyUSB from host computer to the container:

podman run --device /dev/ttyUSB0 --device /dev/ttyUSB1 -it docker.io/espressif/idf-rust-examples

Docker (does not support flashing from container):

docker run -it espressif/idf-rust-examples

If you are using the idf-rust-examples image, instructions will be displayed on the screen.

Devcontainers

There is also the option to integrate with Visual Studio Code using remote containers. With this method, we would have a fully working environment to build projects in Rust for ESP boards in VScode alongside useful settings and extensions, for more information, please, refer to esp-rs-devcontainer.