Merge branch 'feature/doc_update_idf_file_args_plus_idftoolspath_setup' into 'master'

feat(tools): Documentation update about setting IDF_TOOLS_PATH and idf.py argument file parsing

Closes IDF-8527 and IDFGH-11401

See merge request espressif/esp-idf!27080

docs/en/api-guides/tools/idf-py.rst

@@ -235,6 +235,23 @@ To list all available root level options, run ``idf.py --help``. To list options
 - ``--cmake-warn-uninitialized`` (or ``-w``)  causes CMake to print uninitialized variable warnings found in the project directory only. This only controls CMake variable warnings inside CMake itself, not other types of build warnings. This option can also be set permanently by setting the ``IDF_CMAKE_WARN_UNINITIALIZED`` environment variable to a non-zero value.
 - ``--no-hints`` flag disables hints on resolving errors and disable capturing output.
 
+Passing arguments via a ``@file``
+---------------------------------
+
+It is possible to pass multiple arguments to ``idf.py`` via a file. The file or path to the file must be annotated with ``@`` at the beginning. Arguments in the file can be separated by newlines or spaces and are expanded exactly as if they had appeared in that order on the idf.py command line.
+
+For example, let's have a file `custom_flash.txt`:
+
+.. code-block:: bash
+
+  flash --baud 115200
+
+Then the command can be executed as: ``idf.py @custom_flash.txt monitor``
+
+Arguments from a file can be combined with additional command line arguments, and multiple files annotated with ``@`` can be used simultaneously. For instance, if there is a second file ``another_config.txt``, both can be utilized by specifying ``idf.py @custom_flash.txt @another_config.txt monitor``.
+
+A further example of how this argument file can be used, e.g., creating configuration profile files via @filename, is in the :example_file:`Multiple Build Configurations Example <build_system/cmake/multi_config/README.md>`.
+
 .. _cmake: https://cmake.org
 .. _ninja: https://ninja-build.org
 .. _esptool.py: https://github.com/espressif/esptool/#readme

docs/en/get-started/linux-macos-setup.rst

@@ -216,9 +216,19 @@ To prefer the Espressif download server when installing tools, use the following
 Customizing the Tools Installation Path
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user account has sufficient permissions to read and write this path.
+The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux. If you wish to install the tools into a different directory, **export the environment variable IDF_TOOLS_PATH before running the installation scripts**. Make sure that your user account has sufficient permissions to read and write this path.
 
-If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the Install script (``install.bat``, ``install.ps1`` or ``install.sh``) and an Export script (``export.bat``, ``export.ps1`` or ``export.sh``) are executed.
+.. code-block:: bash
+
+    export IDF_TOOLS_PATH="$HOME/required_idf_tools_path"
+    ./install.sh
+
+    . ./export.sh
+
+If changing the ``IDF_TOOLS_PATH``, make sure it is exported in the environment before running any ESP-IDF tools or scripts.
+
+.. note::
+    Using ``IDF_TOOLS_PATH`` in variable assignement, e.g., ``IDF_TOOLS_PATH="$HOME/required_idf_tools_path" ./install.sh``, without prior exporting, will not work in most shells because the variable assignment will not affect the current execution environment, even if it's exported/changed in the sourced script.
 
 .. _get-started-set-up-env:
 

docs/zh_CN/api-guides/tools/idf-py.rst

@@ -235,6 +235,23 @@ ESP-IDF 支持多个目标芯片，运行 ``idf.py --list-targets`` 查看当前
 - ``--cmake-warn-uninitialized`` （或 ``-w``）将使 CMake 只显示在工程目录中发现的变量未初始化的警告，该选项仅控制 CMake 内部的 CMake 变量警告，不控制其他类型的构建警告。将环境变量 ``IDF_CMAKE_WARN_UNINITIALIZED`` 设置为非零值，可永久启用该选项。
 - ``--no-hints`` 用于禁用有关错误处理的提示并禁用捕获输出。
 
+通过 ``@file`` 传递参数
+---------------------------------
+
+可以通过文件向 ``idf.py`` 传递多个参数。该文件或文件路径须在开头使用 ``@`` 进行标注。文件中的参数支持通过换行或空格分隔，并按其在 idf.py 命令行中的顺序扩展。
+
+例如，当前有文件 `custom_flash.txt`：
+
+.. code-block:: bash
+
+  flash --baud 115200
+
+运行命令：``idf.py @custom_flash.txt monitor``
+
+文件中的参数可以与额外的命令行参数结合使用，也支持同时使用带有 ``@`` 标注的多个文件。例如，另有一个文件 ``another_config.txt``，此时，可以通过指定 ``idf.py @custom_flash.txt @another_config.txt monitor`` 同时使用两个文件。
+
+关于参数文件的更多示例，如通过 @filename 创建配置文件概要，请参阅 :example_file:`多个构建配置示例 <build_system/cmake/multi_config/README.md>`。
+
 .. _cmake: https://cmake.org
 .. _ninja: https://ninja-build.org
 .. _esptool.py: https://github.com/espressif/esptool/#readme

docs/zh_CN/get-started/linux-macos-setup.rst

@@ -216,9 +216,19 @@ ESP-IDF 工具安装器会下载 Github 发布版本中附带的一些工具，
 自定义工具安装路径
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-本步骤中介绍的脚本将 ESP-IDF 所需的编译工具默认安装在用户的根目录中，即 Linux 系统中的 ``$HOME/.espressif`` 目录。可以选择将工具安装到其他目录中，但请在运行安装脚本前，重新设置环境变量 ``IDF_TOOLS_PATH``。注意，请确保用户账号已经具备了读写该路径的权限。
+本步骤中介绍的脚本将 ESP-IDF 所需的编译工具默认安装在用户的根目录中，即 Linux 系统中的 ``$HOME/.espressif`` 目录。可以选择将工具安装到其他目录中，**但请在运行安装脚本前，导出环境变量 IDF_TOOLS_PATH**。注意，请确保用户账号已经具备了读写该路径的权限。
 
-如果修改了 ``IDF_TOOLS_PATH`` 变量，请确保该变量在每次执行安装脚本（``install.bat``、``install.ps1`` 或 ``install.sh``）和导出脚本（``export.bat``、``export.ps1`` 或 ``export.sh``）均保持一致。
+.. code-block:: bash
+
+    export IDF_TOOLS_PATH="$HOME/required_idf_tools_path"
+    ./install.sh
+
+    . ./export.sh
+
+如果修改了 ``IDF_TOOLS_PATH`` 变量，请在运行任意 ESP-IDF 工具或脚本前，将该变量导出到环境变量中。
+
+.. note::
+    如未导出环境变量，大多数 shell 将不支持在变量赋值中使用 ``IDF_TOOLS_PATH``，例如 ``IDF_TOOLS_PATH="$HOME/required_idf_tools_path" ./install.sh``。因为即便在源脚本中导出或修改了该变量，当前的执行环境也不受变量赋值影响。
 
 .. _get-started-set-up-env: