ESP32 官方文档（二）构建系统

构建系统

本文档解释了 Espressif 物联网开发框架构建系统和“组件”的概念.

如果您想知道如何组织新的 ESP-IDF 项目,请阅读本文档.

我们建议使用 esp-idf-template 项目作为项目的起点.

使用构建系统

esp-idf 中的 README 文件有如何使用构建系统构建项目的说明.

概要

一个 ESP-IDF 项目可以看作是多个组件的组合.例如,对于显示当前湿度的网络服务器,可能有:

• ESP32 基础库( libc,rom bindings 等)
• WiFi 驱动
• TCP / IP 协议堆栈
• FreeRTOS 操作系统
• Web 服务器
• 湿度传感器驱动
• 主程序

ESP-IDF 使这些组件结构更清晰并具有可配置性.为此,在编译项目时,构建环境将查找 ESP-IDF 目录、项目目录和(可选)其他自定义组件目录中的所有组件.之后,它允许用户使用基于文本的菜单系统去自定义每个组件来配置 ESP-IDF 项目.在配置完项目中的组件之后,构建程序将编译项目.

概念

• “项目”是一个目录,其中包含构建单个 “app” (可执行文件)所需的文件和配置,以及其他附加文件,如:分区表,数据/文件系统分区和引导程序.
• “项目配置”保存在项目根目录中的 sdkconfig 文件中.通过 make menuconfig 修改此文件以自定义项目配置.单个项目只包含一个项目配置.
• “app” 是由 esp-idf 构建的可执行文件.单个项目通常会构建两个应用程序 - 一个“项目应用程序”(主要可执行文件,即您的自定义固件)和一个“引导程序”(启动项目应用程序的初始引导程序).
• “组件”是独立代码的模块化部分,它们被编译成静态库(.a文件)并链接到应用程序.有些是由 esp-idf 本身提供的,有些则可能来自其他地方.

有些东西不是项目的一部分:

• “ESP-IDF” 不是该项目的一部分.相反,它是独立的,并通过 IDF_PATH 环境变量链接到项目,该变量保存 esp-idf 目录的路径.这允许 IDF 框架与您的项目分离.
• 用于编译的工具链不是项目的一部分.工具链应安装在系统命令行 PATH 中,或者工具链的路径设置为项目配置中编译器前缀的一部分.

示例项目

一个示例项目目录结构可能如下所示:

 - myProject/
             - Makefile
             - sdkconfig
             - components/ - component1/ - component.mk
                                         - Kconfig
                                         - src1.c
                           - component2/ - component.mk
                                         - Kconfig
                                         - src1.c
                                         - include/ - component2.h
             - main/       - src1.c
                           - src2.c
                           - component.mk

             - build/

“myProject” 示例包含以下元素:

• 顶层项目 Makefile .此 Makefile 设置 PROJECT_NAME 变量,并(可选)定义项目范围的 make 变量.它包括核心的 $(IDF_PATH)/make/project.mk Makefile 文件,它实现了 ESP-IDF 构建系统的其余部分.
• “sdkconfig” 项目配置文件.当 “make menuconfig” 运行时,将创建/更新此文件,并保存项目中所有组件的配置(包括 esp-idf 本身).“sdkconfig” 文件可能会也可能不会添加到项目的源代码管理系统中.
• 可选的 “components” 目录包含属于项目一部分的组件.项目不必包含此类自定义组件,但它可用于构造可重用代码或包括不属于 ESP-IDF 的第三方组件.
• “main” 目录是一个特殊的“伪组件(pseudo-component)”,它包含项目本身的源代码.“main” 是默认名称,Makefile 变量COMPONENT_DIRS包含此组件,但您可以修改此变量(或设置 EXTRA_COMPONENT_DIRS)以查找其他位置的组件.
• “build” 目录是项目编译时创建的,包含项目编译时产生的文件.运行 make 后,该目录被创建,并包含临时目标文件和库以及最终的二进制输出文件 bin.此目录通常不会添加到源代码管理中,也不会随项目源代码一起发布.

