espup 0.2.7

Tool for installing and maintaining ESP Rust environment.
Documentation

espup

Crates.io MSRV Continuous Integration Security audit Matrix

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 the following dependencies are installed.

Windows

  • git.
  • Python: Only required when installing ESP-IDF.

Linux

  • Ubuntu/Debian 
    sudo apt-get install -y git python3 python3-pip gcc build-essential curl pkg-config libudev-dev
    • libudev-dev is only required when installing cargo-espflash.
    • python3 and python3-pip are only required when installing ESP-IDF.
  • Fedora 
    sudo dnf -y install git python3 python3-pip perl gcc systemd-devel
    • systemd-devel is only required when installing cargo-espflash.
    • python3 and python3-pip are only required when installing ESP-IDF.
    • perl is required to build openssl-sys
  • openSUSE Thumbleweed/Leap 
    sudo zypper install -y git gcc libudev-devel ninja python3 python3-pip make
    • libudev-devel is only required when installing cargo-espflash.
    • python3 and python3-pip are only required when installing ESP-IDF.

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
%USERPROFILE%\export-esp.ps1

Warning

The generated export file, by default export-esp, needs to be sourced in every terminal before building an application.

Note

The export file can be regenerated by running espup install again, in this case, it won't install the components again as it would detect the current installation and reuse it. The -p/--config-path option can be used to determine where to regenerate the export file.

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, Xtensa Rust toolchain will be installed under <rustup_home>/toolchains/esp.

Note

ESP-IDF instalation

When building std applications, ESP-IDF is required, there are two ways of installing it:

  • Using esp-idf-sys, a crate that all std applications require (and its already included in our esp-idf-template).
    • We reccomend using this approach as its easier (you dont have to deal with ESP-IDF instalaltion and sourcing), and its more flexible.
  • Using espup. espup install has a -e/--esp-idf-version option that allows installing the desired ESP-IDF version. When using this argument:
    • ldproxy, a tool required for all std projects, will be installed if not present already.
    • The generated export file will include the necessary environment variables for ESP-IDF
    • When building std applications that use the installed version of ESP-IDF, esp-idf-sys will recognize there is an activated ESP-IDF environment and will use it instead of downloading and installing it.
      • This is very helpful when we want to build several projects with the same ESP-IDF version as it saves time and space.
      • Be aware that if you source the environment with an ESP-IDF version and you try to build and std application that uses a different version it will fail to build.
Usage: espup install [OPTIONS]

Options:
 -p, --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]

  -e, --esp-idf-version <ESP_IDF_VERSION>
          ESP-IDF version to install. If empty, no ESP-IDF is installed. ESP-IDF installation can also be managed by esp-idf-sys(https://github.com/esp-rs/esp-idf-sys).

          Version format:

          - `commit:<hash>`: Uses the commit `<hash>` of the `esp-idf` repository.

          - `tag:<tag>`: Uses the tag `<tag>` of the `esp-idf` repository.

          - `branch:<branch>`: Uses the branch `<branch>` of the `esp-idf` repository.

          - `v<major>.<minor>` or `<major>.<minor>`: Uses the tag `v<major>.<minor>` of the `esp-idf` repository.

          - `<branch>`: Uses the branch `<branch>` of the `esp-idf` repository.

          When using this option, `ldproxy` crate will also be installed.

  -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)

  -c, --extra-crates <EXTRA_CRATES>
          Comma or space list of extra crates to install

  -x, --llvm-version <LLVM_VERSION>
          LLVM version

          [default: 15]
          [possible values: 15]

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

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

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

          [default: nightly]

  -m, --profile-minimal
          Minifies the installation.

          This will install a reduced version of LLVM, delete the folder where all the assets are downloaded, and, if installing ESP-IDF, delete some unnecessary folders like docs and examples.

  -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 information (use `-h` for a summary)

  -V, --version
          Print version information

Uninstall Subcommand

Usage: espup uninstall [OPTIONS]

Options:
  -p, --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]
  -h, --help                   Print help information
  -V, --version                Print version information

Update Subcommand

Usage: espup update [OPTIONS]

Options:
  -p, --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]
  -v, --toolchain-version <TOOLCHAIN_VERSION>
          Xtensa Rust toolchain version
  -h, --help
          Print help information
  -V, --version
          Print version information

Known Issues or Limitations

  • If installing esp-idf in Windows, only all targets is allowed.
  • In Windows, when installing esp-idf fails with: 
    ERROR: Could not find a version that satisfies the requirement windows-curses; sys_platform == "win32" (from esp-windows-curses) (from versions: none)
ERROR: No matching distribution found for windows-curses; sys_platform == "win32"
Traceback (most recent call last):
        File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1973, in <module>
main(sys.argv[1:])
        File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1969, in main
action_func(args)
        File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1619, in action_install_python_env
subprocess.check_call(run_args, stdout=sys.stdout, stderr=sys.stderr, env=env_copy)
        File "C:\Python311\Lib\subprocess.py", line 413, in check_call
raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['<home_dir>/.espressif\\python_env\\idf4.4_py3.11_env\\Scripts\\python.exe', '-m', 'pip', 'install', '--no-warn-script-location', '-r', <home_dir>/.espressif\\esp-idf-ae062fbba3ded0aa\\release-v4.4\\requirements.txt', '--extra-index-url', 'https://dl.espressif.com/pypi']' returned non-zero exit status 1.
Error: Could not install esp-idf
    Solution: Use a python version between 3.6 and 3.10 as 3.11 Python wheels are not yet released for Windows.

License

Licensed under either of:

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.