From c1e34403526bf947202bf462a176d85c61246053 Mon Sep 17 00:00:00 2001 From: Shang Zhou Date: Tue, 5 Dec 2023 19:48:43 +0800 Subject: [PATCH] docs: Update CN translation for idf-py.rst and linux-macos-setup.rst --- docs/en/api-guides/tools/idf-py.rst | 2 +- docs/en/get-started/linux-macos-setup.rst | 4 ++-- docs/zh_CN/api-guides/tools/idf-py.rst | 17 +++++++++++++++++ docs/zh_CN/get-started/linux-macos-setup.rst | 14 ++++++++++++-- 4 files changed, 32 insertions(+), 5 deletions(-) diff --git a/docs/en/api-guides/tools/idf-py.rst b/docs/en/api-guides/tools/idf-py.rst index 7d7bd5b6e0..c785b7a212 100644 --- a/docs/en/api-guides/tools/idf-py.rst +++ b/docs/en/api-guides/tools/idf-py.rst @@ -250,7 +250,7 @@ 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 is e.g. :example_file:`configuration profile files ` in the GitHub cmake multi_config README. +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 `. .. _cmake: https://cmake.org .. _ninja: https://ninja-build.org diff --git a/docs/en/get-started/linux-macos-setup.rst b/docs/en/get-started/linux-macos-setup.rst index 0213a0c903..f462393b52 100644 --- a/docs/en/get-started/linux-macos-setup.rst +++ b/docs/en/get-started/linux-macos-setup.rst @@ -216,7 +216,7 @@ 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, **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. +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. .. code-block:: bash @@ -228,7 +228,7 @@ The scripts introduced in this step install compilation tools required by ESP-ID 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. + 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: diff --git a/docs/zh_CN/api-guides/tools/idf-py.rst b/docs/zh_CN/api-guides/tools/idf-py.rst index 945e7c95e2..38162c5bca 100644 --- a/docs/zh_CN/api-guides/tools/idf-py.rst +++ b/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:`多个构建配置示例 `。 + .. _cmake: https://cmake.org .. _ninja: https://ninja-build.org .. _esptool.py: https://github.com/espressif/esptool/#readme diff --git a/docs/zh_CN/get-started/linux-macos-setup.rst b/docs/zh_CN/get-started/linux-macos-setup.rst index 3b7e1d8e36..529346091d 100644 --- a/docs/zh_CN/get-started/linux-macos-setup.rst +++ b/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: