↓Skip to main content
IT Blog IT Blog
  1. All Posts/

rust-build

Tools Shell

rust-build

This repository contains:

  • Workflows for building a Rust fork esp-rs/rust with Xtensa support
  • Binary artifacts in Releases
  • An installation script to locally install a pre-compiled nightly ESP32 toolchain

If you want to know more about the Rust ecosystem on ESP targets, see The Rust on ESP Book chapter

Table of Contents

  • rust-build

    • Table of Contents
    • Xtensa Installation

      • Download installer

        •       <li>
        <a rel="nofollow noopener" target="_blank" href="#linux-and-macos">Linux and macOS</a></p> <ul dir="auto">
          <li>
            <a rel="nofollow noopener" target="_blank" href="#prerequisites">Prerequisites</a>
          </li>
          <li>
            <a rel="nofollow noopener" target="_blank" href="#installation-commands">Installation commands</a>
          </li>
          <li>
            <a rel="nofollow noopener" target="_blank" href="#set-up-the-environment-variables">Set up the environment variables</a>
          </li>
          <li>
            <a rel="nofollow noopener" target="_blank" href="#arguments">Arguments</a>
          </li>
        </ul>
      </li>
      
      <li>
        <a rel="nofollow noopener" target="_blank" href="#windows-x86_64-gnu">Windows x86_64 GNU</a></p> <ul dir="auto">
          <li>
            <a rel="nofollow noopener" target="_blank" href="#prerequisites-x86_64-gnu">Prerequisites x86_64 GNU</a>
          </li>
          <li>
            <a rel="nofollow noopener" target="_blank" href="#installation-commands-for-powershell">Installation commands for PowerShell</a>
          </li>
          <li>
            <a rel="nofollow noopener" target="_blank" href="#long-path-limitation">Long path limitation</a>
          </li>
        </ul>
      </li>
      
      <li>
        <a rel="nofollow noopener" target="_blank" href="#windows-x86_64-msvc">Windows x86_64 MSVC</a></p> <ul dir="auto">
          <li>
            <a rel="nofollow noopener" target="_blank" href="#prerequisites-x86_64-msvc">Prerequisites x86_64 MSVC</a>
          </li>
          <li>
            <a rel="nofollow noopener" target="_blank" href="#installation-commands-for-powershell-1">Installation commands for PowerShell</a>
          </li>
          <li>
            <a rel="nofollow noopener" target="_blank" href="#set-up-the-environment-variables-1">Set up the environment variables</a>
          </li>
          <li>
            <a rel="nofollow noopener" target="_blank" href="#long-path-limitation-1">Long path limitation</a>
          </li>
        </ul>
      </li>
    </ul>
  </li>
  
  <li>
    <a rel="nofollow noopener" target="_blank" href="#risc-v-installation">RISC-V Installation</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#building-projects">Building projects</a></p> <ul dir="auto">
      <li>
        <a rel="nofollow noopener" target="_blank" href="#cargo-first-approach">Cargo first approach</a>
      </li>
      <li>
        <a rel="nofollow noopener" target="_blank" href="#idf-first-approach">Idf first approach</a>
      </li>
    </ul>
  </li>
  
  <li>
    <a rel="nofollow noopener" target="_blank" href="#using-containers">Using Containers</a>
  </li>
  <li>
    <a rel="nofollow noopener" target="_blank" href="#using-dev-containers">Using Dev Containers</a>
  </li>
</ul>

      Xtensa Installation

      Warning
      Install scripts from this repository will now be feature freeze. New features will be added to espup, a Rust version of the install scripts.

      Download the installer from the Release section.

      Download installer

      Download installer in Bash 

      curl -LO https://github.com/esp-rs/rust-build/releases/download/v1.66.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.66.0.0/Install-RustToolchain.ps1' -OutFile .Install-RustToolchain.ps1

      Linux and macOS

      The following instructions are specific for the ESP32 and ESP32-S series based on Xtensa architecture.
      Instructions for ESP-C series based on RISC-V architecture are described in RISC-V section.

      Prerequisites

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

          apt-get install -y git curl gcc clang ninja-build cmake libudev-dev unzip xz-utils 
python3 python3-pip python3-venv libusb-1.0-0 libssl-dev pkg-config libpython2.7

      No prerequisites are needed for macOS.

      Installation commands 

      git clone https://github.com/esp-rs/rust-build.git
cd rust-build
./install-rust-toolchain.sh
. ./export-esp.sh

      Run ./install-rust-toolchain.sh --help for more information about arguments.
      Installation of different version of the toolchain:

      ./install-rust-toolchain.sh --toolchain-version 1.66.0.0
