概述
使用ESP-IDF开发时,项目特指一个目录,其中包含了构建可执行应用程序所需的全部文件和配置,以及其他支持型文件,例如分区表、数据/文件系统分区和引导程序。
ESP-IDF 并不是项目的一部分,它独立于项目,通过 IDF_PATH 环境变量(保存 esp-idf 目录的路径)链接到项目,从而将 IDF 框架与项目分离。
项目结构
- myProject/
- CMakeLists.txt
- sdkconfig
- components/
- component1/
- CMakeLists.txt
- Kconfig
- src1.c
- component2/
- CMakeLists.txt
- Kconfig
- src1.c
- include/
- component2.h
- main/
- src1.c
- src2.c
- build/
- 顶层项目 CMakeLists.txt 文件,这是 CMake 用于学习如何构建项目的主要文件,可以在这个文件中设置项目全局的 CMake 变量。顶层项目 CMakeLists.txt 文件会导入 esp-idf/tools/cmake/project.cmake 文件,由它负责实现构建系统的其余部分。该文件最后会设置项目的名称,并定义该项目
- sdkconfig 项目配置文件,执行 idf.py menuconfig 时会创建或更新此文件,文件中保存了项目中所有组件(包括 ESP-IDF 本身)的配置信息。 sdkconfig 文件可能会也可能不会被添加到项目的源码管理系统中。
- 可选的 component 目录中包含了项目的部分自定义组件,并不是每个项目都需要这种自定义组件,但它组件有助于构建可复用的代码或者导入第三方(不属于 ESP-IDF)的组件。
- main 目录是一个特殊的 伪组件,包含项目本身的源代码。main 是默认名称,CMake 变量 COMPONENT_DIRS 默认包含此组件,但您可以修改此变量。或者,您也可以在顶层 CMakeLists.txt 中设置 EXTRA_COMPONENT_DIRS 变量以查找其他指定位置处的组件。
- build 目录是存放构建输出的地方,如果没有此目录,idf.py 会自动创建。CMake 会配置项目,并在此目录下生成临时的构建文件。随后,在主构建进程的运行期间,该目录还会保存临时目标文件、库文件以及最终输出的二进制文件。此目录通常不会添加到项目的源码管理系统中,也不会随项目源码一同发布。
hello-world的项目结构分析
- hello_world/
- main/
- CMakeLists.txt
- component.mk
- hello_world_main.c
- .gdbinit.ci
- CMakeLists.txt
- loadable_elf_example_test.py
- Makefile
- README.md
- sdkconfig
- sdkconfig.ci
main 目录
CMakeLists.txt 文件
CMakeLists.txt内容
idf_component_register(SRCS "hello_world_main.c"
INCLUDE_DIRS "")
idf_component_register函数中SRC中包含所有的源文件,INCLUDE_DIRS中包含所有的头文件目录
如果main中的文件结构这样
- main/
- include/
- hello_world.h
- light_control.h
- CMakeLists.txt
- component.mk
- hello_world_main.c
- light_control.c
CMakeLists.txt中的内容应该修改成
idf_component_register(SRCS "hello_world_main.c"
"light_control.c"
INCLUDE_DIRS "include")
component.mk 文件
GUN Make中使用的文件,通过CMake构建时可以在CMakeLists.txt设置 COMPONENT_ADD_INCLUDEDIRS 和 COMPONENT_SRCDIRS 等变量将组件添加到编译过程中。
hello_world_main.c 文件
开发的源文件
.gdbinit.ci 文件
gdb初始化配置文件
CMakeLists.txt
CMakeLists.txt 内容
# The following lines of boilerplate have to be in your project's
# CMakeLists in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(hello-world)
- cmake_minimum_required(VERSION 3.5) 必须放在 CMakeLists.txt 文件的第一行,它会告诉 CMake 构建该项目所需要的最小版本号。ESP-IDF 支持 CMake 3.5 或更高的版本。
- include($ENV{IDF_PATH}/tools/cmake/project.cmake) 会导入 CMake 的其余功能来完成配置项目、检索组件等任务。
- project(hello-world) 会创建项目本身,并指定项目名称。该名称会作为最终输出的二进制文件的名字,即 hello-world.elf 和 hello-world.bin。每个 CMakeLists 文件只能定义一个项目。
Makefile
项目顶层 Makefile,该 Makefile 设置了 PROJECT_NAME 变量,还可以定义作用于整个项目的其它 make 变量(可选)。顶层 Makefile 会导入核心 Makefile 文件 $(IDF_PATH)/make/project.mk ,由它负责实现 ESP-IDF 构建系统的剩余部分。在CMake编译过中是不需要的。
README.md 文件
项目说明文件,markdown文本。
sdkconfig
它的功能和使用Make的KConfig文件类似,使用CMake编译时,从 sdkconfig 文件中加载项目配置信息,生成 sdkconfig.cmake 和 sdkconfig.h 文件,分别用在 CMake 和 C/C++ 中定义配置项。如果项目配置发生了更改,CMake 会自动重新运行,重新生成上述两个文件,接着重新配置项目。通过idf.py menuconfig可以修改配置项。
idf_component_register函数
idf_component_register函数在/tools/cmake/component.cmake中被定义。
# idf_component_register
#
# @brief Register a component to the build, creating component library targets etc.
#
# @param[in, optional] SRCS (multivalue) list of source files for the component
# @param[in, optional] SRC_DIRS (multivalue) list of source directories to look for source files
# in (.c, .cpp. .S); ignored when SRCS is specified.
# @param[in, optional] EXCLUDE_SRCS (multivalue) used to exclude source files for the specified
# SRC_DIRS
# @param[in, optional] INCLUDE_DIRS (multivalue) public include directories for the created component library
# @param[in, optional] PRIV_INCLUDE_DIRS (multivalue) private include directories for the created component library
# @param[in, optional] LDFRAGMENTS (multivalue) linker script fragments for the component
# @param[in, optional] REQUIRES (multivalue) publicly required components in terms of usage requirements
# @param[in, optional] PRIV_REQUIRES (multivalue) privately required components in terms of usage requirements
# or components only needed for functions/values defined in its project_include.cmake
# @param[in, optional] REQUIRED_IDF_TARGETS (multivalue) the list of IDF build targets that the component only supports
# @param[in, optional] EMBED_FILES (multivalue) list of binary files to embed with the component
# @param[in, optional] EMBED_TXTFILES (multivalue) list of text files to embed with the component
function(idf_component_register)
set(options)
set(single_value)
set(multi_value SRCS SRC_DIRS EXCLUDE_SRCS
INCLUDE_DIRS PRIV_INCLUDE_DIRS LDFRAGMENTS REQUIRES
PRIV_REQUIRES REQUIRED_IDF_TARGETS EMBED_FILES EMBED_TXTFILES)
cmake_parse_arguments(_ "${options}" "${single_value}" "${multi_value}" ${ARGN})
...
...
...
endfunction()