mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/add_Chinese_translation_for_api-guides/tools/idf-py' into 'master'
docs: add CN translation for api-guides/tools/idf-py.rst Closes DOC-5123 See merge request espressif/esp-idf!23568
This commit is contained in:
Cai Xin Ying
commit
fd8cf21e4b
@ -1,205 +1,183 @@
|
||||
IDF Frontend - idf.py
|
||||
*********************
|
||||
ESP-IDF Frontend - idf.py
|
||||
*************************
|
||||
|
||||
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:
|
||||
:link_to_translation:`zh_CN:中文版`
|
||||
|
||||
- CMake_, which configures the project to be built
|
||||
- Ninja_ which builds the project
|
||||
- `esptool.py`_ for flashing the target.
|
||||
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:
|
||||
|
||||
The :ref:`getting started guide <get-started-configure>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
|
||||
- CMake_, which configures the project to be built.
|
||||
- Ninja_, which builds the project.
|
||||
- `esptool.py`_, which flashes the target.
|
||||
|
||||
The :ref:`Step 5. First Steps on ESP-IDF <get-started-configure>` contains a brief introduction on how to set up ``idf.py`` to configure, build, and flash projects.
|
||||
|
||||
.. important::
|
||||
|
||||
``idf.py`` should be run in an ESP-IDF "project" directory, i.e. one containing a ``CMakeLists.txt`` file.
|
||||
Older style projects with a ``Makefile`` will not work with ``idf.py``.
|
||||
``idf.py`` should be run in an ESP-IDF project directory, i.e., a directory containing a ``CMakeLists.txt`` file. Older style projects that contain a ``Makefile`` will not work with ``idf.py``.
|
||||
|
||||
Commands
|
||||
========
|
||||
|
||||
Start a new project: create-project
|
||||
------------------------------------
|
||||
Start a New Project: ``create-project``
|
||||
------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py create-project <project name>
|
||||
|
||||
This will create a new ESP-IDF project, additionally folder where the project will
|
||||
be created can be specified by the ``--path`` option.
|
||||
This command creates a new ESP-IDF project. Additionally, the folder where the project will be created in can be specified by the ``--path`` option.
|
||||
|
||||
Create a new component: create-component
|
||||
----------------------------------------
|
||||
|
||||
This command creates a new component, which will have a minimum set of files
|
||||
necessary for building.
|
||||
Create a New Component: ``create-component``
|
||||
-----------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py create-component <component name>
|
||||
|
||||
The ``-C`` option can be used to specify the directory the component will be
|
||||
created in.
|
||||
For more information about components see the :ref:`build system page <component-directories>`.
|
||||
This command creates a new component, which will have a minimum set of files necessary for building. The ``-C`` option can be used to specify the directory the component will be created in. For more information about components see the :ref:`Component CMakeLists Files <component-directories>`.
|
||||
|
||||
.. _selecting-idf-target:
|
||||
|
||||
Select the Target Chip: set-target
|
||||
----------------------------------
|
||||
Select the Target Chip: ``set-target``
|
||||
-----------------------------------------
|
||||
|
||||
ESP-IDF supports multiple targets (chips). A full list of supported targets in your version of ESP-IDF can be seen by running ``idf.py --list-targets``.
|
||||
|
||||
This sets the current project target:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py set-target <target>
|
||||
|
||||
This command sets the current project target.
|
||||
|
||||
.. important::
|
||||
|
||||
``idf.py set-target`` will clear the build directory and re-generate the ``sdkconfig`` file from scratch. The old ``sdkconfig`` file will be saved as ``sdkconfig.old``.
|
||||
|
||||
.. note::
|
||||
|
||||
The behavior of ``idf.py set-target`` command is equivalent to:
|
||||
The behavior of the ``idf.py set-target`` command is equivalent to:
|
||||
|
||||
1. clearing the build directory (``idf.py fullclean``)
|
||||
2. removing the sdkconfig file (``mv sdkconfig sdkconfig.old``)
|
||||
3. configuring the project with the new target (``idf.py -DIDF_TARGET=esp32 reconfigure``)
|
||||
|
||||
It is also possible to pass the desired ``IDF_TARGET`` as an environment variable (e.g. ``export IDF_TARGET=esp32s2``) or as a CMake variable (e.g. ``-DIDF_TARGET=esp32s2`` argument to CMake or idf.py). Setting the environment variable is a convenient method if you mostly work with one type of the chip.
|
||||
It is also possible to pass the desired ``IDF_TARGET`` as an environment variable (e.g., ``export IDF_TARGET=esp32s2``) or as a CMake variable (e.g., ``-DIDF_TARGET=esp32s2`` argument to CMake or ``idf.py`` ). Setting the environment variable is a convenient method if you mostly work with one type of the chip.
|
||||
|
||||
To specify the _default_ value of ``IDF_TARGET`` for a given project, add ``CONFIG_IDF_TARGET`` value to ``sdkconfig.defaults``. For example, ``CONFIG_IDF_TARGET="esp32s2"``. This value will be used if ``IDF_TARGET`` is not specified by other method: using an environment variable, CMake variable, or ``idf.py set-target`` command.
|
||||
To specify the default value of ``IDF_TARGET`` for a given project, please add the ``CONFIG_IDF_TARGET`` option to the project's ``sdkconfig.defaults`` file, e.g., ``CONFIG_IDF_TARGET="esp32s2"``. This value of the option will be used if ``IDF_TARGET`` is not specified by other methods, such as using an environment variable, a CMake variable, or the ``idf.py set-target`` command.
|
||||
|
||||
If the target has not been set by any of these methods, the build system will default to ``esp32`` target.
|
||||
|
||||
Start the graphical configuration tool: menuconfig
|
||||
--------------------------------------------------
|
||||
Start the Graphical Configuration Tool: ``menuconfig``
|
||||
--------------------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py menuconfig
|
||||
|
||||
Build the project: build
|
||||
------------------------
|
||||
Build the Project: ``build``
|
||||
-------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py build
|
||||
|
||||
Running this command will build the project found in the current directory. This can involve multiple steps:
|
||||
This command builds the project found in the current directory. This can involve multiple steps:
|
||||
|
||||
- Create the build directory if needed. The sub-directory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
|
||||
- Run CMake_ as necessary to configure the project and generate build files for the main build tool.
|
||||
- Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
|
||||
|
||||
Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
|
||||
Building is incremental, so if no source files or configuration has changed since the last build, nothing will be done.
|
||||
|
||||
Additionally, the command can be run with ``app``, ``bootloader`` and
|
||||
``partition-table`` arguments to build only the app, bootloader or partition table
|
||||
as applicable.
|
||||
Additionally, the command can be run with ``app``, ``bootloader`` and ``partition-table`` arguments to build only the app, bootloader or partition table as applicable.
|
||||
|
||||
Remove the build output: clean
|
||||
------------------------------
|
||||
|
||||
It is possible to remove the project build output files from the build directory by
|
||||
using:
|
||||
Remove the Build Output: ``clean``
|
||||
-------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py clean
|
||||
|
||||
The project will be fully rebuilt on next build.
|
||||
Using this does not remove the CMake configuration output inside the build folder.
|
||||
This command removes the project build output files from the build directory, and the project will be fully rebuilt on next build. Using this command does not remove the CMake configuration output inside the build folder.
|
||||
|
||||
Delete the entire build contents: fullclean
|
||||
-------------------------------------------
|
||||
Delete the Entire Build Contents: ``fullclean``
|
||||
--------------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py fullclean
|
||||
|
||||
Running this command will delete the entire "build" directory contents.
|
||||
This includes all CMake configuration output.
|
||||
The next time the project is built, CMake will configure it from scratch.
|
||||
Note that this option recursively deletes *all* files in the build directory, so use with care.
|
||||
Project configuration is not deleted.
|
||||
This command deletes the entire "build" directory contents, which includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes **all** files in the build directory, so use with care. Project configuration is not deleted.
|
||||
|
||||
Flash the project: flash
|
||||
------------------------
|
||||
|
||||
Running the following command:
|
||||
Flash the Project: ``flash``
|
||||
-------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py flash
|
||||
|
||||
will automatically build the project if necessary, and then flash it to the target.
|
||||
You can use ``-p`` and ``-b`` options to set serial port name and flasher baud rate, respectively.
|
||||
This command automatically builds the project if necessary, and then flash it to the target. You can use ``-p`` and ``-b`` options to set serial port name and flasher baud rate, respectively.
|
||||
|
||||
.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
|
||||
|
||||
Similarly to the ``build`` command, the command can be run with ``app``,
|
||||
``bootloader`` and ``partition-table`` arguments to flash only the app, bootloader
|
||||
or partition table as applicable.
|
||||
Similarly to the ``build`` command, the command can be run with ``app``, ``bootloader`` and ``partition-table`` arguments to flash only the app, bootloader or partition table as applicable.
|
||||
|
||||
Hints on how to resolve errors
|
||||
Hints on How to Resolve Errors
|
||||
==============================
|
||||
|
||||
``idf.py`` will try to suggest hints on how to resolve errors. It works with a database of hints stored in :idf_file:`tools/idf_py_actions/hints.yml` and the hints will be printed if a match is found for the given error. The menuconfig target is not supported at the moment by automatic hints on resolving errors.
|
||||
|
||||
The ``--no-hints`` argument of ``idf.py`` can be used to turn the hints off in case they are not desired.
|
||||
|
||||
Important notes
|
||||
Important Notes
|
||||
===============
|
||||
|
||||
Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the target before running the serial monitor.
|
||||
|
||||
The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (i.e. building before flashing, erasing before flashing, etc.).
|
||||
The order of multiple ``idf.py`` commands on the same invocation is not important, as they will automatically be executed in the correct order for everything to take effect (e.g., building before flashing, erasing before flashing).
|
||||
|
||||
For commands that are not known to ``idf.py`` an attempt to execute them as a build system target will be made.
|
||||
For commands that are not known to ``idf.py``, an attempt to execute them as a build system target will be made.
|
||||
|
||||
The command ``idf.py`` supports `shell autocompletion <https://click.palletsprojects.com/shell-completion/>`_ for bash, zsh and fish shells.
|
||||
|
||||
In order to make `shell autocompletion <https://click.palletsprojects.com/shell-completion/>`_ supported, please make sure you have at least Python 3.5 and `click <https://click.palletsprojects.com/>`_ 7.1 or newer (:ref:`see also <get-started-get-prerequisites>`).
|
||||
In order to make `shell autocompletion <https://click.palletsprojects.com/shell-completion/>`_ supported, please make sure you have at least Python 3.5 and `click <https://click.palletsprojects.com/>`_ 7.1 or newer (:ref:`Software <get-started-get-prerequisites>`).
|
||||
|
||||
To enable autocompletion for ``idf.py`` use the ``export`` command (:ref:`see this <get-started-set-up-env>`). Autocompletion is initiated by pressing the TAB key. Type ``idf.py -`` and press the TAB key to autocomplete options.
|
||||
To enable autocompletion for ``idf.py``, use the ``export`` command (:ref:`Step 4. Set up the environment variables <get-started-set-up-env>`). Autocompletion is initiated by pressing the TAB key. Type ``idf.py -`` and press the TAB key to autocomplete options.
|
||||
|
||||
The autocomplete support for PowerShell is planned in the future.
|
||||
|
||||
Advanced Commands
|
||||
=================
|
||||
|
||||
Open the documentation: docs
|
||||
----------------------------
|
||||
|
||||
Using the following command the documentation for the projects target and version
|
||||
will be opened in the browser:
|
||||
Open the Documentation: ``docs``
|
||||
-----------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py docs
|
||||
|
||||
Show size: size
|
||||
---------------
|
||||
This command opens the documentation for the projects target and ESP-IDF version in the browser.
|
||||
|
||||
Show Size: ``size``
|
||||
-----------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py size
|
||||
|
||||
Will print app size information including occupied RAM and FLASH and section sizes.
|
||||
This command prints app size information including the occupied RAM and flash and section (i.e., .bss) sizes.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py size-components
|
||||
|
||||
Similarly, this will print the same information for each component used in the project.
|
||||
Similarly, this command prints the same information for each component used in the project.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py size-files
|
||||
|
||||
Will print size information per source file in the project.
|
||||
This command prints size information per source file in the project.
|
||||
|
||||
Options
|
||||
^^^^^^^
|
||||
@ -207,44 +185,40 @@ Options
|
||||
- ``--format`` specifies the output format with available options: ``text``, ``csv``, ``json``, default being ``text``.
|
||||
- ``--output-file`` optionally specifies the name of the file to print the command output to instead of the standard output.
|
||||
|
||||
Reconfigure the project: reconfigure
|
||||
------------------------------------
|
||||
Reconfigure the Project: ``reconfigure``
|
||||
-------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py reconfigure
|
||||
|
||||
This command re-runs CMake_ even if it doesn't seem to need re-running.
|
||||
This isn't necessary during normal usage, but can be useful after adding/removing
|
||||
files from the source tree, or when modifying CMake cache variables.
|
||||
For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``.
|
||||
This command forces CMake_ to be rerun regardless of whether it is necessary. It's unnecessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``.
|
||||
|
||||
Clean the python byte code: python-clean
|
||||
----------------------------------------
|
||||
|
||||
Generated python byte code can be deleted from the IDF directory using:
|
||||
Clean the Python Byte Code: ``python-clean``
|
||||
-----------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py python-clean
|
||||
|
||||
The byte code may cause issues when switching between IDF and Python versions.
|
||||
It is advised to run this target after switching versions of Python.
|
||||
This command deletes generated python byte code from the ESP-IDF directory. The byte code may cause issues when switching between ESP-IDF and Python versions. It is advised to run this target after switching versions of Python.
|
||||
|
||||
Global Options
|
||||
==============
|
||||
|
||||
To list all available root level options, run ``idf.py --help``. To list options that are specific for a subcommand, run ``idf.py <command> --help``, for example ``idf.py monitor --help``. Here is a list of some useful options:
|
||||
To list all available root level options, run ``idf.py --help``. To list options that are specific for a subcommand, run ``idf.py <command> --help``, e.g., ``idf.py monitor --help``. Here is a list of some useful options:
|
||||
|
||||
- ``-C <dir>`` allows overriding the project directory from the default current working directory.
|
||||
- ``-B <dir>`` allows overriding the build directory from the default ``build`` subdirectory of the project directory.
|
||||
- ``--ccache`` flag can be used to enable CCache_ when compiling source files, if the CCache_ tool is installed. This can dramatically reduce some build times.
|
||||
- ``--ccache`` enables CCache_ when compiling source files if the CCache_ tool is installed. This can dramatically reduce the build time.
|
||||
|
||||
Note that some older versions of CCache may exhibit bugs on some platforms, so if files are not rebuilt as expected then try disabling CCache and build again. CCache can be enabled by default by setting the ``IDF_CCACHE_ENABLE`` environment variable to a non-zero value.
|
||||
.. important::
|
||||
|
||||
Note that some older versions of CCache_ may exhibit bugs on some platforms, so if files are not rebuilt as expected, try disabling CCache_ and rebuiling the project. To enable CCache_ by default, set the ``IDF_CCACHE_ENABLE`` environment variable to a non-zero value.
|
||||
|
||||
- ``-v`` flag causes both ``idf.py`` and the build system to produce verbose build output. This can be useful for debugging build problems.
|
||||
- ``--cmake-warn-uninitialized`` (or ``-w``) will cause 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 to disable hints on resolving errors and disable capturing output.
|
||||
- ``--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.
|
||||
|
||||
.. _cmake: https://cmake.org
|
||||
.. _ninja: https://ninja-build.org
|
||||
|
||||
@ -1 +1,226 @@
|
||||
.. include:: ../../../en/api-guides/tools/idf-py.rst
|
||||
ESP-IDF 前端工具 - idf.py
|
||||
**********************************
|
||||
|
||||
:link_to_translation:`en:English`
|
||||
|
||||
``idf.py`` 命令行工具提供了一个前端界面，管理工程构建、工程部署及工程调试等操作。该前端界面使用多项工具，如：
|
||||
|
||||
- CMake_ 用于配置要构建的工程。
|
||||
- Ninja_ 用于构建工程。
|
||||
- `esptool.py`_ 用于烧录目标芯片。
|
||||
|
||||
:ref:`第五步：开始使用 ESP-IDF 吧 <get-started-configure>` 简要介绍了设置 ``idf.py`` 以配置、构建及烧录工程的操作流程。
|
||||
|
||||
.. important::
|
||||
|
||||
``idf.py`` 应在 ESP-IDF 工程目录下运行，即包含 ``CMakeLists.txt`` 文件的目录。旧版本工程，即包含 ``Makefile`` 的目录，与 ``idf.py`` 不兼容。
|
||||
|
||||
常用命令
|
||||
=============
|
||||
|
||||
创建新工程：``create-project``
|
||||
------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py create-project <project name>
|
||||
|
||||
此命令将创建一个新的 ESP-IDF 工程。此外，使用 ``--path`` 选项可指定工程创建路径。
|
||||
|
||||
创建新组件：``create-component``
|
||||
----------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py create-component <component name>
|
||||
|
||||
此命令将创建一个新的组件，包含构建所需的最基本文件集。使用 ``-C`` 选项可指定组件创建目录。有关组件的更多信息，请参阅 :ref:`组件 CMakeLists 文件 <component-directories>`。
|
||||
|
||||
.. _selecting-idf-target:
|
||||
|
||||
选择目标芯片：``set-target``
|
||||
----------------------------------
|
||||
|
||||
ESP-IDF 支持多个目标芯片，运行 ``idf.py --list-targets`` 查看当前 ESP-IDF 版本支持的所有目标芯片。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py set-target <target>
|
||||
|
||||
此命令将设置当前工程的目标芯片。
|
||||
|
||||
.. important::
|
||||
|
||||
``idf.py set-target`` 将清除构建目录，并重新生成 ``sdkconfig`` 文件，原来的 ``sdkconfig`` 文件保存为 ``sdkconfig.old``。
|
||||
|
||||
.. note::
|
||||
|
||||
``idf.py set-target`` 命令与以下操作效果相同：
|
||||
|
||||
1. 清除构建目录 (``idf.py fullclean``)
|
||||
2. 删除 sdkconfig 文件 (``mv sdkconfig sdkconfig.old``)
|
||||
3. 使用新的目标芯片重新配置工程 (``idf.py -DIDF_TARGET=esp32 reconfigure``)
|
||||
|
||||
所需的 ``IDF_TARGET`` 还可以作为环境变量（如 ``export IDF_TARGET=esp32s2``）或 CMake 变量（如将 ``-DIDF_TARGET=esp32s2`` 作为 CMake 或 ``idf.py`` 的参数）传递。在经常使用同类芯片的情况下，设置环境变量将使操作更加便利。
|
||||
|
||||
要给指定工程设定 ``IDF_TARGET`` 的默认值，请将 ``CONFIG_IDF_TARGET`` 选项添加到该工程的 ``sdkconfig.defaults`` 文件（如 ``CONFIG_IDF_TARGET="esp32s2"``）。若未通过使用环境变量、CMake 变量或 ``idf.py set-target`` 命令等方法指定 ``IDF_TARGET``，则默认使用该选项的值。
|
||||
|
||||
若未通过以上任一方法设置目标芯片，构建系统将默认使用 ``esp32``。
|
||||
|
||||
启动图形配置工具：``menuconfig``
|
||||
--------------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py menuconfig
|
||||
|
||||
构建工程：``build``
|
||||
------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py build
|
||||
|
||||
此命令将构建当前目录下的工程，具体步骤如下：
|
||||
|
||||
- 若有需要，创建构建子目录 ``build`` 保存构建输出文件，使用 ``-B`` 选项可改变子目录的路径。
|
||||
- 必要时运行 CMake_ 配置工程，并为主要构建工具生成构建文件。
|
||||
- 运行主要构建工具（Ninja_ 或 ``GNU Make``）。默认情况下，构建工具会完成自动检测，也可通过将 ``-G`` 选项传递给 ``idf.py`` 来显式设置构建工具。
|
||||
|
||||
构建是增量行为，因此若上次构建结束后，源文件或配置并未发生更改，则不会执行任何操作。
|
||||
|
||||
此外，使用 ``app``、``bootloader`` 或 ``partition-table`` 参数运行此命令，可选择仅构建应用程序、引导加载程序或分区表。
|
||||
|
||||
清除构建输出：``clean``
|
||||
------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py clean
|
||||
|
||||
此命令可清除构建目录中的构建输出文件，下次构建时，工程将完全重新构建。注意，使用此选项不会删除构建文件夹内的 CMake 配置输出。
|
||||
|
||||
删除所有构建内容：``fullclean``
|
||||
-------------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py fullclean
|
||||
|
||||
此命令将删除所有 ``build`` 子目录内容，包括 CMake 配置输出。下次构建时， CMake 将重新配置其输出。注意，此命令将递归删除构建目录下的 *所有* 文件（工程配置将保留），请谨慎使用。
|
||||
|
||||
烧录工程：``flash``
|
||||
------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py flash
|
||||
|
||||
此命令将在需要时自动构建工程，随后将其烧录到目标芯片。使用 ``-p`` 和 ``-b`` 选项可分别设置串口名称和烧录程序的波特率。
|
||||
|
||||
.. note:: 环境变量 ``ESPPORT`` 和 ``ESPBAUD`` 可分别设置 ``-p`` 和 ``-b`` 选项的默认值，在命令行上设置这些选项的参数可覆盖默认值。
|
||||
|
||||
与 ``build`` 命令类似，使用 ``app``、``bootloader`` 或 ``partition-table`` 参数运行此命令，可选择仅烧录应用程序、引导加载程序或分区表。
|
||||
|
||||
错误处理提示
|
||||
==============================
|
||||
|
||||
``idf.py`` 使用存储在 :idf_file:`tools/idf_py_actions/hints.yml` 中的提示数据库，当找到与给定错误相匹配的提示时，``idf.py`` 会打印该提示以尝试提供解决方案。目前，错误处理提示不支持 menuconfig 对象。
|
||||
|
||||
若无需该功能，可以通过 ``idf.py`` 的 ``--no-hints`` 参数关闭提示。
|
||||
|
||||
重要提示
|
||||
===============
|
||||
|
||||
多个 ``idf.py`` 命令可以在同一行命令中组合使用。例如，``idf.py -p COM4 clean flash monitor`` 可以清除源代码树、编译工程、并将其烧录到目标芯片，随后运行串行监视器。
|
||||
|
||||
在同一调用中，多个 ``idf.py`` 命令的顺序并不重要，它们将自动以正确的程序执行，以使全部操作生效（例如先构建后烧录、先擦除后烧录）。
|
||||
|
||||
``idf.py`` 会尝试将未知命令作为构建系统目标执行。
|
||||
|
||||
命令 ``idf.py`` 支持 bash、zsh 和 fish shell 的 `shell 自动补全 <https://click.palletsprojects.com/shell-completion/>`_。
|
||||
|
||||
为实现 `shell 自动补全 <https://click.palletsprojects.com/shell-completion/>`_，请确保 Python 版本为 3.5 及以上，`click <https://click.palletsprojects.com/>`_ 版本为 7.1 及以上（请参阅 :ref:`软件 <get-started-get-prerequisites>`）。
|
||||
|
||||
调用命令 ``export`` 为 ``idf.py`` 启用自动补全（:ref:`第四步：设置环境变量 <get-started-set-up-env>`），按 TAB 键启动自动补全。输入 ``idf.py -`` 并按 TAB 键以自动补全选项。
|
||||
|
||||
预计未来版本将支持 PowerShell 自动补全。
|
||||
|
||||
高级命令
|
||||
=================
|
||||
|
||||
打开文档：``docs``
|
||||
----------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py docs
|
||||
|
||||
此命令将在浏览器中打开工程目标芯片和 ESP-IDF 版本对应的文档。
|
||||
|
||||
显示大小：``Size``
|
||||
----------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py size
|
||||
|
||||
此命令将显示应用程序大小，包括占用的 RAM 和 flash 及各部分（如 .bss）的大小。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py size-components
|
||||
|
||||
此命令将显示工程中各个组件的应用程序大小。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py size-files
|
||||
|
||||
该命令将显示工程中每个源文件的大小。
|
||||
|
||||
选项
|
||||
^^^^^^^
|
||||
|
||||
- ``--format`` 指定输出格式，可输出 ``text``、``csv``、 ``json`` 格式，默认格式为 ``text``。
|
||||
- ``--output-file`` 可选参数，可以指定命令输出文件的文件名，而非标准输出。
|
||||
|
||||
重新配置工程：``reconfigure``
|
||||
------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py reconfigure
|
||||
|
||||
此命令将重新运行 CMake_。正常情况下并不会用到该命令，因为一般无需重新运行 CMake，但如果从源代码树中添加或删除了文件，或需要修改 CMake 缓存变量时，将有必要使用该命令。例如，``idf.py -DNAME='VALUE' reconfigure`` 可将变量 ``NAME`` 在 CMake 缓存中设置为值 ``VALUE``。
|
||||
|
||||
清除 Python 字节码：``python-clean``
|
||||
----------------------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py python-clean
|
||||
|
||||
此命令将从 ESP-IDF 目录中删除生成的 Python 字节码。字节码在切换 ESP-IDF 和 Python 版本时可能会引起问题，建议在切换 Python 版本后运行此命令。
|
||||
|
||||
全局选项
|
||||
==============
|
||||
|
||||
运行 ``idf.py --help`` 列出所有可用的根级别选项。要列出特定子命令的选项，请运行 ``idf.py <command> --help``，如 ``idf.py monitor --help``。部分常用选项如下：
|
||||
|
||||
- ``-C <dir>`` 支持从默认的当前工作目录覆盖工程目录。
|
||||
- ``-B <dir>`` 支持从工程目录的默认 ``build`` 子目录覆盖构建目录。
|
||||
- ``--ccache`` 可以在安装了 CCache_ 工具的前提下，在构建源文件时启用 CCache_，减少部分构建耗时。
|
||||
|
||||
.. important::
|
||||
|
||||
注意，某些旧版本 CCache_ 在某些平台上存在 bug，因此如果文件没有按预期重新构建，可禁用 CCache_ 并重新构建。可以通过将环境变量 ``IDF_CCACHE_ENABLE`` 设置为非零值来默认启用 CCache_。
|
||||
|
||||
- ``-v`` 会使 ``idf.py`` 和构建系统生成详细的构建输出，有助于调试构建错误。
|
||||
- ``--cmake-warn-uninitialized`` （或 ``-w``）将使 CMake 只显示在工程目录中发现的变量未初始化的警告，该选项仅控制 CMake 内部的 CMake 变量警告，不控制其他类型的构建警告。将环境变量 ``IDF_CMAKE_WARN_UNINITIALIZED`` 设置为非零值，可永久启用该选项。
|
||||
- ``--no-hints`` 用于禁用有关错误处理的提示并禁用捕获输出。
|
||||
|
||||
.. _cmake: https://cmake.org
|
||||
.. _ninja: https://ninja-build.org
|
||||
.. _esptool.py: https://github.com/espressif/esptool/#readme
|
||||
.. _CCache: https://ccache.dev/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user