. ./export-esp.sh

      Set up the environment variables

      We need to update environment variables as some of the installed tools are not
      yet added to the PATH environment variable, we also need to add LIBCLANG_PATH
      environment variable to avoid conflicts with the system Clang. The environment
      variables that we need to update are shown at the end of the install script and
      stored in an export file. By default this export file is export-esp.sh but can
      be modified with the -f|--export-file argument.
      We must set the environment variables in every terminal session.

      Note
      If the export variables are added to the shell startup script, the shell may need to be refreshed.

      Arguments

      • -b|--build-target: Comma separated list of targets [esp32,esp32s2,esp32s3,esp32c3,all]. Defaults to: esp32,esp32s2,esp32s3
      • -c|--cargo-home: Cargo path.
      • -d|--toolchain-destination: Toolchain installation folder. Defaults to: <rustup_home>/toolchains/esp
      • -e|--extra-crates: Extra crates to install. Defaults to: ldproxy cargo-espflash
      • -f|--export-file: Destination of the export file generated. Defaults to: export-esp.sh
      • -i|--installation-mode: Installation mode: [install, reinstall, uninstall]. Defaults to: install
      • -k|--minified-llvm: Use minified LLVM. Possible values: [YES, NO]. Defaults to: YES
      • -l|--llvm-version: LLVM version.
      • -m|--minified-esp-idf: [Only applies if using -s|--esp-idf-version]. Deletes some idf folders to save space. Possible values [YES, NO]. Defaults to: NO
      • -n|--nightly-version: Nightly Rust toolchain version. Defaults to: nightly
      • -r|--rustup-home: Path to .rustup. Defaults to: ~/.rustup
      • -s|--esp-idf-version: ESP-IDF branch to install. When empty, no esp-idf is installed. Default: ""
      • -t|--toolchain-version: Xtensa Rust toolchain version
      • -x|--clear-cache: Removes cached distribution files. Possible values: [YES, NO]. Defaults to: YES

      Windows x86_64 GNU

      The following instructions describe deployment with the GNU toolchain. If you’re using Visual Studio with Windows 10 SDK, consider option Windows x86_64 MSVC.

      Prerequisites x86_64 GNU

      Install MinGW x86_64 e.g., from releases https://github.com/niXman/mingw-builds-binaries/releases and add bin to environment variable PATH

      choco install 7zip -y
Invoke-WebRequest https://github.com/niXman/mingw-builds-binaries/releases/download/12.1.0-rt_v10-rev3/x86_64-12.1.0-release-posix-seh-rt_v10-rev3.7z -OutFile x86_64-12.1.0-release-posix-seh-rt_v10-rev3.7z
7z e x86_64-12.1.0-release-posix-seh-rt_v10-rev3.7z
$env:PATH+=";.....x86_64-12.1.0-release-posix-seh-rt_v10-rev3mingw64bin"

      Install ESP-IDF using Windows installer https://dl.espressif.com/dl/esp-idf/

      Installation commands for PowerShell

      Activate ESP-IDF PowerShell and enter following command:

      git clone https://github.com/esp-rs/rust-build.git
cd rust-build
./Install-RustToolchain.ps1 -DefaultHost x86_64-pc-windows-gnu -ExportFile Export-EspRust.ps1
. ./Export-EspRust.ps1

      Long path limitation

      Several build tools have problem with long paths on Windows including Git and CMake. We recommend to put project on short path or use command subst to map the directory with the project to separate disk letter.

      subst "R:" "rust-project"

      Windows x86_64 MSVC

      The following instructions are specific for the ESP32 and ESP32-S series based on Xtensa architecture. If you do not have Visual Studio and Windows 10 SDK installed, consider the alternative option Windows x86_64 GNU.
      Instructions for ESP-C series based on RISC-V architecture are described in RISC-V section.

      Prerequisites x86_64 MSVC

      Installation of prerequisites using Winget:

      winget install --id Git.Git
winget install Python # requirements for ESP-IDF based development, skip in case of Bare metal
winget install -e --id Microsoft.WindowsSDK
winget install Microsoft.VisualStudio.2022.BuildTools --silent --override "--wait --quiet --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64"

      Installation of prerequisites using Visual Studio installer GUI – installed with option Desktop development with C++ – components: MSVCv142 – VS2019 C++ x86/64 build tools, Windows 11 SDK

      Installation of MSVC and Windows 11 SDK using vs_buildtools.exe:

      Invoke-WebRequest 'https://aka.ms/vs/17/release/vs_buildtools.exe' -OutFile .vs_buildtools.exe
.vs_BuildTools.exe --passive --wait --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows10SDK.20348

      Installation of prerequisites using 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 visualstudio2022-workload-vctools windows-sdk-10.0 -y
choco install cmake git ninja python3 -y  # requirements for ESP-IDF based development, skip in case of Bare metal

      Installation commands for PowerShell 

      git clone https://github.com/esp-rs/rust-build.git
cd rust-build
./Install-RustToolchain.ps1

      Export variables are displayed at the end of the output from the script.
      Installation of different versions of toolchain:

      ./Install-RustToolchain.ps1 -ToolchainVersion 1.66.0.0
. ./Export-EspRust.ps1

      Set up the environment variables

      We need to update environment variables as some of the installed tools are not
      yet added to the PATH environment variable, we also need to add LIBCLANG_PATH
      environment variable to avoid conflicts with the system Clang. The environment
      variables that we need to update are stored in an export file. By default this
      export file is Export-EspRust.ps1 but can…



↑