mirror of https://github.com/esp-rs/espup.git synced 2025-09-27 21:01:39 +00:00

Sergio Gasquez 4ce421288a docs: 📝 Update requirements

2022-10-27 12:13:04 +02:00

9.1 KiB

Raw Blame History

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.

Note

This application is still under development and should be considered experimental

Requirements

Before running or installing espup, make sure that rustup and the following dependencies are installed.

Windows

Python. Version should be between 3.6 and 3.10.
git
Toolchain. Select one of the following:
- Windows x86_64 GNU
- Windows x86_64 MSVC

Linux

Ubuntu/Debian

sudo apt-get install -y git python3 python3-pip gcc build-essential curl pkg-config libudev-dev

Fedora

sudo dnf -y install git python3 python3-pip gcc systemd-devel

openSUSE Thumbleweed/Leap

sudo zypper install -y git gcc libudev-devel ninja python3 python3-pip make

Installation

Download the pre-compiled release binaries or using cargo-binstall.

Linux x86_64

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

macOS aarch64

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

macOS x86_64

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

Windows

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

It's also possible to install from source code:

cargo install espup --git https://github.com/esp-rs/espup

Quickstart

See Usage section for more details.

Install

no_std

espup install
# Unix
. ./export-esp.sh
# Windows
.\export-esp.ps1

std: Installing esp-idf via espup is not mandatory, as esp-idf-sys already takes care of it, but has some benefits.
```
espup install --espidf-version <ESPIDF_VERSION>
# Unix
. ./export-esp.sh
# Windows
.\export-esp.ps1
```

Warning

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

Uninstall

  espup uninstall

Update

  espup update --toolchain-version <TOOLCHAIN_VERSION>

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

Installation paths can be modified by setting the environment variables CARGO_HOME and RUSTUP_HOME before running the install command. Xtensa Rust toolchain will be installed under <rustup_home>/toolchains/esp.

Usage: espup install [OPTIONS]

Options:
  -e, --espidf-version <ESPIDF_VERSION>
          ESP-IDF version to install. If empty, no esp-idf is installed. 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.

  -f, --export-file <EXPORT_FILE>
          Destination of the generated export file

          [default: export-esp.sh]

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

          [default: cargo-espflash]

  -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

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

          [default: all]

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

          [default: 1.64.0.0]

  -h, --help
          Print help information (use `-h` for a summary)

Uninstall Subcommand

Usage: espup uninstall [OPTIONS]

Options:
  -e, --espidf-version <ESPIDF_VERSION>
          ESP-IDF version to uninstall. If empty, no esp-idf is uninsalled. 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.

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

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

  -c, --remove-clang
          Removes clang

  -h, --help
          Print help information (use `-h` for a summary)

Update Subcommand

Usage: espup update [OPTIONS]

Options:
  -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 [default: 1.64.0.0]
  -h, --help
          Print help 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:

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.

9.1 KiB Raw Blame History

EspUp

Requirements

Windows

Linux

Installation

Linux x86_64

macOS aarch64

macOS x86_64

Windows

Quickstart

Install

Uninstall

Update

Usage

Install Subcommand

Uninstall Subcommand

Update Subcommand

Known Issues or Limitations

License

Contribution

9.1 KiB

Raw Blame History