espup

rustup for esp-rs

espup is a tool for installing and maintaining the required toolchains for developing applications in Rust for Espressif SoC's.

To better understand what espup installs, see Rust on ESP targets chapter of The Rust on ESP Book

Requirements

Before running or installing espup, make sure that rustup is installed. Linux systems also require the following packages:

• Ubuntu/Debian

  sudo apt-get install -y gcc build-essential curl pkg-config
  

• Fedora

  sudo dnf -y install perl gcc
  

  • perl is required to build openssl-sys
• openSUSE Thumbleweed/Leap

  sudo zypper install -y gcc ninja make
  

Installation

cargo install espup

It's also possible to use cargo-binstall or to directly download the pre-compiled release binaries:

• Linux aarch64

  curl -L https://github.com/esp-rs/espup/releases/latest/download/espup-aarch64-unknown-linux-gnu -o espup
  chmod a+x espup
  

• Linux x86_64

  curl -L https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-unknown-linux-gnu -o espup
  chmod a+x espup
  

• macOS aarch64

  curl -L https://github.com/esp-rs/espup/releases/latest/download/espup-aarch64-apple-darwin -o espup
  chmod a+x espup
  

• macOS x86_64

  curl -L https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-apple-darwin -o espup
  chmod a+x espup
  

• Windows MSVC

  Invoke-WebRequest 'https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-pc-windows-msvc.  exe' -OutFile .\espup.exe
  

Quickstart

See Usage section for more details.

Install

espup install
# Unix
. $HOME/export-esp.sh
# Windows does not require sourcing any file

Warning

The generated export file, by default export-esp, needs to be sourced in every terminal in Unix systems before building an application. In Windows, environment variables are automatically injected into your system and don't need to be sourced.

Uninstall

espup uninstall

Update

espup update

Usage

Usage: espup <COMMAND>

Commands:
  install    Installs esp-rs environment
  uninstall  Uninstalls esp-rs environment
  update     Updates Xtensa Rust toolchain
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help information
  -V, --version  Print version information

Install Subcommand

Note

Xtensa Rust destination path

Installation paths can be modified by setting the environment variables CARGO_HOME and RUSTUP_HOME before running the install command. By default, toolchains will be installed under <rustup_home>/toolchains/esp, although this can be changed using the -a/--name option.

Usage: espup install [OPTIONS]

Options:
  -c, --config-path <CONFIG_PATH>
          Path to where the espup configuration file will be written to

  -d, --default-host <DEFAULT_HOST>
          Target triple of the host

          [possible values: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-pc-windows-msvc, x86_64-pc-windows-gnu, x86_64-apple-darwin, aarch64-apple-darwin]

  -f, --export-file <EXPORT_FILE>
          Relative or full path for the export file that will be generated. If no path is provided, the file will be generated under home directory (https://docs.rs/dirs/latest/dirs/fn.home_dir.html)

  -e, --extended-llvm
          Extends the LLVM installation.

          This will install the whole LLVM instead of only installing the libs.

  -l, --log-level <LOG_LEVEL>
          Verbosity level of the logs

          [default: info]
          [possible values: debug, info, warn, error]

  -a, --name <NAME>
          Xtensa Rust toolchain name

          [default: esp]

  -n, --nightly-version <NIGHTLY_VERSION>
          Nightly Rust toolchain version

          [default: nightly]

  -s, --std
          Only install toolchains required for STD applications.

          With this option, espup will skip GCC installation (it will be handled by esp-idf-sys), hence you won't be able to build no_std applications.

  -t, --targets <TARGETS>
          Comma or space separated list of targets [esp32,esp32s2,esp32s3,esp32c2,esp32c3,all]

          [default: all]

  -v, --toolchain-version <TOOLCHAIN_VERSION>
          Xtensa Rust toolchain version

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Uninstall Subcommand

Usage: espup uninstall [OPTIONS]

Options:
  -c, --config-path <CONFIG_PATH>  Path to where the espup configuration file will be written to
  -l, --log-level <LOG_LEVEL>      Verbosity level of the logs [default: info] [possible values: debug, info, warn, error]
  -a, --name <NAME>                Xtensa Rust toolchain name [default: esp]
  -h, --help                       Print help
  -V, --version                    Print version

Update Subcommand

Usage: espup update [OPTIONS]

Options:
  -c, --config-path <CONFIG_PATH>
          Path to where the espup configuration file will be written to
  -d, --default-host <DEFAULT_HOST>
          Target triple of the host [possible values: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-pc-windows-msvc, x86_64-pc-windows-gnu, x86_64-apple-darwin, aarch64-apple-darwin]
  -l, --log-level <LOG_LEVEL>
          Verbosity level of the logs [default: info] [possible values: debug, info, warn, error]
  -a, --name <NAME>
          Xtensa Rust toolchain name [default: esp]
  -v, --toolchain-version <TOOLCHAIN_VERSION>
          Xtensa Rust toolchain version
  -h, --help
          Print help
  -V, --version
          Print version

License

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.

Contribution

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.