# EspUp [![Continuous Integration](https://github.com/esp-rs/espup/actions/workflows/ci.yaml/badge.svg)](https://github.com/esp-rs/espup/actions/workflows/ci.yaml) [![Security audit](https://github.com/esp-rs/espup/actions/workflows/audit.yaml/badge.svg)](https://github.com/esp-rs/espup/actions/workflows/audit.yaml) [![Open in Remote - Containers](https://img.shields.io/static/v1?label=Remote%20-%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/esp-rs/espup) > `rustup` for [esp-rs](https://github.com/esp-rs/) `espup` is a tool for installing and maintaining the required toolchains for developing applications in Rust for Espressif SoC's. ## Requirements ### Windows - Python must be installed and the version should be between `3.6` and `3.10`. - Toolchain. Select one of the following: - [Windows x86_64 GNU](https://github.com/esp-rs/rust-build#windows-x86_64-gnu) - [Windows x86_64 MSVC](https://github.com/esp-rs/rust-build#windows-x86_64-msvc) ### Linux - Ubuntu/Debian ```sh 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 libtinfo5 libpython2.7 ``` ## Installation Download the prebuilt binary for your target from the [releases section](https://github.com/esp-rs/espup/releases), or install it with cargo: ```sh cargo install espup --git https://github.com/esp-rs/espup ``` ## Usage ``` Usage: espup 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`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) and [`RUSTUP_HOME`](https://rust-lang.github.io/rustup/environment-variables.html) before running the `install` command. Xtensa Rust toolchain will be installed under `/toolchains/esp`. ``` Usage: espup install [OPTIONS] Options: -e, --espidf-version ESP-IDF version to install. If empty, no esp-idf is installed. Version format: - `commit:`: Uses the commit `` of the `esp-idf` repository. - `tag:`: Uses the tag `` of the `esp-idf` repository. - `branch:`: Uses the branch `` of the `esp-idf` repository. - `v.` or `.`: Uses the tag `v.` of the `esp-idf` repository. - ``: Uses the branch `` of the `esp-idf` repository. -f, --export-file Destination of the generated export file [default: export-esp.sh] -c, --extra-crates Comma or space list of extra crates to install [default: cargo-espflash] -l, --log-level Verbosity level of the logs [default: info] [possible values: debug, info, warn, error] -n, --nightly-version Nightly Rust toolchain version [default: nightly] -m, --profile-minimal Minifies the installation -t, --targets Comma or space separated list of targets [esp32,esp32s2,esp32s3,esp32c3,all] [default: all] -v, --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 ESP-IDF version to uninstall. If empty, no esp-idf is uninsalled. Version format: - `commit:`: Uses the commit `` of the `esp-idf` repository. - `tag:`: Uses the tag `` of the `esp-idf` repository. - `branch:`: Uses the branch `` of the `esp-idf` repository. - `v.` or `.`: Uses the tag `v.` of the `esp-idf` repository. - ``: Uses the branch `` of the `esp-idf` repository. -l, --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 Verbosity level of the logs [default: info] [possible values: debug, info, warn, error] -v, --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 "/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1973, in main(sys.argv[1:]) File "/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1969, in main action_func(args) File "/.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 '['/.espressif\\python_env\\idf4.4_py3.11_env\\Scripts\\python.exe', '-m', 'pip', 'install', '--no-warn-script-location', '-r', /.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](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) - MIT license ([LICENSE-MIT](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.