docs: update installation instructions for 1.54.0 (#20)

* docs: update installation instructions for 1.54.0 * docker: publish idf-rust image under Espressif account
2021-08-12 08:16:13 +02:00 · 2021-08-12 08:16:13 +02:00 · d6f26b645b
parent ff5909f466
commit d6f26b645b
7 changed files with 200 additions and 66 deletions
--- a/.github/workflows/publish-esp-idf-rust-image.yml
+++ b/.github/workflows/publish-esp-idf-rust-image.yml
@ -19,4 +19,4 @@ jobs:
        with:
          context: .
          push: true
-          tags: georgikrocks/esp-idf-rust:latest
+          tags: espressif/idf-rust:latest
--- a/25
+++ b/25
@ -6,22 +6,29 @@ ENV LANG=C.UTF-8
 ENV RUSTUP_HOME=/opt/rust
 ENV CARGO_HOME=/opt/cargo
 ENV PATH=/opt/cargo/bin:/opt/rust/bin:/opt/xtensa-esp32-elf-clang/bin:$PATH
+
+ARG VERSION="1.54.0-dev"
+ARG ARCH="x86_64-unknown-linux-gnu"
+ARG RUST_DIST="rust-${VERSION}-${ARCH}"
+ARG RUST_SRC_DIST="rust-src-${VERSION}"
+ARG TOOLCHAIN_DESTINATION_DIR="/opt/esp"
+
 RUN curl https://sh.rustup.rs -sSf | bash -s -- --profile minimal --default-toolchain nightly  -y
 WORKDIR /opt

-RUN wget -q https://dl.espressif.com/dl/idf-rust/dist/x86_64-unknown-linux-gnu/rust-1.53.0-dev-x86_64-unknown-linux-gnu.tar.xz \
-    && tar xvf rust-1.53.0-dev-x86_64-unknown-linux-gnu.tar.xz \
-    && ./rust-1.53.0-dev-x86_64-unknown-linux-gnu/install.sh --destdir=/opt/esp --prefix="" --without=rust-docs \
-    && rm -rf rust-1.53.0-dev-x86_64-unknown-linux-gnu*
+RUN wget -q https://dl.espressif.com/dl/idf-rust/dist/${ARCH}/${RUST_DIST}.tar.xz \
+    && tar xvf ${RUST_DIST}.tar.xz \
+    && ./${RUST_DIST}/install.sh --destdir=${TOOLCHAIN_DESTINATION_DIR} --prefix="" --without=rust-docs \
+    && rm -rf ${RUST_DIST} ${RUST_DIST}.tar.xz

-RUN wget -q https://dl.espressif.com/dl/idf-rust/dist/noarch/rust-src-1.53.0-dev.tar.xz \
-    && tar xvf rust-src-1.53.0-dev.tar.xz \
-    && ./rust-src-1.53.0-dev/install.sh --destdir=/opt/esp --prefix="" --without=rust-docs \
-    && rm -rf rust-src-1.53.0-dev* \
+RUN wget -q https://dl.espressif.com/dl/idf-rust/dist/noarch/${RUST_SRC_DIST}.tar.xz \
+    && tar xvf ${RUST_SRC_DIST}.tar.xz \
+    && ./${RUST_SRC_DIST}/install.sh --destdir=${TOOLCHAIN_DESTINATION_DIR} --prefix="" --without=rust-docs \
+    && rm -rf ${RUST_SRC_DIST} ${RUST_SRC_DIST}.tar.xz \
    && rustup toolchain link esp /opt/esp \
    && rustup default esp

-RUN wget -q https://dl.espressif.com/dl/idf-rust/dist/x86_64-unknown-linux-gnu/xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-linux-amd64.tar.xz \
+RUN wget -q https://dl.espressif.com/dl/idf-rust/dist/${ARCH}/xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-linux-amd64.tar.xz \
    && tar xf xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-linux-amd64.tar.xz \
    && rm xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-linux-amd64.tar.xz

--- a/docs/rust-on-xtensa-installation-aarch64-apple-darwin.md
+++ b/docs/rust-on-xtensa-installation-aarch64-apple-darwin.md
@ -1,35 +1,69 @@
 # Rust on Xtensa Installation for macOS M1

+Following instructions are specific for ESP32 and ESP32-S series based on Xtensa architecture.
+
+Instructions for ESP-C series based on RISC-V architecture are described in document for [ESP32-C3](../README.md#esp32-c3).
+
 Tested OS: macOS Big Sur M1

 ## Prerequisites

 - rustup - https://rustup.rs/

-## Commands
+## Installation commands

-```
+```sh
 rustup toolchain install nightly

-mkdir -p ~/.rustup/toolchains/esp
+VERSION="1.54.0-dev"
+ARCH="aarch64-apple-darwin"
+RUST_DIST="rust-${VERSION}-${ARCH}"
+RUST_SRC_DIST="rust-src-${VERSION}"
+TOOLCHAIN_DESTINATION_DIR="~/.rustup/toolchains/esp"

-wget --continue https://dl.espressif.com/dl/idf-rust/dist/aarch64-apple-darwin/rust-1.53.0-dev-aarch64-apple-darwin.tar.xz
-tar xvf rust-1.53.0-dev-aarch64-apple-darwin.tar.xz
-./rust-1.53.0-dev-aarch64-apple-darwin/install.sh --destdir=~/.rustup/toolchains/esp --prefix="" --without=rust-docs
+mkdir -p ${TOOLCHAIN_DESTINATION_DIR}

-wget --continue https://dl.espressif.com/dl/idf-rust/dist/noarch/rust-src-1.53.0-dev.tar.xz
-tar xvf rust-src-1.53.0-dev.tar.xz
-./rust-src-1.53.0-dev/install.sh --destdir=~/.rustup/toolchains/esp --prefix=""
+wget "https://dl.espressif.com/dl/idf-rust/dist/${ARCH}/${RUST_DIST}.tar.xz"
+tar xvf ${RUST_DIST}.tar.xz
+./${RUST_DIST}/install.sh --destdir=${TOOLCHAIN_DESTINATION_DIR} --prefix="" --without=rust-docs
+
+wget "https://dl.espressif.com/dl/idf-rust/dist/noarch/${RUST_SRC_DIST}.tar.xz"
+tar xvf ${RUST_SRC_DIST}.tar.xz
+./${RUST_SRC_DIST}/install.sh --destdir=${TOOLCHAIN_DESTINATION_DIR} --prefix="" --without=rust-docs

 rustup default esp

-wget --continue https://dl.espressif.com/dl/idf-rust/dist/aarch64-apple-darwin/xtensa-esp32-elf-llvm11_0_0-aarch64-apple-darwin.tar.xz
+wget --continue "https://dl.espressif.com/dl/idf-rust/dist/${ARCH}/xtensa-esp32-elf-llvm11_0_0-aarch64-apple-darwin.tar.xz"
 tar xf xtensa-esp32-elf-llvm11_0_0-aarch64-apple-darwin.tar.xz
 export PATH="`pwd`/xtensa-esp32-elf-clang/bin/:$PATH"

 wget --continue https://github.com/espressif/rust-esp32-example/archive/refs/heads/main.zip
 unzip main.zip
 cd rust-esp32-example-main
-idf.py build
 ```

+## Select architecture for the build
+
+For the ESP32 - default (Xtensa architecture):
+
+```sh
+idf.py set-target esp32
+```
+
+For the ESP32-S2 (Xtensa architecture):
+
+```sh
+idf.py set-target esp32s2
+```
+
+For the ESP32-S3 (Xtensa architecture):
+
+```sh
+idf.py set-target esp32s3
+```
+
+## Build and flash
+
+```sh
+idf.py build flash
+```
--- a/docs/rust-on-xtensa-installation-x86_64-apple-darwin.md
+++ b/docs/rust-on-xtensa-installation-x86_64-apple-darwin.md
@ -1,35 +1,68 @@
 # Rust on Xtensa Installation for macOS x64

-Tested OS: macOS Big Sur x64
+Following instructions are specific for ESP32 and ESP32-S series based on Xtensa architecture.

+Instructions for ESP-C series based on RISC-V architecture are described in document for [ESP32-C3](../README.md#esp32-c3).
+
+Tested OS: macOS Big Sur x64
 ## Prerequisites

 - rustup - installed with nightly toolchain - https://rustup.rs/

-## Commands
+## Installation commands

-```
+```sh
 rustup toolchain install nightly

-mkdir -p ~/.rustup/toolchains/esp
+VERSION="1.54.0-dev"
+ARCH="x86_64-apple-darwin"
+RUST_DIST="rust-${VERSION}-${ARCH}"
+RUST_SRC_DIST="rust-src-${VERSION}"
+TOOLCHAIN_DESTINATION_DIR="~/.rustup/toolchains/esp"

-wget https://dl.espressif.com/dl/idf-rust/dist/x86_64-apple-darwin/rust-1.53.0-dev-x86_64-apple-darwin.tar.xz
-tar xvf rust-1.53.0-dev-x86_64-apple-darwin.tar.xz
-./rust-1.53.0-dev-x86_64-apple-darwin/install.sh --destdir=~/.rustup/toolchains/esp --prefix="" --without=rust-docs
+mkdir -p ${TOOLCHAIN_DESTINATION_DIR}

-wget https://dl.espressif.com/dl/idf-rust/dist/noarch/rust-src-1.53.0-dev.tar.xz
-tar xvf rust-src-1.53.0-dev.tar.xz
-./rust-src-1.53.0-dev/install.sh --destdir=~/.rustup/toolchains/esp --prefix="" --without=rust-docs
+wget "https://dl.espressif.com/dl/idf-rust/dist/${ARCH}/${RUST_DIST}.tar.xz"
+tar xvf ${RUST_DIST}.tar.xz
+./${RUST_DIST}/install.sh --destdir=${TOOLCHAIN_DESTINATION_DIR} --prefix="" --without=rust-docs
+
+wget "https://dl.espressif.com/dl/idf-rust/dist/noarch/${RUST_SRC_DIST}.tar.xz"
+tar xvf ${RUST_SRC_DIST}.tar.xz
+./${RUST_SRC_DIST}/install.sh --destdir=${TOOLCHAIN_DESTINATION_DIR} --prefix="" --without=rust-docs

 rustup default esp

-wget https://dl.espressif.com/dl/idf-rust/dist/x86_64-apple-darwin/xtensa-esp32-elf-llvm11_0_0-x86_64-apple-darwin.tar.xz
+wget "https://dl.espressif.com/dl/idf-rust/dist/${ARCH}/xtensa-esp32-elf-llvm11_0_0-x86_64-apple-darwin.tar.xz"
 tar xf xtensa-esp32-elf-llvm11_0_0-x86_64-apple-darwin.tar.xz
 export PATH="`pwd`/xtensa-esp32-elf-clang/bin/:$PATH"

 wget --continue https://github.com/espressif/rust-esp32-example/archive/refs/heads/main.zip
 unzip main.zip
 cd rust-esp32-example-main
-idf.py build
 ```

+## Select architecture for the build
+
+For the ESP32 - default (Xtensa architecture):
+
+```sh
+idf.py set-target esp32
+```
+
+For the ESP32-S2 (Xtensa architecture):
+
+```sh
+idf.py set-target esp32s2
+```
+
+For the ESP32-S3 (Xtensa architecture):
+
+```sh
+idf.py set-target esp32s3
+```
+
+## Build and flash
+
+```sh
+idf.py build flash
+```
--- a/docs/rust-on-xtensa-installation-x86_64-pc-windows-msvc.md
+++ b/docs/rust-on-xtensa-installation-x86_64-pc-windows-msvc.md
@ -1,5 +1,9 @@
 # Rust on Xtensa Installation for Windows x64

+Following instructions are specific for ESP32 and ESP32-S series based on Xtensa architecture.
+
+Instructions for ESP-C series based on RISC-V architecture are described in document for [ESP32-C3](../README.md#esp32-c3).
+
 Tested OS: Windows 10 x64

 ## Prerequisites
@ -8,41 +12,58 @@ Tested OS: Windows 10 x64
 - rustup - installed with nightly toolchain - https://rustup.rs/
 - Chocolatey - https://chocolatey.org/

-## Commands for PowerShell
+## Installation commands for PowerShell

-```
+```sh
 choco install 7zip

 rustup toolchain install nightly

-mkdir -p ~\.rustup\toolchains\esp
+$Version="1.54.0-dev"
+$Arch="x86_64-pc-windows-msvc"
+$RustDist="rust-${VERSION}-${ARCH}"

-Invoke-WebRequest https://dl.espressif.com/dl/idf-rust/dist/x86_64-pc-windows-msvc/rust-1.53.0-dev-x86_64-pc-windows-msvc.tar.xz -OutFile rust-1.53.0-dev-x86_64-pc-windows-msvc.tar.xz
-7z e .\rust-1.53.0-dev-x86_64-pc-windows-msvc.tar.xz
-7z x .\rust-1.53.0-dev-x86_64-pc-windows-msvc.tar
-pushd rust-1.53.0-dev-x86_64-pc-windows-msvc
-cp -Recurse .\rustc\bin ~\.rustup\toolchains\esp\
-cp -Recurse .\rustc\lib ~\.rustup\toolchains\esp\
-cp -Recurse .\rustc\share ~\.rustup\toolchains\esp\
-cp -ErrorAction SilentlyContinue -Recurse .\rust-std-x86_64-pc-windows-msvc\lib\* ~\.rustup\toolchains\esp\lib\
-popd
+mkdir -p ~\.rustup\toolchains\ -ErrorAction SilentlyContinue
+pushd ~\.rustup\toolchains\

-Invoke-WebRequest https://dl.espressif.com/dl/idf-rust/dist/noarch/rust-src-1.53.0-dev.tar.xz -OutFile rust-src-1.53.0-dev.tar.xz
-7z e .\rust-src-1.53.0-dev.tar.xz
-7z x .\rust-src-1.53.0-dev.tar
-pushd rust-src-1.53.0-dev
-cp -ErrorAction SilentlyContinue -Recurse .\rust-src\lib\* ~\.rustup\toolchains\esp\lib\
+Invoke-WebRequest "https://dl.espressif.com/dl/idf-rust/dist/${Arch}/${RustDist}.zip" -OutFile "${RustDist}.zip"
+7z x .\${RustDist}.zip
 popd

 rustup default esp

-Invoke-WebRequest https://dl.espressif.com/dl/idf-rust/dist/x86_64-pc-windows-msvc/xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-win64.zip -OutFile xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-win64.zip
+Invoke-WebRequest https://dl.espressif.com/dl/idf-rust/dist/${Arch}/xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-win64.zip -OutFile xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-win64.zip
 7z x xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-win64.zip
-$ClangPath=Join-Path -Path (Get-Location) -ChildPath xtensa-esp32-elf-clang\bin
-$env:PATH="${ClangPath};$env:PATH"
+$env:LIBCLANG_PATH=Join-Path -Path (Get-Location) -ChildPath xtensa-esp32-elf-clang\bin
+$env:PATH+=";$env:LIBCLANG_PATH"

 Invoke-WebRequest https://github.com/espressif/rust-esp32-example/archive/refs/heads/main.zip -OutFile rust-esp32-example.zip
 7z x rust-esp32-example.zip
 cd rust-esp32-example-main
-idf.py build
+```
+
+## Select architecture for the build
+
+For the ESP32 - default (Xtensa architecture):
+
+```sh
+idf.py set-target esp32
+```
+
+For the ESP32-S2 (Xtensa architecture):
+
+```sh
+idf.py set-target esp32s2
+```
+
+For the ESP32-S3 (Xtensa architecture):
+
+```sh
+idf.py set-target esp32s3
+```
+
+## Build and flash
+
+```sh
+idf.py build flash
 ```
--- a/docs/rust-on-xtensa-installation-x86_64-unknown-linux-gnu.md
+++ b/docs/rust-on-xtensa-installation-x86_64-unknown-linux-gnu.md
@ -1,36 +1,71 @@
 # Rust on Xtensa Installation for Linux x64

+Following instructions are specific for ESP32 and ESP32-S series based on Xtensa architecture.
+
+Instructions for ESP-C series based on RISC-V architecture are described in document for [ESP32-C3](../README.md#esp32-c3).
+
 Tested OS: Ubuntu 18 x64, Ubuntu 20 x64, Mint 20 x64, OpenSUSE Thumbleweed

 ## Prerequisites

 - rustup - installed with nightly toolchain - https://rustup.rs/

-## Commands
+## Installation commands

-```
+```sh
 sudo apt install gcc wget xz-utils

 rustup toolchain install nightly

-mkdir -p ~/.rustup/toolchains/esp
+VERSION="1.54.0-dev"
+ARCH="x86_64-unknown-linux-gnu"
+RUST_DIST="rust-${VERSION}-${ARCH}"
+RUST_SRC_DIST="rust-src-${VERSION}"
+TOOLCHAIN_DESTINATION_DIR="~/.rustup/toolchains/esp"

-wget https://dl.espressif.com/dl/idf-rust/dist/x86_64-unknown-linux-gnu/rust-1.53.0-dev-x86_64-unknown-linux-gnu.tar.xz
-tar xvf rust-1.53.0-dev-x86_64-unknown-linux-gnu.tar.xz
-./rust-1.53.0-dev-x86_64-unknown-linux-gnu/install.sh --destdir=~/.rustup/toolchains/esp --prefix="" --without=rust-docs
+mkdir -p ${TOOLCHAIN_DESTINATION_DIR}

-wget https://dl.espressif.com/dl/idf-rust/dist/noarch/rust-src-1.53.0-dev.tar.xz
-tar xvf rust-src-1.53.0-dev.tar.xz
-./rust-src-1.53.0-dev/install.sh --destdir=~/.rustup/toolchains/esp --prefix="" --without=rust-docs
+wget https://dl.espressif.com/dl/idf-rust/dist/${ARCH}/${RUST_DIST}.tar.xz
+tar xvf ${RUST_DIST}.tar.xz
+./${RUST_DIST}/install.sh --destdir=${TOOLCHAIN_DESTINATION_DIR} --prefix="" --without=rust-docs
+
+wget https://dl.espressif.com/dl/idf-rust/dist/noarch/${RUST_SRC_DIST}.tar.xz
+tar xvf ${RUST_SRC_DIST}.tar.xz
+./${RUST_SRC_DIST}/install.sh --destdir=${TOOLCHAIN_DESTINATION_DIR} --prefix="" --without=rust-docs

 rustup default esp

-wget https://dl.espressif.com/dl/idf-rust/dist/x86_64-unknown-linux-gnu/xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-linux-amd64.tar.xz
+wget https://dl.espressif.com/dl/idf-rust/dist/${ARCH}/xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-linux-amd64.tar.xz
 tar xf xtensa-esp32-elf-llvm11_0_0-llvmorg-11-init-21249-g36dbc8b-linux-amd64.tar.xz
 export PATH="`pwd`/xtensa-esp32-elf-clang/bin/:$PATH"

 wget --continue https://github.com/espressif/rust-esp32-example/archive/refs/heads/main.zip
 unzip main.zip
 cd rust-esp32-example-main
-idf.py build
+```
+
+## Select architecture for the build
+
+For the ESP32 - default (Xtensa architecture):
+
+```sh
+idf.py set-target esp32
+```
+
+For the ESP32-S2 (Xtensa architecture):
+
+```sh
+idf.py set-target esp32s2
+```
+
+For the ESP32-S3 (Xtensa architecture):
+
+```sh
+idf.py set-target esp32s3
+```
+
+## Build and flash
+
+```sh
+idf.py build flash
 ```
--- a/docs/rust-on-xtensa.md
+++ b/docs/rust-on-xtensa.md
@ -1,4 +1,8 @@
-# Rust on ESP32 (Xtensa)
+# Rust on ESP32 and ESP32-S series (Xtensa)
+
+Following instructions are specific for ESP32 and ESP32-S series based on Xtensa architecture.
+
+Instructions for ESP-C series based on RISC-V architecture are described in document for [ESP32-C3](../README.md#esp32-c3).

 ## Quick start