itsscb/espup
1
0
Fork 0
mirror of https://github.com/esp-rs/espup.git synced 2025-10-02 23:25:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: 📝 Update readme

Browse Source
This commit is contained in:
Sergio Gasquez 2022-10-03 10:55:27 +00:00
parent 67db330b81
commit 1a86c30fc3
1 changed files with 114 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

225
README.md
View File

@ -1,183 +1,186 @@
# EspUp # EspUp
[![Continuous Integration](https://github.com/SergioGasquez/espup/actions/workflows/ci.yaml/badge.svg)](https://github.com/SergioGasquez/espup/actions/workflows/ci.yaml) [![Continuous Integration](https://github.com/SergioGasquez/espup/actions/workflows/ci.yaml/badge.svg)](https://github.com/SergioGasquez/espup/actions/workflows/ci.yaml)
[![Security audit](https://github.com/SergioGasquez/espup/actions/workflows/audit.yaml/badge.svg)](https://github.com/SergioGasquez/espup/actions/workflows/audit.yaml) [![Security audit](https://github.com/SergioGasquez/espup/actions/workflows/audit.yaml/badge.svg)](https://github.com/SergioGasquez/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/SergioGasquez/espup) [![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/SergioGasquez/espup)
Tool for installing and maintaining ESP Rust toolchain. > `rustup` for [esp-rs](https://github.com/esp-rs/)
> **Warning**
> `espup` is a tool for installing and maintaining the required toolchains for
> This crate is still in early development (See [Known Issues section](#known-issues)). Use at your own risk and, please, report any issues that you find! developing applications in Rust for Espressif SoC's.
## Requirements ## Requirements
### Windows ### Windows
- Python must be installed and the version should be between `3.6` and `3.10`. - 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 ## Installation
Download the prebuilt binary for your target from the [releases section](https://github.com/SergioGasquez/espup/releases), or install it with cargo:
```sh ```sh
cargo install espup --git https://github.com/SergioGasquez/espup cargo install espup --git https://github.com/SergioGasquez/espup
``` ```
## Usage ## Usage
> **Warning** ```
> Usage: espup <COMMAND>
> Only install subcommand is available at the momment.
```sh
USAGE:
espup <SUBCOMMAND>
OPTIONS: Commands:
-h, --help Print help information install Installs esp-rs environment
-V, --version Print version information uninstall Uninstalls esp-rs environment
update Updates Xtensa Rust toolchain
help Print this message or the help of the given subcommand(s)
SUBCOMMANDS: Options:
help Print this message or the help of the given subcommand(s) -h, --help Print help information
install Installs esp-rs environment -V, --version Print version information
uninstall Uninstalls esp-rs environment
update Updates Xtensa Rust toolchain
``` ```
### Install Subcommand ### Install Subcommand
EspUp allows you to customise your installation paths by setting the environment > **Note**
>
> Installation paths can be modified by setting the environment
variables [`CARGO_HOME`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) 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 executable. and [`RUSTUP_HOME`](https://rust-lang.github.io/rustup/environment-variables.html)
before running the `install` command.
Xtensa Rust toolchain will be installed under `<rustup_home>/toolchains/esp`. Xtensa Rust toolchain will be installed under `<rustup_home>/toolchains/esp`.
```sh
USAGE:
espup install [OPTIONS]
OPTIONS:
-c, --extra-crates <EXTRA_CRATES>
Comma or space list of extra crates to install
[default: cargo-espflash] ```
Usage: espup install [OPTIONS]
-e, --espidf-version <ESPIDF_VERSION> Options:
ESP-IDF version to install. If empty, no esp-idf is installed. Version format: -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. - `commit:<hash>`: Uses the commit `<hash>` of the `esp-idf` repository.
- `tag:<tag>`: Uses the tag `<tag>` 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. - `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 - `v<major>.<minor>` or `<major>.<minor>`: Uses the tag `v<major>.<minor>` of the `esp-idf` repository.
`esp-idf` repository.
- `<branch>`: Uses the branch `<branch>` of the `esp-idf` repository. - `<branch>`: Uses the branch `<branch>` of the `esp-idf` repository.
-f, --export-file <EXPORT_FILE> -f, --export-file <EXPORT_FILE>
Destination of the generated export file Destination of the generated export file
[default: export-esp.sh] [default: export-esp.sh]
-h, --help -c, --extra-crates <EXTRA_CRATES>
Print help information Comma or space list of extra crates to install
-l, --log-level <LOG_LEVEL> [default: cargo-espflash]
Verbosity level of the logs
[default: info] -l, --log-level <LOG_LEVEL>
[possible values: debug, info, warn, error] Verbosity level of the logs
-m, --profile-minimal [default: info]
Minifies the installation [possible values: debug, info, warn, error]
-n, --nightly-version <NIGHTLY_VERSION> -n, --nightly-version <NIGHTLY_VERSION>
Nightly Rust toolchain version Nightly Rust toolchain version
[default: nightly] [default: nightly]
-t, --targets <TARGETS> -m, --profile-minimal
Comma or space separated list of targets [esp32,esp32s2,esp32s3,esp32c3,all] Minifies the installation
[default: all] -t, --targets <TARGETS>
Comma or space separated list of targets [esp32,esp32s2,esp32s3,esp32c3,all]
-v, --toolchain-version <TOOLCHAIN_VERSION> [default: all]
Xtensa Rust toolchain version
[default: 1.64.0.0] -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 ### Uninstall Subcommand
```sh ```
USAGE: Usage: espup uninstall [OPTIONS]
espup uninstall [OPTIONS]
OPTIONS: Options:
-c, --remove-clang -e, --espidf-version <ESPIDF_VERSION>
Removes clang ESP-IDF version to uninstall. If empty, no esp-idf is uninsalled. Version format:
-e, --espidf-version <ESPIDF_VERSION> - `commit:<hash>`: Uses the commit `<hash>` of the `esp-idf` repository.
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.
- `tag:<tag>`: Uses the tag `<tag>` of the `esp-idf` repository. - `branch:<branch>`: Uses the branch `<branch>` 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.
- `v<major>.<minor>` or `<major>.<minor>`: Uses the tag `v<major>.<minor>` of the - `<branch>`: Uses the branch `<branch>` of the `esp-idf` repository.
`esp-idf` repository.
- `<branch>`: Uses the branch `<branch>` of the `esp-idf` repository. -l, --log-level <LOG_LEVEL>
Verbosity level of the logs
-h, --help [default: info]
Print help information [possible values: debug, info, warn, error]
-l, --log-level <LOG_LEVEL> -c, --remove-clang
Verbosity level of the logs Removes clang
[default: info] -h, --help
[possible values: debug, info, warn, error] Print help information (use `-h` for a summary)
``` ```
### Update Subcommand ### Update Subcommand
```sh ```
USAGE: Usage: espup update [OPTIONS]
espup update [OPTIONS]
OPTIONS: Options:
-h, --help -l, --log-level <LOG_LEVEL>
Print help information Verbosity level of the logs [default: info] [possible values: debug, info, warn, error]
-v, --toolchain-version <TOOLCHAIN_VERSION>
-l, --log-level <LOG_LEVEL> Xtensa Rust toolchain version [default: 1.64.0.0]
Verbosity level of the logs [default: info] [possible values: debug, info, warn, error] -h, --help
Print help information
-v, --toolchain-version <TOOLCHAIN_VERSION>
Xtensa Rust toolchain version [default: 1.64.0.0]
``` ```
## Known Issues ## Known Issues or Limitations
- When installing esp-idf in Windows, only `all` targets is wokring. If you try to install - If installing esp-idf in Windows, only `all` targets is allowed.
any esp-idf version for any target combination that does not include all of them, you will - In Windows, when installing esp-idf fails with:
have issues activating the environment. ```
ERROR: Could not find a version that satisfies the requirement windows-curses; sys_platform == "win32" (from esp-windows-curses) (from versions: none)
## Troubleshooting ERROR: No matching distribution found for windows-curses; sys_platform == "win32"
Traceback (most recent call last):
- In Windows, when installing esp-idf fails with File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1973, in <module>
``` main(sys.argv[1:])
ERROR: Could not find a version that satisfies the requirement windows-curses; sys_platform == "win32" (from esp-windows-curses) (from versions: none) File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1969, in main
ERROR: No matching distribution found for windows-curses; sys_platform == "win32" action_func(args)
Traceback (most recent call last): File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1619, in action_install_python_env
File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1973, in <module> subprocess.check_call(run_args, stdout=sys.stdout, stderr=sys.stderr, env=env_copy)
main(sys.argv[1:]) File "C:\Python311\Lib\subprocess.py", line 413, in check_call
File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1969, in main raise CalledProcessError(retcode, cmd)
action_func(args) 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.
File "<home_dir>/.espressif\esp-idf-ae062fbba3ded0aa\release-v4.4\tools\idf_tools.py", line 1619, in action_install_python_env Error: Could not install esp-idf
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 *_Solution_*: Use a python version between `3.6` and `3.10` as `3.11` Python wheels are not yet released for Windows.
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_*: This is due to python `3.11` being used. Use a python version between `3.6` and `3.10`
## License ## License