|
|
@@ -50,83 +50,10 @@ idf.py
|
|
|
``idf.py`` 命令行工具提供了一个前端，可以帮助您轻松管理项目的构建过程，它管理了以下工具：
|
|
|
|
|
|
- CMake_，配置待构建的项目
|
|
|
-- 命令行构建工具（Ninja_ 或 `GNU Make`）
|
|
|
+- Ninja_，用于构建项目
|
|
|
- `esptool.py`_，烧录目标硬件设备
|
|
|
|
|
|
-:ref:`入门指南 <get-started-configure>` 简要介绍了如何设置 ``idf.py`` 用于配置、构建并烧录项目。
|
|
|
-
|
|
|
-``idf.py`` 应运行在 ESP-IDF 的 ``项目`` 目录下，即包含 ``CMakeLists.txt`` 文件的目录。仅包含 Makefile 的老式项目并不支持 ``idf.py``。
|
|
|
-
|
|
|
-运行 ``idf.py --help`` 查看完整的命令列表。下面总结了最常用的命令：
|
|
|
-
|
|
|
-- ``idf.py set-target <target>`` 会设置构建项目的目标（芯片）。请参考 `选择目标芯片`_。
|
|
|
-- ``idf.py menuconfig`` 会运行 ``menuconfig`` 工具来配置项目。
|
|
|
-- ``idf.py build`` 会构建在当前目录下找到的项目，它包括以下步骤：
|
|
|
-
|
|
|
- - 根据需要创建 ``build`` 构建目录，它用于保存构建过程的输出文件，可以使用 ``-B`` 选项修改默认的构建目录。
|
|
|
- - 根据需要运行 CMake_ 来配置项目，为主构建工具生成构建文件。
|
|
|
- - 运行主构建工具（Ninja_ 或 `GNU Make`）。默认情况下，构建工具会被自动检测，可以使用 ``-G`` 选项显式地指定构建工具。
|
|
|
-
|
|
|
- 构建过程是增量式的，如果自上次构建以来源文件或项目配置没有发生改变，则不会执行任何操作。
|
|
|
-
|
|
|
-- ``idf.py clean`` 会把构建输出的文件从构建目录中删除，从而清理整个项目。下次构建时会强制“重新完整构建”这个项目。清理时，不会删除 CMake 配置输出及其他文件。
|
|
|
-- ``idf.py fullclean`` 会将整个 ``build`` 目录下的内容全部删除，包括所有 CMake 的配置输出文件。下次构建项目时，CMake 会从头开始配置项目。请注意，该命令会递归删除构建目录下的 *所有文件*，请谨慎使用。项目配置文件不会被删除。
|
|
|
-- ``idf.py flash`` 会在必要时自动构建项目，并将生成的二进制程序烧录进目标 {IDF_TARGET_NAME} 设备中。``-p`` 和 ``-b`` 选项可分别设置串口的设备名和烧录时的波特率。
|
|
|
-- ``idf.py monitor`` 用于显示目标 {IDF_TARGET_NAME} 设备的串口输出。``-p`` 选项可用于设置主机端串口的设备名，按下 ``Ctrl-]`` 可退出监视器。更多有关监视器的详情，请参阅 :doc:`tools/idf-monitor`。
|
|
|
-
|
|
|
-多个 ``idf.py`` 命令可合并成一个，例如，``idf.py -p COM4 clean flash monitor`` 会依次清理源码树，构建项目，烧录进目标 {IDF_TARGET_NAME} 设备，最后运行串口监视器。
|
|
|
-
|
|
|
-对于 ``idf.py`` 不知道的指令，``idf.py`` 会尝试将其作为构建系统的目标来执行。
|
|
|
-
|
|
|
-``idf.py`` 命令支持 bash、 zsh 以及 fish 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 的自动补全功能。
|
|
|
-
|
|
|
-.. 注解:: 环境变量 ``ESPPORT`` 和 ``ESPBAUD`` 可分别用来设置 ``-p`` 和 ``-b`` 选项的默认值。在命令行中，重新为这两个选项赋值，会覆盖其默认值。
|
|
|
-
|
|
|
-高级命令
|
|
|
-^^^^^^^^
|
|
|
-
|
|
|
-- ``idf.py app``，``idf.py bootloader``，``idf.py partition-table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。
|
|
|
-- ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 {IDF_TARGET_NAME}。
|
|
|
-- ``idf.py -p PORT erase-flash`` 会使用 esptool.py 擦除 {IDF_TARGET_NAME} 的整个 Flash。
|
|
|
-- ``idf.py size`` 会打印应用程序相关的大小信息，``size-components`` 和 ``size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。如果您在运行 CMake（或 ``idf.py``）时定义了变量 ``-DOUTPUT_JSON=1``，那么输出的格式会变成 JSON 而不是可读文本。详情请查看 ``idf.py-size``。
|
|
|
-- ``idf.py reconfigure`` 命令会重新运行 CMake_ （即便无需重新运行）。正常使用时，并不需要运行此命令，但当源码树中添加/删除文件后或更改 CMake cache 变量时，此命令会非常有用，例如，``idf.py -DNAME='VALUE' reconfigure`` 会将 CMake cache 中的变量 ``NAME`` 的值设置为 ``VALUE``。
|
|
|
-- ``idf.py python-clean`` 会从 IDF 目录中删除生成的 Python 字节码，Python 字节码可能会在切换 IDF 和 Python 版本时引发问题，因此建议在切换 Python 后运行该命令。
|
|
|
-- ``idf.py docs`` 将在浏览器中直接打开项目目标芯片和对应版本的文档链接。请使用 ``idf.py docs --help`` 查看所有选项。
|
|
|
-
|
|
|
-同时调用多个 ``idf.py`` 命令时，命令的输入顺序并不重要，它们会按照正确的顺序依次执行，并保证每一条命令都生效（即先构建后烧录，先擦除后烧录等）。
|
|
|
-
|
|
|
-idf.py 选项
|
|
|
-^^^^^^^^^^^^^^
|
|
|
-
|
|
|
-运行 ``idf.py --help`` 命令列出所有根级选项。运行 ``idf.py <command> --help`` 命令列出针对某一子命令的选项，如 ``idf.py monitor --help``。下列是一些常用选项：
|
|
|
-
|
|
|
-- ``-C <dir>`` 可用来从默认的当前工作目录覆盖项目目录。
|
|
|
-- ``-B <dir>`` 可用来从项目目录默认的 ``build`` 子目录覆盖构建目录。
|
|
|
-- ``--ccache`` 可用来在编译源文件时启用 CCache_，安装了 CCache_ 工具后可极大缩短编译时间。
|
|
|
-
|
|
|
-请注意，一些旧版本的 CCache 在某些平台上可能会出现 bug，因此如果文件没有按预期重新构建，请尝试禁用 CCache 后再次构建。通过设置环境变量 ``IDF_CCACHE_ENABLE`` 为非零值，可以默认启用 CCache。
|
|
|
-
|
|
|
-- ``-v`` 可以让 ``idf.py`` 和编译系统产生详细的编译输出，对于调试编译问题会非常有用。
|
|
|
-- ``--cmake-warn-uninitialized``（或 ``-w``）会让 CMake 在项目目录内打印未初始化的变量警告（不包括在项目目录外的目录），这一选项只能控制 CMake 内部的 CMake 变量警告，不包括其它类型的编译警告。可以通过设置环境变量 ``IDF_CMAKE_WARN_UNINITIALIZED`` 为非零值，从而永久设置该选项。
|
|
|
-
|
|
|
-开始新项目
|
|
|
------------------
|
|
|
-
|
|
|
-运行 ``idf.py create-project`` 命令可以开始创建您的新项目，运行 ``idf.py create-project --help`` 命令获取更多相关信息。
|
|
|
-
|
|
|
-例如：
|
|
|
-
|
|
|
-.. code-block:: bash
|
|
|
-
|
|
|
- idf.py create-project --path my_projects my_new_project
|
|
|
-
|
|
|
-以上命令会直接在 my_projects 目录下创建一个名为 my_new_project 的新项目。
|
|
|
+可通过 ``idf.py`` 配置构建系统，具体可参考 :doc:`相关文档 <tools/idf-py>`。
|
|
|
|
|
|
直接使用 CMake
|
|
|
--------------
|
|
|
@@ -386,19 +313,6 @@ ESP-IDF 在搜索所有待构建的组件时，会按照 ``COMPONENT_DIRS`` 指
|
|
|
|
|
|
有关更完整的 ``CMakeLists.txt`` 示例，请参阅 `组件依赖示例`_ 和 `组件 CMakeLists 示例`_。
|
|
|
|
|
|
-创建新组件
|
|
|
--------------
|
|
|
-
|
|
|
-使用 ``idf.py create-component`` 命令创建新组件。 新组件将包含构建组件所需的一组文件。您可以将组件的头文件纳入到您的项目中，并使用其功能。请运行 ``idf.py create-component --help`` 命令获取更多信息。
|
|
|
-
|
|
|
-示例:
|
|
|
-
|
|
|
-.. code-block:: bash
|
|
|
-
|
|
|
- idf.py -C components create-component my_component
|
|
|
-
|
|
|
-该示例将在当前工作目录下的子目录 components 中创建一个新的组件。更多关于组件的信息，请参考 :ref:`上文<component-directories>`。
|
|
|
-
|
|
|
.. _preset_component_variables:
|
|
|
|
|
|
预设的组件变量
|
|
|
@@ -527,8 +441,8 @@ ESP-IDF 构建系统会在命令行中添加以下 C 预处理器定义：
|
|
|
- engine.c
|
|
|
- include/ - engine.h
|
|
|
- spark_plug/ - CMakeLists.txt
|
|
|
- - plug.c
|
|
|
- - plug.h
|
|
|
+ - spark_plug.c
|
|
|
+ - spark_plug.h
|
|
|
|
|
|
Car 组件
|
|
|
^^^^^^^^^
|
|
|
@@ -1051,43 +965,10 @@ Flash 参数
|
|
|
构建 Bootloader
|
|
|
===============
|
|
|
|
|
|
-引导程序默认作为 ``idf.py build`` 的一部分被构建，也可以通过 ``idf.py bootloader`` 来单独构建。
|
|
|
-
|
|
|
引导程序是 :idf:`/components/bootloader/subproject` 内部独特的“子项目”，它有自己的项目 CMakeLists.txt 文件，能够构建独立于主项目的 ``.ELF`` 和 ``.BIN`` 文件，同时它又与主项目共享配置和构建目录。
|
|
|
|
|
|
子项目通过 :idf_file:`/components/bootloader/project_include.cmake` 文件作为外部项目插入到项目的顶层，主构建进程会运行子项目的 CMake，包括查找组件（主项目使用的组件的子集），生成引导程序专用的配置文件（从主 ``sdkconfig`` 文件中派生）。
|
|
|
|
|
|
-..
|
|
|
- Label removed here because of the conflict with the english docs restructuring.
|
|
|
- When translating please follow the structure in the english docs.
|
|
|
-
|
|
|
-选择目标芯片
|
|
|
-====================
|
|
|
-
|
|
|
-ESP-IDF 支持多款芯片，运行 `idf.py --list-targets` 可以查看当前 ESP-IDF 版本中支持目标的完整列表。
|
|
|
-
|
|
|
-在构建项目前，请首先根据您的芯片选择正确的软件目标，具体命令为 ``idf.py set-target <target>``。举例 ::
|
|
|
-
|
|
|
- idf.py set-target esp32s2
|
|
|
-
|
|
|
-.. important::
|
|
|
-
|
|
|
- 运行 ``idf.py set-target`` 命令将清除 ``build`` 文件夹的内容，并重新生成一个 ``sdkconfig`` 文件。之前的 ``sdkconfig`` 将另存为 ``sdkconfig.old``。
|
|
|
-
|
|
|
-.. note::
|
|
|
-
|
|
|
- 运行 ``idf.py set-target`` 命令相当于分别运行以下几个命令：
|
|
|
-
|
|
|
- 1. 清除 ``build`` 文件夹 (``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`` 配置为环境变量比较方便。
|
|
|
-
|
|
|
-对于特定项目，您可以使用以下方式为 ``IDF_TARGET`` 配置 _default_ 值：把 ``CONFIG_IDF_TARGET`` 的值加入 ``sdkconfig.defaults``。举例而言，配置 ``CONFIG_IDF_TARGET="esp32s2"``。这样一来，除非特别设置（比如使用环境变量、CMake 变量或 ``idf.py set-target`` 命令），否则 ``IDF_TARGET`` 将默认采用 ``CONFIG_IDF_TARGET``。
|
|
|
-
|
|
|
-如果您从未通过以上述任何方式配置过“目标”芯片，则构建系统会默认将 ``esp32`` 设定为“目标”芯片。
|
|
|
-
|
|
|
.. _write-pure-component:
|
|
|
|
|
|
编写纯 CMake 组件
|
|
|
@@ -1344,7 +1225,8 @@ idf 组件命令
|
|
|
[EMBED_FILES file1 file2 ...]
|
|
|
[EMBED_TXTFILES file1 file2 ...]
|
|
|
[KCONFIG kconfig]
|
|
|
- [KCONFIG_PROJBUILD kconfig_projbuild])
|
|
|
+ [KCONFIG_PROJBUILD kconfig_projbuild]
|
|
|
+ [WHOLE_ARCHIVE])
|
|
|
|
|
|
将一个组件注册到构建系统中。就像 ``project()`` CMake 命令一样，该命令应该直接从组件的 CMakeLists.txt 中调用（而不是通过函数或宏），且建议在其他命令之前调用该命令。下面是一些关于在 ``idf_component_register`` 之前 *不能* 调用哪些命令的指南：
|
|
|
|
|
|
@@ -1366,6 +1248,7 @@ idf 组件命令
|
|
|
- REQUIRED_IDF_TARGETS - 指定该组件唯一支持的目标。
|
|
|
- KCONFIG - 覆盖默认的 Kconfig 文件。
|
|
|
- KCONFIG_PROJBUILD - 覆盖默认的 Kconfig.projbuild 文件。
|
|
|
+ - WHOLE_ARCHIVE - 如果指定了此参数，链接时会在组件库的前后分别添加 ``-Wl,--whole-archive`` 和 ``-Wl,--no-whole-archive``。这与设置 ``WHOLE_ARCHIVE`` 组件属性的效果一致。
|
|
|
|
|
|
以下内容用于 :ref:`将数据嵌入到组件中<cmake_embed_data>`，并在确定组件是否仅用于配置时被视为源文件。这意味着，即使组件没有指定源文件，如果组件指定了以下其中之一，仍然会在内部为组件创建一个静态库。
|
|
|
|
|
|
@@ -1401,6 +1284,7 @@ idf 组件属性
|
|
|
- REQUIRED_IDF_TARGETS - 组件支持的目标列表；由 ``idf_component_register`` EMBED_TXTFILES 参数设置。
|
|
|
- REQUIRES - 公共组件依赖关系列表；由 ``idf_component_register`` REQUIRES 参数设置。
|
|
|
- SRCS - 组件源文件列表；由 ``idf_component_register`` 的 SRCS 或 SRC_DIRS/EXCLUDE_SRCS 参数设置。
|
|
|
+- WHOLE_ARCHIVE - 如果该属性被设置为 ``TRUE`` （或是其他 CMake 布尔“真”值：1、``ON``、``YES``、``Y`` 等），链接时会在组件库的前后分别添加 ``-Wl,--whole-archive`` 和 ``-Wl,--no-whole-archive`` 选项。这可以强制链接器将每个目标文件包含到可执行文件中，即使该目标文件没有解析来自应用程序其余部分的任何引用。当组件中包含依赖链接时注册的插件或模块时，通常会使用该方法。默认情况下，此属性为 ``FALSE``。可以从组件的 CMakeLists.txt 文件中将其设置为 ``TRUE``。
|
|
|
|
|
|
.. _cmake-file-globbing:
|
|
|
|
|
|
@@ -1616,4 +1500,3 @@ CMake 中不可用的功能
|
|
|
.. _quirc: https://github.com/dlbeer/quirc
|
|
|
.. _pyenv: https://github.com/pyenv/pyenv#readme
|
|
|
.. _virtualenv: https://virtualenv.pypa.io/en/stable/
|
|
|
-.. _CCache: https://ccache.dev/
|
daiziyan