feat(tools): Inform user about IDF_PATH set/change in install/export scripts

Author: Marek Fiala

Diff for: docs/en/api-guides/tools/idf-tools.rst

@@ -184,7 +184,7 @@ Since the installed tools are not permanently added to the user or system ``PATH
 
     To modify the shell environment in Bash, ``export.sh`` must be "sourced" by using the ``. ./export.sh`` command. Please ensure to include the leading dot and space.
 
-    ``export.sh`` may be used with shells other than Bash (such as zsh). However, in this case, it is required to set the ``IDF_PATH`` environment variable before running the script. When used in Bash, the script guesses the ``IDF_PATH`` value from its own location.
+    ``export.sh`` may be used with various shells like Bash, Zsh, sh, dash, etc. When using Bash or Zsh, you can run it from any path (e.g., ``. ./<<some_path>>/export.sh``) as it automatically detects IDF_PATH. For other shells, it must be run from the ESP-IDF directory (``. ./export.sh``) to locate IDF_PATH correctly.
 
 activate.py
 ~~~~~~~~~~~

Diff for: export.bat

@@ -47,7 +47,7 @@ if not exist "%IDF_PATH%\tools\activate.py" (
 )
 
 
-for /f "delims=" %%i in ('python "%IDF_PATH%/tools/activate.py" --export') do set activate=%%i
+for /f "delims=" %%i in ('python "%IDF_PATH%\tools\activate.py" --export') do set activate=%%i
 %activate%
 
 goto :__end
@@ -64,8 +64,8 @@ goto :__end
     goto :__end
 
 :__missing_file
-    echo Could not detect correct IDF_PATH. Please set it before running this script:
-    echo   set IDF_PATH=(add path here)
+    echo Could not detect IDF_PATH. Please navigate to your ESP-IDF directory and run:
+    echo export.bat
     goto :__end
 
 :__end

Diff for: export.fish

@@ -17,8 +17,8 @@ set idf_path (dirname (realpath (status -f)))
 if not test -f "$idf_path/tools/idf.py"
    or not test -f "$idf_path/tools/idf_tools.py"
    or not test -f "$idf_path/tools/activate.py"
-    echo "Could not detect IDF_PATH. Please set it before sourcing this script:"
-    echo "  export IDF_PATH=(add path here)"
+    echo "Could not detect IDF_PATH. Please navigate to your ESP-IDF directory and run:"
+    echo ". ./export.fish"
     set -e idf_path
     exit 1
 end

Diff for: export.ps1

@@ -13,8 +13,8 @@ if (-not (Test-Path "$idf_path/tools/idf.py") -or
     -not (Test-Path "$idf_path/tools/idf_tools.py") -or
     -not (Test-Path "$idf_path/tools/activate.py")) {
 
-    Write-Output "Could not detect IDF_PATH. Please set it before running this script:"
-    Write-Output '  $env:IDF_PATH=(add path here)'
+    Write-Output "Could not detect IDF_PATH. Please navigate to your ESP-IDF directory and run:"
+    Write-Output ".\export.ps1"
 
     $env:IDF_PATH = ""
 

Diff for: export.sh

@@ -32,17 +32,14 @@ then
     # shellcheck disable=SC2296  # ignore parameter starts with '{' because it's zsh
     idf_path=$(dirname "${(%):-%x}")
     shell_type="zsh"
-elif test -n "${IDF_PATH-}"
-then
-    idf_path=$IDF_PATH
 fi
 
 if [ ! -f "${idf_path}/tools/idf.py" ] ||
-    [ ! -f "${idf_path}/tools/idf_tools.py" ] ||
-    [ ! -f "${idf_path}/tools/activate.py" ]
+   [ ! -f "${idf_path}/tools/idf_tools.py" ] ||
+   [ ! -f "${idf_path}/tools/activate.py" ]
 then
-    echo "Could not detect IDF_PATH. Please set it before sourcing this script:"
-    echo "  export IDF_PATH=(add path here)"
+    echo "Could not detect IDF_PATH. Please navigate to your ESP-IDF directory and run:"
+    echo ". ./export.sh"
     unset idf_path
     return 1
 fi

Diff for: install.bat

@@ -3,6 +3,8 @@ if defined MSYSTEM (
 	echo This .bat file is for Windows CMD.EXE shell only.
 	goto :__end
 )
+:: Set local ensures that variables like IDF_PATH are not changed/propagated out of the script
+setlocal
 
 set SCRIPT_EXIT_CODE=0
 
@@ -30,6 +32,8 @@ if /I "%1" == "/?" goto :__help
 if /I "%1" == "-h" goto :__help
 if /I "%1" == "--help" goto :__help
 
+echo INFO: Using IDF_PATH '%IDF_PATH%' for installation.
+
 for /f "delims=" %%i in ('python.exe "%IDF_PATH%\tools\install_util.py" extract targets "%*"') do set TARGETS=%%i
 
 echo Installing ESP-IDF tools

Diff for: install.fish

@@ -4,6 +4,8 @@ set basedir (realpath (dirname (status -f)))
 
 set -x IDF_PATH $basedir
 
+echo "INFO: Using IDF_PATH '$IDF_PATH' for installation."
+
 echo "Detecting the Python interpreter"
 source "$IDF_PATH"/tools/detect_python.fish
 
@@ -27,7 +29,7 @@ or exit 1
 set FEATURES ("$ESP_PYTHON" "$IDF_PATH"/tools/install_util.py extract features $argv) || exit 1
 
 echo "Installing Python environment and packages"
-"$ESP_PYTHON" "$IDF_PATH"/tools/idf_tools.py install-python-env --features=$FEATURES
+"$ESP_PYTHON" "$IDF_PATH"/tools/idf_tools.py install-python-env --features=$FEATURES || exit 1
 
 echo "All done! You can now run:"
 echo ""

Diff for: install.ps1

@@ -11,17 +11,23 @@ python "$IDF_PATH/tools/install_util.py" print_help ps1
 Exit
 }
 
