diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 70d6ccb93f..39fc173e58 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -3,7 +3,7 @@ :link_to_translation:`en:[English]` -本文档主要介绍 ESP-IDF 构建系统的实现原理以及 ``组件`` 等相关概念。如需您想了解如何组织和构建新的 ESP-IDF 项目或组件,请阅读本文档。 +本文档主要介绍 ESP-IDF 构建系统的实现原理以及 ``组件`` 等相关概念。如需了解如何组织和构建新的 ESP-IDF 项目或组件,请阅读本文档。 概述 ==== @@ -47,7 +47,7 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候, idf.py -------- -``idf.py`` 命令行工具提供了一个前端,可以帮助您轻松管理项目的构建过程,它管理了以下工具: +``idf.py`` 命令行工具提供了一个前端,可以帮助你轻松管理项目的构建过程,它管理了以下工具: - CMake_,配置待构建的项目 - Ninja_,用于构建项目 @@ -58,7 +58,7 @@ idf.py 直接使用 CMake -------------- -为了方便,:ref:`idf.py` 已经封装了 CMake_ 命令,但是您愿意,也可以直接调用 CMake。 +为了方便,:ref:`idf.py` 已经封装了 CMake_ 命令,但是你愿意,也可以直接调用 CMake。 .. highlight:: bash @@ -76,14 +76,14 @@ idf.py 若在 CMake 中使用 ``ninja`` 或 ``make``,则多数 ``idf.py`` 子命令也会有其对应的目标,例如在构建目录下运行 ``make menuconfig`` 或 ``ninja menuconfig`` 与运行 ``idf.py menuconfig`` 是相同的。 .. Note:: - 如果您已经熟悉了 CMake_,那么可能会发现 ESP-IDF 的 CMake 构建系统不同寻常,为了减少样板文件,该系统封装了 CMake 的许多功能。请参考 :ref:`write-pure-component` 以编写更多 “CMake 风格”的组件。 + 如果你已经熟悉了 CMake_,那么可能会发现 ESP-IDF 的 CMake 构建系统不同寻常,为了减少样板文件,该系统封装了 CMake 的许多功能。请参考 :ref:`write-pure-component` 以编写更多 “CMake 风格”的组件。 .. _flash-with-ninja-or-make: 使用 Ninja/Make 来烧录 ^^^^^^^^^^^^^^^^^^^^^^ -您可以直接使用 ninja 或 make 运行如下命令来构建项目并烧录:: +可以直接使用 ninja 或 make 运行如下命令来构建项目并烧录:: ninja flash @@ -93,7 +93,7 @@ idf.py 可用的目标还包括:``flash``、``app-flash`` (仅用于 app)、``bootloader-flash`` (仅用于 bootloader)。 -以这种方式烧录时,可以通过设置 ``ESPPORT`` 和 ``ESPBAUD`` 环境变量来指定串口设备和波特率。您可以在操作系统或 IDE 项目中设置该环境变量,或者直接在命令行中进行设置:: +以这种方式烧录时,可以通过设置 ``ESPPORT`` 和 ``ESPBAUD`` 环境变量来指定串口设备和波特率。可以在操作系统或 IDE 项目中设置该环境变量,或者直接在命令行中进行设置:: ESPPORT=/dev/ttyUSB0 ninja flash @@ -108,9 +108,9 @@ idf.py 在 IDE 中使用 CMake ------------------- -您还可以使用集成了 CMake 的 IDE,仅需将项目 ``CMakeLists.txt`` 文件的路径告诉 IDE 即可。集成 CMake 的 IDE 通常会有自己的构建工具(CMake 称之为“生成器”),它是组成 IDE 的一部分,用来构建源文件。 +还可以使用集成了 CMake 的 IDE,仅需将项目 ``CMakeLists.txt`` 文件的路径告诉 IDE 即可。集成 CMake 的 IDE 通常会有自己的构建工具(CMake 称之为“生成器”),它是组成 IDE 的一部分,用来构建源文件。 -向 IDE 中添加除 ``build`` 目标以外的自定义目标(如添加 “Flash” 目标到 IDE)时,建议调用 ``idf.py`` 命令来执行这些“特殊”的操作。 +向 IDE 中添加除 ``build`` 目标以外的自定义目标(如添加 “flash” 目标到 IDE)时,建议调用 ``idf.py`` 命令来执行这些“特殊”的操作。 有关将 ESP-IDF 同 CMake 集成到 IDE 中的详细信息,请参阅 :ref:`build_system_metadata`。 @@ -121,13 +121,13 @@ idf.py ESP-IDF 适用于 Python 3.7 以上版本。 -``idf.py`` 和其他的 Python 脚本会使用默认的 Python 解释器运行,如 ``python``。您可以通过 ``python3 $IDF_PATH/tools/idf.py ...`` 命令切换到别的 Python 解释器,或者您可以通过设置 shell 别名或其他脚本来简化该命令。 +``idf.py`` 和其他的 Python 脚本会使用默认的 Python 解释器运行,如 ``python``。你可以通过 ``python3 $IDF_PATH/tools/idf.py ...`` 命令切换到别的 Python 解释器,或者通过设置 shell 别名或其他脚本来简化该命令。 如果直接使用 CMake,运行 ``cmake -D PYTHON=python3 ...``,CMake 会使用传入的值覆盖默认的 Python 解释器。 如果使用集成 CMake 的 IDE,可以在 IDE 的图形用户界面中给名为 ``PYTHON`` 的 CMake cache 变量设置新的值来覆盖默认的 Python 解释器。 -如果想在命令行中更优雅地管理 Python 的各个版本,请查看 pyenv_ 或 virtualenv_ 工具,它们会帮助您更改默认的 python 版本。 +如果想在命令行中更优雅地管理 Python 的各个版本,请查看 pyenv_ 或 virtualenv_ 工具,它们会帮助你更改默认的 python 版本。 .. _example-project-structure: @@ -160,9 +160,9 @@ ESP-IDF 适用于 Python 3.7 以上版本。 - "sdkconfig" 项目配置文件,执行 ``idf.py menuconfig`` 时会创建或更新此文件,文件中保存了项目中所有组件(包括 ESP-IDF 本身)的配置信息。 ``sdkconfig`` 文件可能会也可能不会被添加到项目的源码管理系统中。 -- 可选的 "components" 目录中包含了项目的部分自定义组件,并不是每个项目都需要这种自定义组件,但它有助于构建可复用的代码或者导入第三方(不属于 ESP-IDF)的组件。或者,您也可以在顶层 CMakeLists.txt 中设置 ``EXTRA_COMPONENT_DIRS`` 变量以查找其他指定位置处的组件。 +- 可选的 "components" 目录中包含了项目的部分自定义组件,并不是每个项目都需要这种自定义组件,但它有助于构建可复用的代码或者导入第三方(不属于 ESP-IDF)的组件。或者,你也可以在顶层 CMakeLists.txt 中设置 ``EXTRA_COMPONENT_DIRS`` 变量以查找其他指定位置处的组件。 -- "main" 目录是一个特殊的组件,它包含项目本身的源代码。"main" 是默认名称,CMake 变量 ``COMPONENT_DIRS`` 默认包含此组件,但您可以修改此变量。有关详细信息,请参阅 :ref:`重命名 main 组件 `。如果项目中源文件较多,建议将其归于组件中,而不是全部放在 "main" 中。 +- "main" 目录是一个特殊的组件,它包含项目本身的源代码。"main" 是默认名称,CMake 变量 ``COMPONENT_DIRS`` 默认包含此组件,但你可以修改此变量。有关详细信息,请参阅 :ref:`重命名 main 组件 `。如果项目中源文件较多,建议将其归于组件中,而不是全部放在 "main" 中。 - "build" 目录是存放构建输出的地方,如果没有此目录,``idf.py`` 会自动创建。CMake 会配置项目,并在此目录下生成临时的构建文件。随后,在主构建进程的运行期间,该目录还会保存临时目标文件、库文件以及最终输出的二进制文件。此目录通常不会添加到项目的源码管理系统中,也不会随项目源码一同发布。 @@ -204,7 +204,7 @@ ESP-IDF 适用于 Python 3.7 以上版本。 以下这些变量都有默认值,用户可以覆盖这些变量值以自定义构建行为。更多实现细节,请参阅 :idf_file:`/tools/cmake/project.cmake` 文件。 -- ``COMPONENT_DIRS``:组件的搜索目录,默认为 ``IDF_PATH/components``、 ``PROJECT_DIR/components``、和 ``EXTRA_COMPONENT_DIRS``。如果您不想在这些位置搜索组件,请覆盖此变量。 +- ``COMPONENT_DIRS``:组件的搜索目录,默认为 ``IDF_PATH/components``、 ``PROJECT_DIR/components``、和 ``EXTRA_COMPONENT_DIRS``。如果你不想在这些位置搜索组件,请覆盖此变量。 - ``EXTRA_COMPONENT_DIRS``:用于搜索组件的其它可选目录列表。路径可以是相对于项目目录的相对路径,也可以是绝对路径。 @@ -354,6 +354,10 @@ ESP-IDF 在搜索所有待构建的组件时,会按照 ``COMPONENT_DIRS`` 指 如果上游代码在编译的时候发出了警告,那这么做可能会很有效。 +.. note:: + + 如已借助 ``idf_component_register`` 中的 ``SRC_DIRS`` 变量填充源文件,CMake `set_source_files_properties`_ 命令将无法使用,详情请参考 :ref:`cmake-file-globbing`。 + 请注意,上述两条命令只能在组件 CMakeLists 文件的 ``idf_component_register`` 命令之后调用。 .. _component-configuration: @@ -610,7 +614,7 @@ CMake 通常会在链接器命令行上重复两次组件库名称来自动处 .. highlight:: cmake -ESP-IDF 的 CMake 辅助函数 ``idf_component_add_link_dependency`` 可以在组件之间添加仅作用于链接时的依赖关系。绝大多数情况下,我们都建议您使用 ``idf_component_register`` 中的 ``PRIV_REQUIRES`` 功能来构建依赖关系。然而在某些情况下,还是有必要添加另一个组件对当前组件的链接时依赖,即反转 ``PRIV_REQUIRES`` 中的依赖关系(参考示例::doc:`/api-reference/peripherals/spi_flash/spi_flash_override_driver`)。 +ESP-IDF 的 CMake 辅助函数 ``idf_component_add_link_dependency`` 可以在组件之间添加仅作用于链接时的依赖关系。绝大多数情况下,我们都建议你使用 ``idf_component_register`` 中的 ``PRIV_REQUIRES`` 功能来构建依赖关系。然而在某些情况下,还是有必要添加另一个组件对当前组件的链接时依赖,即反转 ``PRIV_REQUIRES`` 中的依赖关系(参考示例::doc:`/api-reference/peripherals/spi_flash/spi_flash_override_driver`)。 要使另一个组件在链接时依赖于这个组件:: @@ -632,7 +636,7 @@ ESP-IDF 的 CMake 辅助函数 ``idf_component_add_link_dependency`` 可以在 project_include.cmake --------------------- -如果组件的某些构建行为需要在组件 CMakeLists 文件之前被执行,您可以在组件目录下创建名为 ``project_include.cmake`` 的文件,``project.cmake`` 在运行过程中会导入此 CMake 文件。 +如果组件的某些构建行为需要在组件 CMakeLists 文件之前被执行,你可以在组件目录下创建名为 ``project_include.cmake`` 的文件,``project.cmake`` 在运行过程中会导入此 CMake 文件。 ``project_include.cmake`` 文件在 ESP-IDF 内部使用,以定义项目范围内的构建功能,比如 ``esptool.py`` 的命令行参数和 ``bootloader`` 这个特殊的应用程序。 @@ -656,13 +660,13 @@ KConfig.projbuild 通过封装对现有函数进行重新定义或扩展 ------------------------------------- -链接器具有封装功能,可以重新定义或扩展现有 ESP-IDF 函数的行为。如需封装函数,您需要在项目的 ``CMakeLists.txt`` 文件中提供以下 CMake 声明: +链接器具有封装功能,可以重新定义或扩展现有 ESP-IDF 函数的行为。如需封装函数,你需要在项目的 ``CMakeLists.txt`` 文件中提供以下 CMake 声明: .. code-block:: cmake target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--wrap=function_to_redefine") -其中,``function_to_redefine`` 为需要被重新定义或扩展的函数名称。启用此选项后,链接器将把二进制库中所有对 ``function_to_redefine`` 函数的调用改为对 ``__wrap_function_to_redefine`` 函数的调用。因此,您必须在应用程序中定义这一符号。 +其中,``function_to_redefine`` 为需要被重新定义或扩展的函数名称。启用此选项后,链接器将把二进制库中所有对 ``function_to_redefine`` 函数的调用改为对 ``__wrap_function_to_redefine`` 函数的调用。因此,你必须在应用程序中定义这一符号。 链接器会提供一个名为 ``__real_function_to_redefine`` 的新符号,指向将被重新定义的函数的原有实现。由此,可以从新的实现中调用该函数,从而对原有实现进行扩展。 @@ -819,9 +823,9 @@ CMake 文件可以使用 ``IDF_TARGET`` 变量来获取当前的硬件目标。 嵌入二进制数据 --------------------- -有时您的组件希望使用一个二进制文件或者文本文件,但是您又不希望将它们重新格式化为 C 源文件。 +有时你的组件希望使用一个二进制文件或者文本文件,但是你又不希望将它们重新格式化为 C 源文件。 -这时,您可以在组件注册中指定 ``EMBED_FILES`` 参数,用空格分隔要嵌入的文件名称:: +这时,你可以在组件注册中指定 ``EMBED_FILES`` 参数,用空格分隔要嵌入的文件名称:: idf_component_register(... EMBED_FILES server_root_cert.der) @@ -833,7 +837,7 @@ CMake 文件可以使用 ``IDF_TARGET`` 变量来获取当前的硬件目标。 .. highlight:: c -文件的内容会被添加到 Flash 的 .rodata 段,用户可以通过符号名来访问,如下所示:: +文件的内容会被添加到 flash 的 .rodata 段,用户可以通过符号名来访问,如下所示:: extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); @@ -909,7 +913,7 @@ ESP-IDF 还支持自动生成链接脚本,它允许组件通过链接片段文 - ``externalproject_add`` 定义了一个外部构建系统。 - 设置 ``SOURCE_DIR``、``CONFIGURE_COMMAND``、``BUILD_COMMAND`` 和 ``INSTALL_COMMAND``。如果外部构建系统没有配置这一步骤,可以将 ``CONFIGURE_COMMAND`` 设置为空字符串。在 ESP-IDF 的构建系统中,一般会将 ``INSTALL_COMMAND`` 变量设置为空。 - - 设置 ``BUILD_IN_SOURCE``,即构建目录与源目录相同。否则,您也可以设置 ``BUILD_DIR`` 变量。 + - 设置 ``BUILD_IN_SOURCE``,即构建目录与源目录相同。否则,你也可以设置 ``BUILD_DIR`` 变量。 - 有关 ``externalproject_add()`` 命令的详细信息,请参阅 ExternalProject_。 - 第二组命令添加了一个目标库,指向外部构建系统生成的库文件。为了添加 include 目录,并告知 CMake 该文件的位置,需要再设置一些属性。 @@ -940,7 +944,7 @@ ExternalProject 的依赖与构建清理 自定义 sdkconfig 的默认值 ========================= -对于示例工程或者其他您不想指定完整 sdkconfig 配置的项目,但是您确实希望覆盖 ESP-IDF 默认值中的某些键值,则可以在项目中创建 ``sdkconfig.defaults`` 文件。重新创建新配置时将会用到此文件,另外在 ``sdkconfig`` 没有设置新配置值时,上述文件也会被用到。 +对于示例工程或者其他你不想指定完整 sdkconfig 配置的项目,但是你确实希望覆盖 ESP-IDF 默认值中的某些键值,则可以在项目中创建 ``sdkconfig.defaults`` 文件。重新创建新配置时将会用到此文件,另外在 ``sdkconfig`` 没有设置新配置值时,上述文件也会被用到。 如若需要覆盖此文件的名称或指定多个文件,请设置 ``SDKCONFIG_DEFAULTS`` 环境变量或在顶层 CMakeLists.txt 文件中设置 ``SDKCONFIG_DEFAULTS``。非绝对路径的文件名将以当前项目的相对路径来解析。 @@ -959,7 +963,7 @@ ExternalProject 的依赖与构建清理 .. _flash_parameters: -Flash 参数 +flash 参数 ========== 有些情况下,我们希望在没有 IDF 时也能烧写目标板,为此,我们希望可以保存已构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以通过编写一段简单的脚本来保存二进制文件和 esptool.py。 @@ -972,7 +976,7 @@ Flash 参数 .. highlight:: bash -您可以参照如下命令将任意烧录参数文件传递给 ``esptool.py``:: +你可以参照如下命令将任意烧录参数文件传递给 ``esptool.py``:: python esptool.py --chip {IDF_TARGET_PATH_NAME} write_flash @build/flash_project_args @@ -1058,7 +1062,7 @@ CMake 在许多开源的 C/C++ 项目中广泛使用,用户可以在自己的 .. highlight:: cmake -还有一种情况是您有一个由其它构建过程生成预建静态库(``.a`` 文件)。 +还有一种情况是你有一个由其它构建过程生成预建静态库(``.a`` 文件)。 ESP-IDF 构建系统为用户提供了一个实用函数 ``add_prebuilt_library``,能够轻松导入并使用预建库:: @@ -1259,7 +1263,7 @@ ESP-IDF 组件命令 ``idf_component_register`` 的参数包括: - SRCS - 组件的源文件,用于为组件创建静态库;如果没有指定,组件将被视为仅配置组件,从而创建接口库。 - - SRC_DIRS、 EXCLUDE_SRCS - 用于通过指定目录来 glob 源文件 (.c、.cpp、.S),而不是通过 SRCS 手动指定源文件。请注意,这受 :ref:`CMake 中通配符的限制`。 在 EXCLUDE_SRCS 中指定的源文件会从被 glob 的文件中移除。 + - SRC_DIRS、 EXCLUDE_SRCS - 用于通过指定目录来 glob 源文件 (.c、.cpp、.S),而不是通过 SRCS 手动指定源文件。请注意,这受 :ref:`CMake 中通配符的限制`。在 EXCLUDE_SRCS 中指定的源文件会从被 glob 的文件中移除。 - INCLUDE_DIRS - 相对于组件目录的路径,该路径将被添加到需要当前组件的所有其他组件的 include 搜索路径中。 - PRIV_INCLUDE_DIRS - 必须是相对于组件目录的目录路径,它仅被添加到这个组件源文件的 include 搜索路径中。 - REQUIRES - 组件的公共组件依赖项。 @@ -1359,7 +1363,7 @@ JSON 配置服务器 ``kconfserver`` 工具可以帮助 IDE 轻松地与配置系统的逻辑进行集成,它运行在后台,通过使用 stdin 和 stdout 读写 JSON 文件的方式与调用进程交互。 -您可以通过 ``idf.py confserver`` 或 ``ninja kconfserver`` 从项目中运行 ``kconfserver``,也可以使用不同的构建生成器来触发类似的目标。 +你可以通过 ``idf.py confserver`` 或 ``ninja kconfserver`` 从项目中运行 ``kconfserver``,也可以使用不同的构建生成器来触发类似的目标。 有关 kconfserver 的更多信息,请参阅 `esp-idf-kconfig 文档 `_。