Merge pull request #21625 from crasbe/pr/esptools_export

dist/tools: improve the `esptools`, enhance documentation

cpu/esp32/doc.md

@@ -574,9 +574,13 @@ if you have already used ESP-IDF directly.
 
 Once the ESP32x tools are installed in the directory specified by the
 environment variable `$IDF_TOOLS_PATH`, the shell script
-`$RIOTBASE/dist/tools/esptools/install.sh` can be sourced to export the
+`$RIOTBASE/dist/tools/esptools/export.sh` can be sourced to export the
 paths of the installed tools using again the environment variable
 `$IDF_TOOLS_PATH`.
+By writing `.` followed by a space in front of the script, the script
+runs in the same environment as the current shell and sets the local
+environment variables, which would otherwise be lost on termination
+of the script.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 $ . dist/tools/esptools/export.sh

dist/tools/esptools/export.sh

@@ -1,5 +1,12 @@
 #!/bin/sh
 
+# If the script is not sourced, the exported variables are not saved
+# in the environment.
+if [ "$(basename -- "$0")" = "export.sh" ]; then
+    echo "Please run the script prefixed with a '.' followed by a space to source it." 1>&2
+    exit 1
+fi
+
 ESP32_GCC_RELEASE="esp-14.2.0_20241119"
 ESP8266_GCC_RELEASE="esp-5.2.0_20191018"
 
@@ -15,6 +22,49 @@ fi
 
 TOOLS_PATH="${IDF_TOOLS_PATH}/tools"
 
