diff --git a/docs/en/api-guides/tools/idf-tools.rst b/docs/en/api-guides/tools/idf-tools.rst index 425f0abb09..354476dea8 100644 --- a/docs/en/api-guides/tools/idf-tools.rst +++ b/docs/en/api-guides/tools/idf-tools.rst @@ -182,9 +182,9 @@ Since the installed tools are not permanently added to the user or system ``PATH .. note:: - 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. + To modify the shell environment in Bash, ``export.sh`` must be "sourced" by using the command ``. ./export.sh``. 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., ``. ./<>/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 --git a/docs/zh_CN/api-guides/tools/idf-tools.rst b/docs/zh_CN/api-guides/tools/idf-tools.rst index f614ccae00..613180a278 100644 --- a/docs/zh_CN/api-guides/tools/idf-tools.rst +++ b/docs/zh_CN/api-guides/tools/idf-tools.rst @@ -184,7 +184,7 @@ ESP-IDF 的根目录中提供了针对不同 shell 的用户安装脚本,包 在 Bash 中修改 shell 环境时,必须使用 ``. ./export.sh`` 命令加载 ``export.sh``,注意添加前面的点和空格。 - ``export.sh`` 可以在除了 Bash 外的其他 shell(如 zsh)中使用。但在这种情况下,必须在运行脚本前设置 ``IDF_PATH`` 环境变量。在 Bash 中使用时,脚本会从当前目录猜测 ``IDF_PATH`` 的值。 + ``export.sh`` 可以在多种 shell 中使用,例如 bash、sh、zsh、dash 等。在使用 bash 或 zsh 时,可以在任何路径中直接运行(例如 ``. ./<>/export.sh``),这是因为它能够自动检测到 ``IDF_PATH``。若使用其它 shell, 则必须在 ESP-IDF 路径中运行 (``. ./export.sh``),才能正确找到 ``IDF_PATH``。 activate.py ~~~~~~~~~~~ diff --git a/export.bat b/export.bat index f15ce3f977..77ab42fba1 100644 --- a/export.bat +++ b/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 --git a/export.fish b/export.fish index 9c8dccdb8b..e2d9600021 100644 --- a/export.fish +++ b/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 --git a/export.ps1 b/export.ps1 index 90295563bf..5e54c4437e 100644 --- a/export.ps1 +++ b/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 --git a/export.sh b/export.sh index 6bea2c4824..b5adfd672b 100644 --- a/export.sh +++ b/export.sh @@ -22,27 +22,40 @@ idf_path="." shell_type="detect" # shellcheck disable=SC2128,SC2169,SC2039,SC3054,SC3028 # ignore array expansion warning -if test -n "${BASH_SOURCE-}" +if [ -n "${BASH_SOURCE-}" ] then # shellcheck disable=SC3028,SC3054 # unreachable with 'dash' idf_path=$(dirname "${BASH_SOURCE[0]}") shell_type="bash" -elif test -n "${ZSH_VERSION-}" +elif [ -n "${ZSH_VERSION-}" ] then # shellcheck disable=SC2296 # ignore parameter starts with '{' because it's zsh idf_path=$(dirname "${(%):-%x}") shell_type="zsh" -elif test -n "${IDF_PATH-}" +elif [ -n "${IDF_PATH-}" ] then - idf_path=$IDF_PATH + if [ -f "/.dockerenv" ] + then + echo "Using the IDF_PATH found in the environment as docker environment detected." + idf_path=$IDF_PATH + elif [ -n "${IDF_PATH_FORCE-}" ] + then + echo "Using the forced IDF_PATH found in the environment." + idf_path=$IDF_PATH + fi 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 automatically detect IDF_PATH from script location. Please navigate to your ESP-IDF directory and run:" + echo ". ./export.sh" + if [ -n "${IDF_PATH-}" ] + then + echo + echo "To use the IDF_PATH set in the environment, you can enforce it by setting 'export IDF_PATH_FORCE=1'" + fi unset idf_path return 1 fi diff --git a/install.bat b/install.bat index 6c41409102..668b7d3db6 100644 --- a/install.bat +++ b/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 --git a/install.fish b/install.fish index e064f9e2e9..065df8abe4 100755 --- a/install.fish +++ b/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 --git a/install.ps1 b/install.ps1 index b70df9d431..e20f44cca4 100644 --- a/install.ps1 +++ b/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 --git a/install.sh b/install.sh index 868665c527..ce972c7290 100755 --- a/install.sh +++ b/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 --git a/tools/activate.py b/tools/activate.py index d1f88e34ad..697b003029 100755 --- a/tools/activate.py +++ b/tools/activate.py @@ -33,6 +33,7 @@ os.environ['IDF_PYTHON_ENV_PATH'] = '' # let idf_tools get the pyenv path 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 --git a/tools/export_utils/activate_venv.py b/tools/export_utils/activate_venv.py index d409d50ead..9546d941df 100644 --- a/tools/export_utils/activate_venv.py +++ b/tools/export_utils/activate_venv.py @@ -13,6 +13,7 @@ from console_output import die 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 --git a/tools/export_utils/utils.py b/tools/export_utils/utils.py index bd1d60ba45..2f6dd3f25e 100644 --- a/tools/export_utils/utils.py +++ b/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')