+Write-Output "INFO: Using IDF_PATH '$IDF_PATH' for installation."
+
 $TARGETS = (python "$IDF_PATH/tools/install_util.py" extract targets "$args")
 
 Write-Output "Installing ESP-IDF tools"
-$proces_tools = Start-Process -Wait -PassThru -NoNewWindow -FilePath "python" -Args "`"$IDF_PATH/tools/idf_tools.py`" install --targets=${TARGETS}"
+# PowerShell does not propagate variables to new process (spawned python), so we pass detected IDF_PATH as argument
+# to avoid using any previously set IDF_PATH values in the terminal environment.
+$proces_tools = Start-Process -Wait -PassThru -NoNewWindow -FilePath "python" -Args "`"$IDF_PATH/tools/idf_tools.py`" --idf-path ${IDF_PATH} install --targets=${TARGETS}"
 $exit_code_tools = $proces_tools.ExitCode
 if ($exit_code_tools -ne 0) { exit $exit_code_tools }  # if error
 
 $FEATURES = (python "$IDF_PATH/tools/install_util.py" extract features "$args")
 
 Write-Output "Setting up Python environment"
-$proces_py_env = Start-Process -Wait -PassThru  -NoNewWindow -FilePath "python" -Args "`"$IDF_PATH/tools/idf_tools.py`" install-python-env --features=${FEATURES}"
+# PowerShell does not propagate variables to new process (spawned python), so we pass detected IDF_PATH as argument
+# to avoid using any previously set IDF_PATH values in the terminal environment.
+$proces_py_env = Start-Process -Wait -PassThru -NoNewWindow -FilePath "python" -Args "`"$IDF_PATH/tools/idf_tools.py`" --idf-path ${IDF_PATH} install-python-env --features=${FEATURES}"
 $exit_code_py_env = $proces_py_env.ExitCode
 if ($exit_code_py_env -ne 0) { exit $exit_code_py_env } # if error
 

Diff for: install.sh

@@ -7,6 +7,8 @@ basedir=$(dirname "$0")
 IDF_PATH=$(cd "${basedir}"; pwd -P)
 export IDF_PATH
 
+echo "INFO: Using IDF_PATH '${IDF_PATH}' for installation."
+
 echo "Detecting the Python interpreter"
 . "${IDF_PATH}/tools/detect_python.sh"
 

Diff for: tools/activate.py

@@ -33,6 +33,7 @@ def die(msg: str) -> None:
 idf_tools.g.idf_tools_path = os.environ.get('IDF_TOOLS_PATH') or os.path.expanduser(idf_tools.IDF_TOOLS_PATH_DEFAULT)
 idf_python_env_path, idf_python_export_path, virtualenv_python, idf_version = idf_tools.get_python_env_path()
 
+os.environ['IDF_PATH_OLD'] = os.environ.get('IDF_PATH', '')
 os.environ['IDF_PATH'] = idf_path
 os.environ['IDF_PYTHON_ENV_PATH'] = idf_python_env_path
 os.environ['ESP_IDF_VERSION'] = idf_version

Diff for: tools/export_utils/activate_venv.py

@@ -13,6 +13,7 @@
 from console_output import eprint
 from console_output import oprint
 from console_output import status_message
+from console_output import warn
 from shell_types import SHELL_CLASSES
 from shell_types import SUPPORTED_SHELLS
 from utils import conf
@@ -161,7 +162,11 @@ def main() -> None:
         sys.exit()
 
     eprint(f'[dark_orange]Activating ESP-IDF {conf.IDF_VERSION}')
-    debug(f'IDF_PATH {conf.IDF_PATH}')
+    if conf.IDF_PATH_OLD and conf.IDF_PATH != conf.IDF_PATH_OLD:
+        warn(f"IDF_PATH is changed from '{conf.IDF_PATH_OLD}' to '{conf.IDF_PATH}'.")
+    else:
+        eprint(f"Setting IDF_PATH to '{conf.IDF_PATH}'.")
+
     debug(f'IDF_PYTHON_ENV_PATH {conf.IDF_PYTHON_ENV_PATH}')
 
     check_python_version()

Diff for: tools/export_utils/utils.py

@@ -17,6 +17,7 @@ class Config:
     """
     def __init__(self) -> None:
         self.IDF_PATH = os.environ['IDF_PATH']
+        self.IDF_PATH_OLD = os.environ['IDF_PATH_OLD']
         self.IDF_VERSION = os.environ['ESP_IDF_VERSION']
         self.IDF_PYTHON_ENV_PATH = os.environ['IDF_PYTHON_ENV_PATH']
         self.IDF_TOOLS_PY = os.path.join(self.IDF_PATH, 'tools', 'idf_tools.py')