+# this function expects the parameters $TOOL, $TOOLS_DIR and $*_VERSION
+export_checks()
+{
+    TOOL="$1"
+    TOOLS_DIR_INT="$2" # internal TOOLS_DIR
+    TOOLS_VERSION="$3"
+
+    # create the wildcard expression from the TOOLS_DIR
+    TOOLS_DIR_BASE=$(echo "$TOOLS_DIR_INT/bin" | sed "s|/$TOOLS_VERSION/|/[^/]*/|")
+    TOOLS_DIR_IN_PATH=$(echo "$PATH" | grep "${TOOLS_DIR_INT}")
+
+    if [ ! -e "${TOOLS_DIR_INT}" ]; then
+        echo "${TOOLS_DIR_INT} does not exist - please run"
+        echo "\${RIOTBASE}/dist/tools/esptools/install.sh $TOOL"
+        return 1
+    fi
+
+    echo "$PATH" | tr ':' '\n' | while read -r entry; do
+        if echo "$entry" | grep -q "^${TOOLS_DIR_BASE}$"; then
+            if [ "$entry" != "${TOOLS_DIR_INT}/bin" ]; then
+                echo "Warning: PATH contains outdated entry: \"$entry\"." \
+                     "Please check your ~/.bashrc or ~/.profile.">&2
+            fi
+	fi
+    done
+    unset entry
+
+    if [ -e "${TOOLS_DIR_INT}" ] && [ -z "${TOOLS_DIR_IN_PATH}" ]; then
+        echo "Extending PATH by ${TOOLS_DIR_INT}/bin"
+        export PATH="${TOOLS_DIR_INT}/bin:${PATH}"
+
+        echo "To make this permanent, add this line to your ~/.bashrc or ~/.profile:"
+        echo PATH="\$PATH:${TOOLS_DIR_INT}/bin"
+    fi
+
+    unset TOOL
+    unset TOOLS_DIR_INT
+    unset TOOLS_VERSION
+    unset TOOLS_DIR_IN_PATH
+
+    return 0
+}
+
 export_arch()
 {
     case $1 in
@@ -36,35 +86,18 @@ export_arch()
     esac
 
     TOOLS_DIR="${TOOLS_PATH}/${TARGET_ARCH}/${ESP_GCC_RELEASE}/${TARGET_ARCH}"
-    TOOLS_DIR_IN_PATH=$(echo "$PATH" | grep "${TOOLS_DIR}")
-
-    if [ ! -e "${TOOLS_DIR}" ]; then
-        echo "${TOOLS_DIR} does not exist - please run"
-        echo "\${RIOTBASE}/dist/tools/esptools/install.sh $1"
-        return
-    fi
-
-    if [ -e "${TOOLS_DIR}" ] && [ -z "${TOOLS_DIR_IN_PATH}" ]; then
-        echo "Extending PATH by ${TOOLS_DIR}/bin"
-        export PATH="${TOOLS_DIR}/bin:${PATH}"
-    fi
-
-    echo "To make this permanent, add this line to your ~/.bashrc or ~/.profile:"
-    echo PATH="\$PATH:${TOOLS_DIR}/bin"
-
+    export_checks "$1" "$TOOLS_DIR" "$ESP_GCC_RELEASE"
     unset TOOLS_DIR
 }
 
 export_openocd()
 {
     TOOLS_DIR="${TOOLS_PATH}/openocd-esp32/${ESP32_OPENOCD_VERSION}"
-    TOOLS_DIR_IN_PATH=$(echo "$PATH" | grep "${TOOLS_DIR}")
     OPENOCD_DIR="${TOOLS_DIR}/openocd-esp32"
 
-    if [ -e "${OPENOCD_DIR}" ] && [ -z "${TOOLS_DIR_IN_PATH}" ]; then
-        echo "Extending PATH by ${TOOLS_DIR}/bin"
-        export PATH="${OPENOCD_DIR}/bin:${PATH}"
-        export OPENOCD="${OPENOCD_DIR}/bin/openocd -s ${OPENOCD_DIR}/share/openocd/scripts"
+    export_checks "openocd" "$OPENOCD_DIR" "$ESP32_OPENOCD_VERSION"
+    if [ $? -eq 0 ]; then
+       export OPENOCD="${OPENOCD_DIR}/bin/openocd -s ${OPENOCD_DIR}/share/openocd/scripts"
     fi
 
     unset TOOLS_DIR
@@ -107,13 +140,7 @@ export_qemu()
     fi
 
     TOOLS_DIR="${TOOLS_PATH}/${QEMU_ARCH}/${ESP32_QEMU_VERSION}/qemu"
-    TOOLS_DIR_IN_PATH=$(echo "$PATH" | grep "${TOOLS_DIR}")
-
-    if [ -e "${TOOLS_DIR}" ] && [ -z "${TOOLS_DIR_IN_PATH}" ]; then
-        echo "Extending PATH by ${TOOLS_DIR}/bin"
-        export PATH="${TOOLS_DIR}/bin:${PATH}"
-    fi
-
+    export_checks "qemu $1" "$TOOLS_DIR" "$ESP32_QEMU_VERSION"
     unset TOOLS_DIR
 }
 
@@ -132,13 +159,7 @@ export_gdb()
     esac
 
     TOOLS_DIR="${TOOLS_PATH}/${GDB_ARCH}/${GDB_VERSION}/${GDB_ARCH}"
-    TOOLS_DIR_IN_PATH=$(echo "$PATH" | grep "${TOOLS_DIR}")
-
-    if [ -e "${TOOLS_DIR}" ] && [ -z "${TOOLS_DIR_IN_PATH}" ]; then
-        echo "Extending PATH by ${TOOLS_DIR}/bin"
-        export PATH="${TOOLS_DIR}/bin:${PATH}"
-    fi
-
+    export_checks "gdb $1" "$TOOLS_DIR" "$GDB_VERSION"
     unset TOOLS_DIR
 }
 
@@ -170,7 +191,7 @@ elif [ "$1" = "gdb" ]; then
 elif [ "$1" = "openocd" ]; then
     export_openocd
 elif [ "$1" = "qemu" ]; then
-    export_qemu $2
+    export_qemu "$2"
 else
     export_arch "$1"
 fi

dist/tools/esptools/install.sh

@@ -264,4 +264,4 @@ else
 fi
 
 echo "Use following command to extend the PATH variable:"
-echo ". $(dirname "$0")/export.sh $1"
+echo ". $(dirname "$0")/export.sh $1 $2"