ESP IDF使用官方规范操作创建工程和组件

本文档将介绍基于 CMake 的构建系统，它是 ESP-IDF V4.0 及以上版本的默认系统。此外 ESP-IDF 还支持 基于 GNU Make 的构建系统，基于 GNU Make 的构建系统是 ESP-IDF V4.0 以下版本的默认系统。

先来看看IDF工具包，这是提供的参数和工具列表。

PS E:\idf.py
Usage: idf.py [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

  ESP-IDF CLI build management tool. For commands that are not known to idf.py an
  attempt to execute it as a build system target will be made.

Options:
  --version                       Show IDF version and exit.
  --list-targets                  Print list of supported targets and exit.
  -C, --project-dir PATH          Project directory.
  -B, --build-dir PATH            Build directory.
  -w, --cmake-warn-uninitialized / -n, --no-warnings
                                  Enable CMake uninitialized variable warnings for
                                  CMake files inside the project directory. (--no-
                                  warnings is now the default, and doesn\'t need to be
                                  specified.) The default value can be set with the
                                  IDF_CMAKE_WARN_UNINITIALIZED environment variable.
  -v, --verbose                   Verbose build output.
  --preview                       Enable IDF features that are still in preview.
  --ccache / --no-ccache          Use ccache in build. Disabled by default. The
                                  default value can be set with the IDF_CCACHE_ENABLE
                                  environment variable.
  -G, --generator [Ninja|MinGW Makefiles]
                                  CMake generator.
  -D, --define-cache-entry TEXT   Create a cmake cache entry. This option can be used
                                  at most once either globally, or for one
                                  subcommand.
  -b, --baud INTEGER              Baud rate for flashing. The default value can be
                                  set with the ESPBAUD environment variable. This
                                  option can be used at most once either globally, or
                                  for one subcommand.
  -p, --port TEXT                 Serial port. The default value can be set with the
                                  ESPPORT environment variable. This option can be
                                  used at most once either globally, or for one
                                  subcommand.
  --help                          Show this message and exit.

Commands:
  add-dependency           Add dependency to the manifest file. For now we only
                           support adding dependencies on the default service.
  all                      Aliases: build. Build the project.
  app                      Build only the app.
  app-flash                Flash the app only.
  bootloader               Build only bootloader.
  bootloader-flash         Flash bootloader only.
  build-system-targets     Print list of build system targets.
  clean                    Delete build output files from the build directory.
  confserver               Run JSON configuration server.
  create-component         Create a new component.
  create-manifest          Create manifest for specified component.
  create-project           Create a new project.
  create-remote-component  Register a new component on the component service.
  delete-version           Delete version in dist directory from the component
                           service.
  efuse_common_table       Generate C-source for IDF's eFuse fields.
  efuse_custom_table       Generate C-source for user's eFuse fields.
  encrypted-app-flash      Flash the encrypted app only.
  encrypted-flash          Flash the encrypted project.
  erase_flash              Erase entire flash chip.
  erase_otadata            Erase otadata partition.
  flash                    Flash the project.
  fullclean                Delete the entire build directory contents.
  gdb                      Run the GDB.
  gdbgui                   GDB UI in default browser.
  gdbtui                   GDB TUI mode.
  menuconfig               Run "menuconfig" project configuration tool.
  monitor                  Display serial output.
  openocd                  Run openocd from current path
  pack-component           Create component archive.
  partition_table          Build only partition table.
  partition_table-flash    Flash partition table only.
  post_debug               Utility target to read the output of async debug action
                           and stop them.
  python-clean             Delete generated Python byte code from the IDF directory
  read_otadata             Read otadata partition.
  reconfigure              Re-run CMake.
  set-target               Set the chip target to build.
  show_efuse_table         Print eFuse table.
  size                     Print basic size information about the app.
  size-components          Print per-component size information.
  size-files               Print per-source-file size information.
  uf2                      Generate the UF2 binary with all the binaries included
  uf2-app                  Generate an UF2 binary for the application only
  upload-component         Upload component in dist directory to the component
                           service.
  upload-component-status  Check status of component upload

命令的使用方法自己查阅百度吧。

• idf.py set-target 会设置构建项目的目标（芯片）
  idf.py set-target esp32
• idf.py menuconfig 会运行 menuconfig 工具来配置项目。
• idf.py build 会构建在当前目录下找到的项目
• idf.py clean 会把构建输出的文件从构建目录中删除，从而清理整个项目。下次构建时会强制“重新完整构建”这个项目。清理时，不会删除 CMake 配置输出及其他文件。
• idf.py fullclean 会将整个 build 目录下的内容全部删除，包括所有 CMake 的配置输出文件。下次构建项目时，CMake 会从头开始配置项目。请注意，该命令会递归删除构建目录下的 所有文件，请谨慎使用。项目配置文件不会被删除。
• idf.py flash 会在必要时自动构建项目，并将生成的二进制程序烧录进目标 ESP32 设备中。-p 和 -b 选项可分别设置串口的设备名和烧录时的波特率。

idf.py 选项

运行 idf.py --help 命令列出所有根级选项。运行 idf.py <command> --help命令列出针对某一子命令的选项，如 idf.py monitor --help。下列是一些常用选项：

• -C <dir> 可用来从默认的当前工作目录覆盖项目目录。
• -B <dir>可用来从项目目录默认的 build 子目录覆盖构建目录。
• --ccache 可用来在编译源文件时启用 CCache，安装了 CCache 工具后可极大缩短编译时间。

开始新项目

运行 idf.py create-project 命令可以开始创建您的新项目.(如果省略路径参数，则创建在当前目录下)
idf.py create-project --path my_projects my_new_project
运行idf.py create-component命令可以开始创建组件
idf.py create-component --C components create-component

最小 CMakeLists 文件示例

cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(myProject)

必要部分

每个项目都要按照上面显示的顺序添加上述三行代码：

• cmake_minimum_required(VERSION 3.5) 必须放在 CMakeLists.txt 文件的第一行，它会告诉CMake 构建该项目所需要的最小版本号。ESP-IDF 支持 CMake 3.5 或更高的版本。
• include($ENV{IDF_PATH}/tools/cmake/project.cmake) 会导入 CMake 的其余功能来完成配置项目、检索组件等任务。
• project(myProject) 会创建项目本身，并指定项目名称。该名称会作为最终输出的二进制文件的名字，即 myProject.elf 和 myProject.bin。每个 CMakeLists 文件只能定义一个项目。

可选的项目变量

• COMPONENT_DIRS：组件的搜索目录，默认为 IDF_PATH/components、 PROJECT_DIR/components、和 EXTRA_COMPONENT_DIRS如果您不想在这些位置搜索组件，请覆盖此变量。
• EXTRA_COMPONENT_DIRS：用于搜索组件的其它可选目录列表。路径可以是相对于项目目录的相对路径，也可以是绝对路径。
• COMPONENTS：要构建进项目中的组件名称列表，默认为 COMPONENT_DIRS 目录下检索到的所有组件。使用此变量可以“精简”项目以缩短构建时间。请注意，如果一个组件通过COMPONENT_REQUIRES 指定了它依赖的另一个组件，则会自动将其添加到 COMPONENTS中，所以 COMPONENTS 列表可能会非常短。
• 请使用 cmake 中的 set 命令 来设置这些变量，如 set(VARIABLE "VALUE")。请注意，set() 命令需放在 include(...) 之前，cmake_minimum(...) 之后。

组件依赖

编译各个组件时，ESP-IDF 系统会递归评估其依赖项。这意味着每个组件都需要声明它所依赖的组件，即 “requires”。

编写组件

idf_component_register(...
                       REQUIRES mbedtls
                       PRIV_REQUIRES console spiffs)

• REQUIRES 需要包含所有在当前组件的 公共 头文件里 #include 的头文件所在的组件。
• PRIV_REQUIRES 需要包含被当前组件的源文件 #include 的头文件所在的组件（除非已经被设置在了 REQUIRES 中）。以及是当前组件正常工作必须要链接的组件。
• REQUIRES 和 PRIV_REQUIRES 的值不能依赖于任何配置选项 (CONFIG_xxx 宏)。这是因为在配置加载之前，依赖关系就已经被展开。其它组件变量（比如包含路径或源文件）可以依赖配置选择。
• 如果当前组件除了 通用组件依赖项 中设置的通用组件（比如 RTOS、libc 等）外，并不依赖其它组件，那么对于上述两个 REQUIRES 变量，可以选择其中一个或是两个都不设置。
  如果组件仅支持某些硬件目标（IDF_TARGET 的值），则可以在 idf_component_register 中指定 REQUIRED_IDF_TARGETS 来声明这个需求。在这种情况下，如果构建系统导入了不支持当前硬件目标的组件时就会报错。