组件目录包含一个组件 makefile 文件 - component.mk.这可能包含变量定义,以控制组件的构建过程,以及它与整个项目的集成.有关更多详细信息,请参阅[组件Makefile](#组件 Makefile).

每个组件还可以包括一个 Kconfig 文件,用于定义通过项目配置设置的组件配置选项.某些组件还可能包含 Kconfig.projbuild 和 Makefile.projbuild 文件,这些文件是用于覆盖项目部分的特殊文件.

项目 Makefile

每个项目都有一个 Makefile,其中包含整个项目的构建配置.默认情况下,项目 Makefile 可以非常小.

最小示例 Makefile

PROJECT_NAME := myProject

include $(IDF_PATH)/make/project.mk

强制项目变量

• PROJECT_NAME:项目名称.二进制输出文件将使用此名称 - 即 myProject.bin, myProject.elf.

可选项目变量

这些变量都有默认值,并可以被自定义操作覆盖.查看 make/project.mk 以获取所有实现细节.

• PROJECT_PATH:顶级项目目录.默认为包含 Makefile 的目录.许多其他项目变量都基于此变量.项目路径不能包含空格.
• BUILD_DIR_BASE:所有 objects/libraries/binaries 文件的构建输出目录.默认为$(PROJECT_PATH)/build.
• COMPONENT_DIRS:搜索组件的目录.默认为$(IDF_PATH)/components( idf 组件),$(PROJECT_PATH)/components(项目组件),$(PROJECT_PATH)/main 和 EXTRA_COMPONENT_DIRS (其他组件).如果您不想在这些位置搜索组件,请覆盖此变量.
• EXTRA_COMPONENT_DIRS:用于搜索组件的其他目录的可选列表.
• COMPONENTS:要构建到项目中的组件名称列表.默认为COMPONENT_DIRS目录中的所有组件.
• EXCLUDE_COMPONENTS:在构建过程中要排除的组件名称的可选列表.请注意,这会减少构建时间,但不会减少二进制大小.
• TEST_EXCLUDE_COMPONENTS:在单元测试的构建过程中要排除的可选组件名称列表.

这些 Makefile 变量中的任何路径都应该是绝对路径.您可以使用$(PROJECT_PATH)/ xxx,$(IDF_PATH)/ xxx转换相对路径,或使用 Make 函数$(abspath xxx).

这些都变量应该在 Makefile 中的 include $(IDF_PATH)/make/project.mk 行之前设置.

组件 Makefile

每个项目都包含一个或多个组件,这些组件可以是 esp-idf 的一部分,也可以从其他组件目录添加.

组件是包含 component.mk 文件的任何目录.

搜索组件

在COMPONENT_DIRS中的目录列表中搜索项目的组件.此列表中的目录可以是组件本身(即它们包含 component.mk 文件),也可以是子目录为组件的顶级目录(包含组件的目录).

运行 make list-components 后,会输出这些变量,这可以帮助调试组件目录是否被找到.

具有相同名称的多个组件

当 esp-idf 找到所有要编译的组件时,它将按照 COMPONENT_DIRS 指定的顺序执行此操作; 默认情况下,首先是 idf 组件,第二个是项目组件,最后是 EXTRA_COMPONENT_DIRS 中的组件.如果这些目录中的两个或多个包含具有相同名称的组件子目录,则使用搜索的最后一个位置中的组件.例如,这允许通过简单地将组件从 esp-idf 组件目录复制到项目组件树然后在那里修改它来覆盖具有修改版本的 esp-idf 组件.如果以这种方式使用,esp-idf 目录本身可以保持不变.

最小组件 Makefile

最小的 component.mk 文件是一个空文件.如果文件为空,则设置默认组件行为:

• 与 makefile 在相同的目录中的所有源文件(*.c,*.cpp,*.cc,*.S)将被编译到组件库中
• 子目录 “include” 将被添加到所有其他