mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: provide CN translation for api-guides/tools/idf-tools.rst
This commit is contained in:
caixinying-git
parent
b38e5e1b3c
commit
ec1e03e132
@ -1,7 +1,7 @@
|
||||
ESP-IDF Frontend - idf.py
|
||||
*************************
|
||||
|
||||
:link_to_translation:`zh_CN:中文版`
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The ``idf.py`` command-line tool provides a front-end for easily managing your project builds, deployment and debugging, and more. It manages several tools, for example:
|
||||
|
||||
|
||||
@ -1,46 +1,48 @@
|
||||
Downloadable Tools
|
||||
==================
|
||||
Downloadable ESP-IDF Tools
|
||||
==========================
|
||||
|
||||
ESP-IDF build process relies on a number of tools: cross-compiler toolchains, CMake build system, and others.
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Installing the tools using an OS-specific package manager (like apt, yum, brew, etc.) is the preferred method when the required version of the tool is available. This recommendation is reflected in the Getting Started guide. For example, on Linux and macOS it is recommended to install CMake using an OS package manager.
|
||||
The ESP-IDF build process relies on a number of tools: cross-compiler toolchains, CMake build system, and others.
|
||||
|
||||
However, some of the tools are IDF-specific and are not available in OS package repositories. Furthermore, different versions of ESP-IDF require different versions of the tools to operate correctly. To solve these two problems, ESP-IDF provides a set of scripts for downloading and installing the correct versions of tools, and exposing them in the environment.
|
||||
Installing the tools using an OS-specific package manager (e.g., apt, yum, brew, etc.) is the preferred method, when the required version of the tool is available. This recommendation is reflected in the :doc:`Get Started <../../get-started/index>`. For example, on Linux and macOS, it is recommended to install CMake using an OS package manager.
|
||||
|
||||
However, some of the tools are specific to ESP-IDF and are not available in OS package repositories. Furthermore, different ESP-IDF versions require different tool versions for proper operation. To solve these two problems, ESP-IDF provides a set of scripts that can download and install the correct tool versions and set up the environment accordingly.
|
||||
|
||||
The rest of the document refers to these downloadable tools simply as "tools". Other kinds of tools used in ESP-IDF are:
|
||||
|
||||
* Python scripts bundled with ESP-IDF (such as ``idf.py``)
|
||||
* Python packages installed from PyPI.
|
||||
* Python scripts bundled with ESP-IDF such as ``idf.py``
|
||||
* Python packages installed from PyPI
|
||||
|
||||
The following sections explain the installation method, and provide the list of tools installed on each platform.
|
||||
The following sections explain the installation method and provide the list of tools installed on each platform.
|
||||
|
||||
.. note::
|
||||
|
||||
This document is provided for advanced users who need to customize their installation, users who wish to understand the installation process, and ESP-IDF developers.
|
||||
|
||||
If you are looking for instructions on how to install the tools, see the :doc:`Getting Started Guide <../../get-started/index>`.
|
||||
If you are looking for instructions on how to install the tools, see :doc:`Get Started <../../get-started/index>`.
|
||||
|
||||
|
||||
Tools metadata file
|
||||
Tools Metadata File
|
||||
-------------------
|
||||
|
||||
The list of tools and tool versions required for each platform is located in :idf_file:`tools/tools.json`. The schema of this file is defined by :idf_file:`tools/tools_schema.json`.
|
||||
|
||||
This file is used by :idf_file:`tools/idf_tools.py` script when installing the tools or setting up the environment variables.
|
||||
This file is used by the :idf_file:`tools/idf_tools.py` script when installing the tools or setting up the environment variables.
|
||||
|
||||
.. _idf-tools-path:
|
||||
|
||||
Tools installation directory
|
||||
Tools Installation Directory
|
||||
----------------------------
|
||||
|
||||
``IDF_TOOLS_PATH`` environment variable specifies the location where the tools are to be downloaded and installed. If not set, ``IDF_TOOLS_PATH`` defaults to ``HOME/.espressif`` on Linux and macOS, and ``%USER_PROFILE%\.espressif`` on Windows.
|
||||
The ``IDF_TOOLS_PATH`` environment variable specifies the location where the tools are to be downloaded and installed. If not set, the default location will be ``HOME/.espressif`` on Linux and macOS, and ``%USER_PROFILE%\.espressif`` on Windows.
|
||||
|
||||
Inside ``IDF_TOOLS_PATH``, the scripts performing tools installation create the following directories and files:
|
||||
Inside the ``IDF_TOOLS_PATH`` directory, the tools installation scripts create the following directories and files:
|
||||
|
||||
- ``dist`` — where the archives of the tools are downloaded.
|
||||
- ``tools`` — where the tools are extracted. The tools are extracted into subdirectories: ``tools/TOOL_NAME/VERSION/``. This arrangement allows different versions of tools to be installed side by side.
|
||||
- ``idf-env.json`` — user install options (targets, features) are stored in this file. Targets are selected chip targets for which tools are installed and kept up-to-date. Features determine the Python package set which should be installed. These options will be discussed later.
|
||||
- ``python_env`` — not tools related; virtual Python environments are installed in the sub-directories. Note that the Python environment directory can be placed elsewhere by setting the ``IDF_PYTHON_ENV_PATH`` environment variable.
|
||||
- ``idf-env.json`` — user install options, such as targets and features, are stored in this file. Targets are selected chip targets for which tools are installed and kept up-to-date. Features determine the Python package set which should be installed. These options will be discussed later.
|
||||
- ``python_env`` — not related to the tools; virtual Python environments are installed in the sub-directories. Note that the Python environment directory can be placed elsewhere by setting the ``IDF_PYTHON_ENV_PATH`` environment variable.
|
||||
- ``espidf.constraints.*.txt`` — one constraint file for each ESP-IDF release containing Python package version requirements.
|
||||
|
||||
GitHub Assets Mirror
|
||||
@ -48,108 +50,130 @@ GitHub Assets Mirror
|
||||
|
||||
Most of the tools downloaded by the tools installer are GitHub Release Assets, which are files attached to a software release on GitHub.
|
||||
|
||||
If GitHub downloads are inaccessible or slow to access, it's possible to configure a GitHub assets mirror.
|
||||
If GitHub downloads are inaccessible or slow to access, a GitHub assets mirror can be configured.
|
||||
|
||||
To use Espressif's download server, set the environment variable ``IDF_GITHUB_ASSETS`` to ``dl.espressif.com/github_assets``. When the install process is downloading a tool from ``github.com``, the URL will be rewritten to use this server instead.
|
||||
|
||||
Any mirror server can be used provided the URL matches the ``github.com`` download URL format: the install process will replace ``https://github.com`` with ``https://${IDF_GITHUB_ASSETS}`` for any GitHub asset URL that it downloads.
|
||||
Any mirror server can be used provided the URL matches the ``github.com`` download URL format. For any GitHub asset URL that the install process downloads, it will replace ``https://github.com`` with ``https://${IDF_GITHUB_ASSETS}``.
|
||||
|
||||
.. note:: The Espressif download server doesn't currently mirror everything from GitHub, it only mirrors files attached as Assets to some releases as well as source archives for some releases.
|
||||
.. note:: The Espressif download server currently does not mirror everything from GitHub, but only files attached as Assets to some releases, as well as source archives for some releases.
|
||||
|
||||
|
||||
``idf_tools.py`` script
|
||||
``idf_tools.py`` Script
|
||||
-----------------------
|
||||
|
||||
:idf_file:`tools/idf_tools.py` script bundled with ESP-IDF performs several functions:
|
||||
The :idf_file:`tools/idf_tools.py` script bundled with ESP-IDF performs several functions:
|
||||
|
||||
* ``install``: Download the tool into ``${IDF_TOOLS_PATH}/dist`` directory, extract it into ``${IDF_TOOLS_PATH}/tools/TOOL_NAME/VERSION``.
|
||||
* ``install``: Download the tool into the ``${IDF_TOOLS_PATH}/dist`` directory and extract it into ``${IDF_TOOLS_PATH}/tools/TOOL_NAME/VERSION``.
|
||||
|
||||
``install`` command accepts the list of tools to install, in ``TOOL_NAME`` or ``TOOL_NAME@VERSION`` format. If ``all`` is given, all the tools (required and optional ones) are installed. If no argument or ``required`` is given, only the required tools are installed.
|
||||
The ``install`` command accepts the list of tools to install in the ``TOOL_NAME`` or ``TOOL_NAME@VERSION`` format. If ``all`` is given, all the tools, including required and optional ones, are installed. If no argument or ``required`` is given, only the required tools are installed.
|
||||
|
||||
* ``download``: Similar to ``install`` but doesn't extract the tools. An optional ``--platform`` argument may be used to download the tools for the specific platform.
|
||||
|
||||
* ``export``: Lists the environment variables which need to be set to use the installed tools. For most of the tools, setting ``PATH`` environment variable is sufficient, but some tools require extra environment variables.
|
||||
* ``export``: Lists the environment variables that need to be set to use the installed tools. For most of the tools, setting the ``PATH`` environment variable is sufficient, but some tools require extra environment variables.
|
||||
|
||||
The environment variables can be listed in either of ``shell`` or ``key-value`` formats, set by ``--format`` parameter:
|
||||
The environment variables can be listed in either ``shell`` or ``key-value`` formats, which can be set using the ``--format`` parameter:
|
||||
|
||||
- ``export`` optional parameters:
|
||||
|
||||
- ``--unset`` Creates statement that unset some global variables, so the environment gets to the state it was before calling ``export.{sh/fish}``.
|
||||
- ``--add_paths_extras`` Adds extra ESP-IDF-related paths of ``$PATH`` to ``${IDF_TOOLS_PATH}/esp-idf.json``, which is used to remove global variables when the active ESP-IDF environment is deactivated. Example: While processing ``export.{sh/fish}`` script, new paths are added to global variable ``$PATH``. This option is used to save these new paths to the ``${IDF_TOOLS_PATH}/esp-idf.json``.
|
||||
- ``--unset``: Creates a statement that unsets specific global variables and restores the environment to its state before calling ``export.{sh/fish}``.
|
||||
- ``--add_paths_extras``: Adds extra ESP-IDF-related paths of ``$PATH`` to ``${IDF_TOOLS_PATH}/esp-idf.json``, which is used to remove global variables when the active ESP-IDF environment is deactivated. For example, while processing the ``export.{sh/fish}`` script, if new paths are added to the global variable ``$PATH``, this option saves these new paths to the ``${IDF_TOOLS_PATH}/esp-idf.json`` file.
|
||||
|
||||
- ``shell`` produces output suitable for evaluation in the shell. For example,
|
||||
- ``shell``: Produces output suitable for evaluation in the shell. For example, produce the following output on Linux and macOS:
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
export PATH="/home/user/.espressif/tools/tool/v1.0.0/bin:$PATH"
|
||||
|
||||
on Linux and macOS, and
|
||||
Produce the following output on Windows:
|
||||
|
||||
::
|
||||
.. code-block:: none
|
||||
|
||||
set "PATH=C:\Users\user\.espressif\tools\v1.0.0\bin;%PATH%"
|
||||
|
||||
on Windows.
|
||||
|
||||
.. note::
|
||||
|
||||
Exporting environment variables in Powershell format is not supported at the moment. ``key-value`` format may be used instead.
|
||||
|
||||
The output of this command may be used to update the environment variables, if the shell supports this. For example::
|
||||
The output of this command may be used to update the environment variables if the shell supports it. For example
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
eval $($IDF_PATH/tools/idf_tools.py export)
|
||||
|
||||
- ``key-value`` produces output in `VARIABLE=VALUE` format, suitable for parsing by other scripts::
|
||||
- ``key-value``: Produces output in the ``VARIABLE=VALUE`` format that is suitable for parsing by other scripts
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
PATH=/home/user/.espressif/tools/tool/v1.0.0:$PATH
|
||||
|
||||
Note that the script consuming this output has to perform expansion of ``$VAR`` or ``%VAR%`` patterns found in the output.
|
||||
|
||||
* ``list``: Lists the known versions of the tools, and indicates which ones are installed.
|
||||
|
||||
Following options are available to customize the output.
|
||||
The following option is available to customize the output.
|
||||
|
||||
- ``--outdated``: List only outdated versions of tools installed in ``IDF_TOOLS_PATH``.
|
||||
- ``--outdated``: Lists only outdated versions of tools installed in ``IDF_TOOLS_PATH``.
|
||||
|
||||
* ``check``: For each tool, checks whether the tool is available in the system path and in ``IDF_TOOLS_PATH``.
|
||||
|
||||
* ``install-python-env``: Create a Python virtual environment in the ``${IDF_TOOLS_PATH}/python_env`` directory (or directly in the directory set by the ``IDF_PYTHON_ENV_PATH`` environment variable) and install there the required Python packages. An optional ``--features`` argument allows one to specify a comma-separated list of features to be added or removed. Feature that begins with ``-`` will be removed and features with ``+`` or without any sign will be added. Example syntax for removing feature ``XY`` is ``--features=-XY`` and for adding ``--features=+XY`` or ``--features=XY``. If both removing and adding options are provided with the same feature, no operation is performed. For each feature a requirements file must exist. For example, feature ``XY`` is a valid feature if ``${IDF_PATH}/tools/requirements/requirements.XY.txt`` is an existing file with a list of Python packages to be installed. There is one mandatory ``core`` feature ensuring core functionality of ESP-IDF (build, flash, monitor, debug in console). There can be an arbitrary number of optional features. The selected list of features is stored in ``idf-env.json``. The requirement files contain a list of the desired Python packages to be installed and ``espidf.constraints.*.txt`` downloaded from https://dl.espressif.com and stored in ``${IDF_TOOLS_PATH}`` the package version requirements for a given ESP-IDF version. Althought it is not recommended, the download and use of constraint files can be disabled with the ``--no-constraints`` argument or setting the ``IDF_PYTHON_CHECK_CONSTRAINTS`` environment variable to ``no``.
|
||||
* ``install-python-env``: Creates a Python virtual environment in the ``${IDF_TOOLS_PATH}/python_env`` directory or directly in the directory set by the ``IDF_PYTHON_ENV_PATH`` environment variable, and install the required Python packages there.
|
||||
|
||||
* ``check-python-dependencies``: Checks if all required Python packages are installed. Packages from ``${IDF_PATH}/tools/requirements/requirements.*.txt`` files selected by the feature list of ``idf-env.json`` are checked with the package versions specified in the ``espidf.constraints.*.txt`` file. The constraint file is downloaded with ``install-python-env`` command. The use of constraints files can be disabled similarly to the ``install-python-env`` command.
|
||||
* An optional ``--features`` argument allows one to specify a comma-separated list of features to be added or removed.
|
||||
|
||||
* ``uninstall``: Print and remove tools, that are currently not used by active ESP-IDF version.
|
||||
#. A feature that begins with ``-`` will be removed, and features with ``+`` or without any sign will be added. Example syntax for removing feature ``XY`` is ``--features=-XY``, and for adding feature ``XY`` is ``--features=+XY`` or ``--features=XY``. If both removing and adding options are provided with the same feature, no operation is performed.
|
||||
|
||||
- ``--dry-run`` Print installed unused tools.
|
||||
- ``--remove-archives`` Additionally remove all older versions of previously downloaded installation packages.
|
||||
#. For each feature, a requirements file must exist. For example, feature ``XY`` is a valid feature if ``${IDF_PATH}/tools/requirements/requirements.XY.txt`` is an existing file with a list of Python packages to be installed.
|
||||
|
||||
#. There is one mandatory ``core`` feature ensuring the core functionality of ESP-IDF, e.g., build, flash, monitor, debug in console. There can be an arbitrary number of optional features.
|
||||
|
||||
#. The selected list of features is stored in ``idf-env.json``.
|
||||
|
||||
#. The requirement files contain a list of the desired Python packages to be installed and the ``espidf.constraints.*.txt`` file downloaded from https://dl.espressif.com and stored in ``${IDF_TOOLS_PATH}``, which contains the package version requirements for a given ESP-IDF version.
|
||||
|
||||
.. note::
|
||||
|
||||
Although **it is not recommended**, the download and use of constraint files can be disabled with the ``--no-constraints`` argument or setting the ``IDF_PYTHON_CHECK_CONSTRAINTS`` environment variable to ``no``.
|
||||
|
||||
* ``check-python-dependencies``: Checks if all required Python packages are installed. Packages from ``${IDF_PATH}/tools/requirements/requirements.*.txt`` files selected by the feature list of ``idf-env.json`` are checked with the package versions specified in the ``espidf.constraints.*.txt`` file.
|
||||
|
||||
.. note::
|
||||
|
||||
The constraint file is downloaded with the ``install-python-env`` command. Similar to the ``install-python-env`` command, the use of constraint files can be disabled with the ``--no-constraints`` argument or setting the ``IDF_PYTHON_CHECK_CONSTRAINTS`` environment variable to ``no``.
|
||||
|
||||
* ``uninstall``: Prints and removes tools that are currently not used by the active ESP-IDF version.
|
||||
|
||||
- ``--dry-run``: Prints installed unused tools.
|
||||
- ``--remove-archives``: Additionally removes all older versions of previously downloaded installation packages.
|
||||
|
||||
.. _idf-tools-install:
|
||||
|
||||
Install scripts
|
||||
Install Scripts
|
||||
---------------
|
||||
|
||||
Shell-specific user-facing scripts are provided in the root of ESP-IDF repository to facilitate tools installation. These are:
|
||||
Shell-specific user-facing installation scripts are provided in the root directory of ESP-IDF repository to facilitate tools installation. These are:
|
||||
|
||||
* ``install.bat`` for Windows Command Prompt
|
||||
* ``install.ps1`` for Powershell
|
||||
* ``install.sh`` for Bash
|
||||
* ``install.fish`` for Fish
|
||||
|
||||
Aside from downloading and installing the tools into ``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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Running the scripts without any optional arguments will install tools for all chip targets (by running ``idf_tools.py install --targets=all``) and Python packages for core ESP-IDF functionality (by running ``idf_tools.py install-python-env --features=core``).
|
||||
To install tools for all chip targets, run the scripts without any optional arguments using ``idf_tools.py install --targets=all``. Similarly, to install Python packages for core ESP-IDF functionality, run ``idf_tools.py install-python-env --features=core``.
|
||||
|
||||
Or for example, ``install.sh esp32`` will install tools only for ESP32. See the :ref:`Getting Started Guide <get-started-set-up-tools>` for more examples.
|
||||
It is also possible to install tools for specific chip targets. For example, ``install.sh esp32`` installs tools only for ESP32. See :ref:`Step 3. Set up the Tools <get-started-set-up-tools>` for more examples.
|
||||
|
||||
``install.sh --enable-XY`` will enable feature ``XY`` (by running ``idf_tools.py install-python-env --features=core,XY``).
|
||||
``install.sh --enable-XY`` enables feature ``XY`` (by running ``idf_tools.py install-python-env --features=core,XY``).
|
||||
|
||||
.. _idf-tools-export:
|
||||
|
||||
Export scripts
|
||||
Export Scripts
|
||||
--------------
|
||||
|
||||
Since the installed tools are not permanently added into the user or system ``PATH`` environment variable, an extra step is required to use them in the command line. The following scripts modify the environment variables in the current shell to make the correct versions of the tools available:
|
||||
Since the installed tools are not permanently added to the user or system ``PATH`` environment variable, an extra step is required to use them in the command line. The following scripts modify the environment variables in the current shell to make the correct versions of the tools available:
|
||||
|
||||
* ``export.bat`` for Windows Command Prompt
|
||||
* ``export.ps1`` for Powershell
|
||||
@ -158,29 +182,29 @@ Since the installed tools are not permanently added into the user or system ``PA
|
||||
|
||||
.. note::
|
||||
|
||||
To modify the shell environment in Bash, ``export.sh`` must be "sourced": ``. ./export.sh`` (note the leading dot and space).
|
||||
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 the ``IDF_PATH`` environment variable must be set before running the script. When used in Bash, the script will guess the ``IDF_PATH`` value from its own location.
|
||||
``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.
|
||||
|
||||
In addition to calling ``idf_tools.py``, these scripts list the directories which have been added to the ``PATH``.
|
||||
In addition to calling ``idf_tools.py``, these scripts list the directories that have been added to the ``PATH``.
|
||||
|
||||
Other installation methods
|
||||
Other Installation Methods
|
||||
--------------------------
|
||||
|
||||
Depending on the environment, more user-friendly wrappers for ``idf_tools.py`` are provided:
|
||||
|
||||
* :ref:`IDF Tools installer for Windows <get-started-windows-tools-installer>` can download and install the tools. Internally the installer uses ``idf_tools.py``.
|
||||
* `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ includes a menu item to set up the tools. Internally the plugin calls ``idf_tools.py``.
|
||||
* `VSCode Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_ for ESP-IDF includes an onboarding flow. This flow helps setting up the tools. Although the extension does not rely on ``idf_tools.py``, the same installation method is used.
|
||||
* :ref:`ESP-IDF Tools Installer <get-started-windows-tools-installer>` can download and install the tools. Internally the installer uses ``idf_tools.py``.
|
||||
* `ESP-IDF Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ includes a menu item to set up the tools. Internally the plugin calls ``idf_tools.py``.
|
||||
* `VSCode ESP-IDF Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_ includes an onboarding flow. This flow helps set up the tools. Although the extension does not rely on ``idf_tools.py``, the same installation method is used.
|
||||
|
||||
Custom installation
|
||||
Custom Installation
|
||||
-------------------
|
||||
|
||||
Although the methods above are recommended for ESP-IDF users, they are not a must for building ESP-IDF applications. ESP-IDF build system expects that all the necessary tools are installed somewhere, and made available in the ``PATH``.
|
||||
|
||||
.. _idf-tools-list:
|
||||
|
||||
List of IDF Tools
|
||||
-----------------
|
||||
List of ESP-IDF Tools
|
||||
---------------------
|
||||
|
||||
.. include-build-file:: idf-tools-inc.rst
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
ESP-IDF 前端工具 - idf.py
|
||||
**********************************
|
||||
|
||||
:link_to_translation:`en:English`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
``idf.py`` 命令行工具提供了一个前端界面，管理工程构建、工程部署及工程调试等操作。该前端界面使用多项工具，如：
|
||||
|
||||
|
||||
@ -1 +1,210 @@
|
||||
.. include:: ../../../en/api-guides/tools/idf-tools.rst
|
||||
可下载的 ESP-IDF 工具
|
||||
===============================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
构建过程中，ESP-IDF 依赖许多工具，如交叉编译工具链、CMake 构建系统等。
|
||||
|
||||
如 :doc:`快速入门 <../../get-started/index>` 所述，若所需工具版本可用，首选使用当前操作系统的软件包管理器（如 apt、yum、brew 等）安装相关工具。例如，在 Linux 和 macOS 系统中，建议用 Linux 和 macOS 系统的软件包管理器安装 CMake。
|
||||
|
||||
但部分 ESP-IDF 的特定工具在操作系统软件包存储库中不可用，且不同版本的 ESP-IDF 需相应使用不同版本的工具运行。为解决以上两个问题，ESP-IDF 提供了一组脚本，可以下载和安装正确的工具版本，并设置相应运行环境。
|
||||
|
||||
下文中，这类可下载的工具简称为“工具”。除此类工具外，ESP-IDF 还使用以下工具：
|
||||
|
||||
* ESP-IDF 捆绑的 Python 脚本，如 ``idf.py``
|
||||
* 从 PyPI 安装的 Python 软件包
|
||||
|
||||
以下各小节介绍了可下载工具的安装方法，并提供了在不同平台上安装的工具列表。
|
||||
|
||||
.. note::
|
||||
|
||||
本文档面向需要自定义其安装过程的高级用户、希望了解安装过程的用户以及 ESP-IDF 开发人员。
|
||||
|
||||
要了解如何安装 ESP-IDF 工具，请参阅 :doc:`快速入门 <../../get-started/index>`。
|
||||
|
||||
|
||||
工具元数据文件
|
||||
-------------------
|
||||
|
||||
各平台所需工具及工具版本列表存放在 :idf_file:`tools/tools.json` 文件中，:idf_file:`tools/tools_schema.json` 定义了该文件的模式。
|
||||
|
||||
在安装工具或设置环境变量时，:idf_file:`tools/idf_tools.py` 脚本将使用上述文件。
|
||||
|
||||
.. _idf-tools-path:
|
||||
|
||||
工具安装目录
|
||||
----------------------------
|
||||
|
||||
``IDF_TOOLS_PATH`` 环境变量指定下载及安装工具的位置。若未设置该变量，Linux 和 macOS 系统的默认下载安装位置为 ``HOME/.espressif``，Windows 系统的默认下载安装位置为 ``%USER_PROFILE%\.espressif``。
|
||||
|
||||
在 ``IDF_TOOLS_PATH`` 目录下，工具安装脚本会创建以下子目录和文件：
|
||||
|
||||
- ``dist`` — 工具存档下载位置。
|
||||
- ``tools`` — 工具解压缩位置。工具会解压缩到子目录 ``tools/TOOL_NAME/VERSION/`` 中，该操作支持同时安装不同版本的工具。
|
||||
- ``idf-env.json`` — “目标 (target)”和“功能 (feature)”等用户安装选项均存储在此文件中。“目标”为选择需要安装和保持更新的工具的芯片目标；“功能”则决定应安装哪些 Python 软件包。有关用户安装选项的详情，请参阅下文。
|
||||
- ``python_env`` — 与工具无关；虚拟 Python 环境安装在其子目录中。注意，设置 ``IDF_PYTHON_ENV_PATH`` 环境变量可以将 Python 环境目录放置到其他位置。
|
||||
- ``espidf.constraints.*.txt`` — 每个 ESP-IDF 版本都有的约束文件，包含 Python 包版本要求。
|
||||
|
||||
GitHub 资源镜像
|
||||
-----------------------
|
||||
|
||||
工具下载器下载的工具大多属于 GitHub 发布的资源，即在 GitHub 上伴随软件发布的文件。
|
||||
|
||||
如果无法访问 GitHub 下载或访问速度较慢，可以配置一个 GitHub 资源镜像。
|
||||
|
||||
要使用乐鑫下载服务器，请将环境变量 ``IDF_GITHUB_ASSETS`` 设置为 ``dl.espressif.com/github_assets``。安装过程中，当从 ``github.com`` 下载工具时，URL 将重写为使用乐鑫下载服务器。
|
||||
|
||||
只要 URL 与 ``github.com`` 的下载 URL 格式匹配，任何镜像服务器均可使用，安装过程中下载的 GitHub 资源 URL 将把 ``https://github.com`` 替换为 ``https://${IDF_GITHUB_ASSETS}``。
|
||||
|
||||
.. note:: 目前，乐鑫下载服务器不会镜像 GitHub 上的所有内容，只镜像部分发布版本的附件资源文件及源文件。
|
||||
|
||||
|
||||
``idf_tools.py`` 脚本
|
||||
---------------------------------------
|
||||
|
||||
ESP-IDF 随附的 :idf_file:`tools/idf_tools.py` 脚本具备以下功能：
|
||||
|
||||
* ``install``：将工具下载到 ``${IDF_TOOLS_PATH}/dist`` 目录，并解压缩到 ``${IDF_TOOLS_PATH}/tools/TOOL_NAME/VERSION``。
|
||||
|
||||
``install`` 命令接收 ``TOOL_NAME`` 或 ``TOOL_NAME@VERSION`` 格式的安装工具列表。如果给定参数 ``all``，则会安装列表上的所有工具，包括必须项和可选项。如果没有给定参数，或给定参数为 ``required``，则只安装必须项。
|
||||
|
||||
* ``download``：与 ``install`` 类似，但不会解压缩工具。使用可选项 ``--platform`` 可下载特定平台的工具。
|
||||
|
||||
* ``export``：列出使用已安装工具前应设置的环境变量。对多数工具而言，只需要设置环境变量 ``PATH``，但也有些工具需要设置额外的环境变量。
|
||||
|
||||
环境变量可以以 ``shell`` 或 ``key-value`` 格式列出，使用 ``--format`` 参数设置该选项。
|
||||
|
||||
- ``export`` 可选参数：
|
||||
|
||||
- ``--unset``：该参数可用于创建语句，取消特定全局变量设置，使环境恢复到调用 ``export.{sh/fish}`` 前的状态。
|
||||
- ``--add_paths_extras``：该参数将 ``$PATH`` 中与 ESP-IDF 相关的额外路径添加到 ``${IDF_TOOLS_PATH}/esp-idf.json`` 中，以保证在退出当前 ESP-IDF 环境时删除全局变量。例如，在运行 ``export.{sh/fish}`` 脚本时，如果在全局变量 ``$PATH`` 中添加了新的路径，在命令中添加该参数可以将这些新路径保存到 ``${IDF_TOOLS_PATH}/esp-idf.json`` 文件中。
|
||||
|
||||
- ``shell``：生成适合在 shell 中执行的输出，例如，在 Linux 和 macOS 上生成以下输出
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
export PATH="/home/user/.espressif/tools/tool/v1.0.0/bin:$PATH"
|
||||
|
||||
在 Windows 上生成以下输出
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
set "PATH=C:\Users\user\.espressif\tools\v1.0.0\bin;%PATH%"
|
||||
|
||||
.. note::
|
||||
|
||||
当前不支持以 Powershell 格式导出环境变量，可以用 ``key-value`` 格式代替。
|
||||
|
||||
如果 shell 支持，则该命令的输出可用于更新环境变量。例如
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
eval $($IDF_PATH/tools/idf_tools.py export)
|
||||
|
||||
- ``key-value``：以 ``VARIABLE=VALUE`` 格式生成输出，以便其他脚本解析
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
PATH=/home/user/.espressif/tools/tool/v1.0.0:$PATH
|
||||
|
||||
注意，用于处理此输出的脚本必须对输出中的 ``$VAR`` 或 ``%VAR%`` 模式进行扩展，即解析成对应变量。
|
||||
|
||||
* ``list``：列出已知的工具版本，并指示哪些版本已安装。
|
||||
|
||||
以下选项可用于自定义输出。
|
||||
|
||||
- ``--outdated``：仅列出安装在 ``IDF_TOOLS_PATH`` 中的过时版本工具。
|
||||
|
||||
* ``check``：检查每个工具是否在系统路径和 ``IDF_TOOLS_PATH`` 中可用。
|
||||
|
||||
* ``install-python-env``：在 ``${IDF_TOOLS_PATH}/python_env`` 目录或直接在 ``IDF_PYTHON_ENV_PATH`` 环境变量设置的目录中创建 Python 虚拟环境，并在其中安装所需的 Python 软件包。
|
||||
|
||||
* 参数 ``--features`` 为可选项，用于指定要添加或删除的功能列表，功能之间用逗号分隔。
|
||||
|
||||
#. 该参数将删除以 ``-`` 开头的功能，添加以 ``+`` 开头或无符号标记的功能。例如，要删除功能 ``XY``，示例语法为 ``--features=-XY``；要添加功能 ``XY``，示例语法为 ``--features=+XY`` 或 ``--features=XY``。如果为同一功能同时提供了删除和添加选项，则不执行任何操作。
|
||||
|
||||
#. 每个功能都必须有依赖文件。例如，只有当 ``${IDF_PATH}/tools/requirements/requirements.XY.txt`` 文件已存在，并包含要安装的 Python 包列表时，功能 ``XY`` 才有效。
|
||||
|
||||
#. ``core`` 功能为必须项，确保 ESP-IDF 的核心功能，如控制台中的构建、烧录、监视器、调试等。
|
||||
|
||||
#. 用户可选择任意数量的可选功能，已选功能列表存储在 ``idf-env.json`` 中。
|
||||
|
||||
#. 依赖文件中存储了需要安装的 Python 包以及 ``espidf.constraints.*.txt`` 文件，该约束文件从 https://dl.espressif.com 下载，并存储在 ``${IDF_TOOLS_PATH}`` 目录，包含了针对特定 ESP-IDF 版本的安装包版本要求。
|
||||
|
||||
.. note::
|
||||
|
||||
可以通过使用 ``--no-constraints`` 参数或将环境变量 ``IDF_PYTHON_CHECK_CONSTRAINTS`` 设置为 ``no``，禁用约束文件的下载和使用，但 **并不建议此做法**。
|
||||
|
||||
* ``check-python-dependencies``：检查所有必需的 Python 包是否均已安装。该命令会对比检查由 ``idf-env.json`` 功能列表从 ``${IDF_PATH}/tools/requirements/requirements.*.txt`` 所选择的软件包与 ``espidf.constraints.*.txt`` 文件指定的软件包版本是否一致。
|
||||
|
||||
.. note::
|
||||
|
||||
约束文件可通过 ``install-python-env`` 命令下载。与 ``install-python-env`` 命令类似，可以通过使用 ``--no-constraints`` 参数或将环境变量 ``IDF_PYTHON_CHECK_CONSTRAINTS`` 设置为 ``no``，禁止使用约束文件。
|
||||
|
||||
* ``uninstall``：打印并删除当前 ESP-IDF 版本未使用的工具。
|
||||
|
||||
- ``--dry-run`` 打印已安装但未使用的工具。
|
||||
- ``--remove-archives`` 删除过去下载的所有旧版本软件安装包。
|
||||
|
||||
.. _idf-tools-install:
|
||||
|
||||
安装脚本
|
||||
---------------
|
||||
|
||||
ESP-IDF 的根目录中提供了针对不同 shell 的用户安装脚本，包括：
|
||||
|
||||
* ``install.bat`` 适用于 Windows 命令提示符
|
||||
* ``install.ps1`` 适用于 Powershell
|
||||
* ``install.sh`` 适用于 Bash
|
||||
* ``install.fish`` 适用于 Fish
|
||||
|
||||
这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外，还会准备一个 Python 虚拟环境，并在此虚拟环境中安装所需软件包。
|
||||
|
||||
为启用相应功能，这些脚本可以选择性地接受一组以逗号分隔的芯片目标列表及 ``--enable-*`` 参数，这类参数会传递给 ``idf_tools.py`` 脚本，并由该脚本将这类参数存储在 ``idf-env.json`` 中，从而逐步启用芯片目标及功能。
|
||||
|
||||
要为所有芯片目标安装工具，请在不使用任何可选参数的情况下，运行 ``idf_tools.py install --targets=all``。要安装具备 ESP-IDF 核心功能的 Python 软件包，请运行 ``idf_tools.py install-python-env --features=core``。
|
||||
|
||||
也可为特定芯片安装工具，例如，运行 ``install.sh esp32`` 可以只为 ESP32 安装工具。更多相关示例，请参阅 :ref:`第三步：设置工具 <get-started-set-up-tools>`。
|
||||
|
||||
运行 ``idf_tools.py install-python-env --features=core,XY``，``install.sh --enable-XY`` 可以启用 ``XY`` 功能。
|
||||
|
||||
.. _idf-tools-export:
|
||||
|
||||
导出脚本
|
||||
--------------
|
||||
|
||||
由于安装好的工具并非永久添加到用户或系统的 ``PATH`` 环境变量中，因此，要在命令行中使用这些工具，还需要额外步骤。以下脚本会修改当前 shell 的环境变量，从而使用正确版本的工具：
|
||||
|
||||
* ``export.bat`` 适用于 Windows 命令提示符
|
||||
* ``export.ps1`` 适用于 Powershell
|
||||
* ``export.sh`` 适用于 Bash
|
||||
* ``export.fish`` 适用于 Fish
|
||||
|
||||
.. note::
|
||||
|
||||
在 Bash 中修改 shell 环境时，必须使用 ``. ./export.sh`` 命令加载 ``export.sh``，注意添加前面的点和空格。
|
||||
|
||||
``export.sh`` 可以在除了 Bash 外的其他 shell（如 zsh）中使用。但在这种情况下，必须在运行脚本前设置 ``IDF_PATH`` 环境变量。在 Bash 中使用时，脚本会从当前目录猜测 ``IDF_PATH`` 的值。
|
||||
|
||||
除了调用 ``idf_tools.py``，这些脚本还会列出已经添加到 ``PATH`` 的目录。
|
||||
|
||||
其他安装方法
|
||||
--------------------------
|
||||
|
||||
为适用于不同环境，ESP-IDF 提供了更多用户友好的 ``idf_tools.py`` 包装工具：
|
||||
|
||||
* :ref:`ESP-IDF 工具安装器 <get-started-windows-tools-installer>` 支持下载和安装工具，其内部使用 ``idf_tools.py`` 实现功能。
|
||||
* `ESP-IDF Eclipse 插件 <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ 包括了一个用于设置工具的菜单项，该插件内部调用 ``idf_tools.py``。
|
||||
* `VSCode ESP-IDF 扩展 <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_ 提供了设置工具的入门流程。尽管此扩展包不依赖 ``idf_tools.py``，但安装方法相同。
|
||||
|
||||
自定义安装
|
||||
-------------------
|
||||
|
||||
推荐用户使用上述方法安装 ESP-IDF 工具，但也可以选择其他方式来构建 ESP-IDF 应用程序。自定义安装时，用户需将所有必要的工具都安装在某个位置，并在 ``PATH`` 中定义，以保证 ESP-IDF 构建系统可用。
|
||||
|
||||
.. _idf-tools-list:
|
||||
|
||||
ESP-IDF 工具列表
|
||||
---------------------
|
||||
|
||||
.. include-build-file:: idf-tools-inc.rst
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user