diff --git a/docs/en/api-guides/tools/idf-tools.rst b/docs/en/api-guides/tools/idf-tools.rst index 9006b2f7a31a..10a2df360179 100644 --- a/docs/en/api-guides/tools/idf-tools.rst +++ b/docs/en/api-guides/tools/idf-tools.rst @@ -161,7 +161,7 @@ Shell-specific user-facing installation scripts are provided in the root directo * ``install.sh`` for Bash * ``install.fish`` for Fish -Apart from downloading and installing the tools in ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment. +Apart from downloading and installing the tools in ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment. If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON_CUSTOM`` before installation and each time before use. For example ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``. These scripts accept optionally a comma-separated list of chip targets and ``--enable-*`` arguments for enabling features. These arguments are passed to the ``idf_tools.py`` script which stores them in ``idf-env.json``. Therefore, chip targets and features can be enabled incrementally. diff --git a/docs/en/get-started/linux-macos-setup.rst b/docs/en/get-started/linux-macos-setup.rst index 7848bf6e6a99..f8022f54f431 100644 --- a/docs/en/get-started/linux-macos-setup.rst +++ b/docs/en/get-started/linux-macos-setup.rst @@ -116,6 +116,8 @@ To install supported Python 3 on macOS: During installation, the install script will check for supported Python versions on your system and select the oldest version that meets the minimum requirement. +If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON_CUSTOM`` before installation and each time before use. For example ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``. + .. _get-started-get-esp-idf: Step 2. Get ESP-IDF diff --git a/docs/zh_CN/api-guides/tools/idf-tools.rst b/docs/zh_CN/api-guides/tools/idf-tools.rst index 8cb37d5946bf..ea44ab103c36 100644 --- a/docs/zh_CN/api-guides/tools/idf-tools.rst +++ b/docs/zh_CN/api-guides/tools/idf-tools.rst @@ -161,7 +161,7 @@ ESP-IDF 的根目录中提供了针对不同 shell 的用户安装脚本,包 * ``install.sh`` 适用于 Bash * ``install.fish`` 适用于 Fish -这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外,还会准备一个 Python 虚拟环境,并在此虚拟环境中安装所需软件包。 +这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外,还会准备一个 Python 虚拟环境,并在此虚拟环境中安装所需软件包。如果要指定 ESP-IDF 使用特定的 Python ,则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON_CUSTOM``,例如 ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``。 为启用相应功能,这些脚本可以选择性地接受一组以逗号分隔的芯片目标列表及 ``--enable-*`` 参数,这类参数会传递给 ``idf_tools.py`` 脚本,并由该脚本将这类参数存储在 ``idf-env.json`` 中,从而逐步启用芯片目标及功能。 diff --git a/docs/zh_CN/get-started/linux-macos-setup.rst b/docs/zh_CN/get-started/linux-macos-setup.rst index abe4bb64984b..17802aa5f903 100644 --- a/docs/zh_CN/get-started/linux-macos-setup.rst +++ b/docs/zh_CN/get-started/linux-macos-setup.rst @@ -115,6 +115,8 @@ Apple M1 用户 .. note:: 安装过程中,安装脚本 (install.sh) 会检查系统中已安装的 Python 版本,并在所有符合最低要求的版本中,选择最早的版本使用。 + +如果要指定 ESP-IDF 使用特定的 Python ,则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON_CUSTOM``,例如 ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``。 .. _get-started-get-esp-idf: diff --git a/export.fish b/export.fish index 0187ca0fe54a..f86005079c07 100644 --- a/export.fish +++ b/export.fish @@ -16,7 +16,7 @@ if not test -f "$idf_path/tools/idf.py" exit 1 end -source "$idf_path"/tools/detect_python.fish +source "$idf_path"/tools/detect_python.fish || return 1 eval ("$ESP_PYTHON" "$idf_path"/tools/activate.py --export) set -e idf_path diff --git a/export.sh b/export.sh index 40bad17d3858..0f9f7e6b5f6c 100644 --- a/export.sh +++ b/export.sh @@ -53,7 +53,7 @@ then return 1 fi -. "${idf_path}/tools/detect_python.sh" +. "${idf_path}/tools/detect_python.sh" || return 1 # Evaluate the ESP-IDF environment set up by the activate.py script. idf_exports=$("$ESP_PYTHON" "${idf_path}/tools/activate.py" --export --shell $shell_type) diff --git a/install.fish b/install.fish index 065df8abe4d1..60da66bbf3f5 100755 --- a/install.fish +++ b/install.fish @@ -7,7 +7,7 @@ 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 +source "$IDF_PATH"/tools/detect_python.fish || exit 1 echo "Checking Python compatibility" "$ESP_PYTHON" "$IDF_PATH"/tools/python_version_checker.py diff --git a/install.sh b/install.sh index ce972c729019..e62b20233ab1 100755 --- a/install.sh +++ b/install.sh @@ -10,7 +10,7 @@ export IDF_PATH echo "INFO: Using IDF_PATH '${IDF_PATH}' for installation." echo "Detecting the Python interpreter" -. "${IDF_PATH}/tools/detect_python.sh" +. "${IDF_PATH}/tools/detect_python.sh" || exit 1 echo "Checking Python compatibility" "${ESP_PYTHON}" "${IDF_PATH}/tools/python_version_checker.py" diff --git a/tools/detect_python.fish b/tools/detect_python.fish index 8e9947f3a8a4..e01cfc7e159f 100644 --- a/tools/detect_python.fish +++ b/tools/detect_python.fish @@ -2,24 +2,36 @@ # # This is a port of detect_python.sh. More information are provided there. +function detect_python + set OLDEST_PYTHON_SUPPORTED_MAJOR 3 set OLDEST_PYTHON_SUPPORTED_MINOR 10 -set -x ESP_PYTHON python +if test -z "$ESP_PYTHON_CUSTOM" + set PYTHON_CANDIDATES python3 python python3.10 python3.11 python3.12 python3.13 +else + echo "Reading ESP_PYTHON_CUSTOM from environment: \"$ESP_PYTHON_CUSTOM\"" + set PYTHON_CANDIDATES "$ESP_PYTHON_CUSTOM" +end -for p_cmd in python3 python python3.10 python3.11 python3.12 python3.13; +for p_cmd in $PYTHON_CANDIDATES $p_cmd --version >/dev/null 2>&1; or continue echo "Checking \"$p_cmd\" ..." $p_cmd -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);"; or continue $p_cmd -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);"; or continue - set ESP_PYTHON $p_cmd + set ESP_PYTHON "$p_cmd" break end +set -e PYTHON_CANDIDATES -test -n "$ESP_PYTHON"; or echo "Python $OLDEST_PYTHON_SUPPORTED_MAJOR.$OLDEST_PYTHON_SUPPORTED_MINOR+ is not installed! Please see the documentation for how to install it." -test -n "$ESP_PYTHON"; or exit 1 +test -n "$ESP_PYTHON"; or echo "Python $OLDEST_PYTHON_SUPPORTED_MAJOR.$OLDEST_PYTHON_SUPPORTED_MINOR+ is not installed! Please see the documentation for how to install it." >&2 +test -n "$ESP_PYTHON"; or return 1 $ESP_PYTHON --version echo "$ESP_PYTHON has been detected" +set -gx ESP_PYTHON "$ESP_PYTHON" + +end +detect_python # Make sure at last line call function, because outside caller need its return value diff --git a/tools/detect_python.sh b/tools/detect_python.sh index 3f84a9b91ef8..ff2ffa9ab91f 100644 --- a/tools/detect_python.sh +++ b/tools/detect_python.sh @@ -3,28 +3,48 @@ # This is a helper script for detecting Python executables in the PATH. It is intended to be used for determining # which Python should be used with idf_tools.py for installing tools and exporting environment variables. # -# 1. The script is looking for python version same or greater than minimal required version on path +# 1. If environment variable ESP_PYTHON_CUSTOM already set, script uses that python binary, otherwise, looks for python version same or greater than minimal required version on path # 2. If required version of python is found it is assigned to environmental variable `ESP_PYTHON` # 3. If required version of python is not found, script will fail +detect_python () { + OLDEST_PYTHON_SUPPORTED_MAJOR=3 OLDEST_PYTHON_SUPPORTED_MINOR=10 -ESP_PYTHON=python +PYTHON_CANDIDATES="python3 +python +python3.10 +python3.11 +python3.12 +python3.13" + +if [ -n "${ESP_PYTHON_CUSTOM:-}" ]; then + echo "Reading ESP_PYTHON_CUSTOM from environment: \"$ESP_PYTHON_CUSTOM\"" + PYTHON_CANDIDATES="$ESP_PYTHON_CUSTOM" +fi -for p_cmd in python3 python python3.10 python3.11 python3.12 python3.13; do - $p_cmd --version >/dev/null 2>&1 || continue +while IFS= read -r p_cmd; do + "$p_cmd" --version >/dev/null 2>&1 || continue echo "Checking \"$p_cmd\" ..." - $p_cmd -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);" || continue - $p_cmd -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);" || continue + "$p_cmd" -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);" || continue + "$p_cmd" -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);" || continue - ESP_PYTHON=$p_cmd + ESP_PYTHON="$p_cmd" break -done +done << EOF +$PYTHON_CANDIDATES +EOF -$ESP_PYTHON --version 2>/dev/null || { - echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it." - exit 1 -} +unset PYTHON_CANDIDATES + +if [ -z "${ESP_PYTHON:-}" ]; then + echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it." >&2 + return 1 +fi echo "\"$ESP_PYTHON\" has been detected" +export ESP_PYTHON + +} +detect_python # Make sure at last line call function, because outside caller need its return value