Introduction to the Compilation Script

When developing a project using ESP-IDF, developers not only need to write source code but also need to write CMakeLists.txt for the project and components. CMakeLists.txt is a text file, also known as a compilation script, which defines a series of compilation objects, compilation configuration items, and commands to guide the compilation process of the source code. The compilation system of ESP-IDF v4.3.2 is based on CMake. In addition to supporting native CMake functions and commands, it also defines a series of custom functions, making it much easier to write compilation scripts.

The compilation scripts in ESP-IDF mainly include the project compilation script and the component compilation scripts. The CMakeLists.txt in the root directory of the project is called the project compilation script, which guides the compilation process of the entire project. A basic project compilation script typically includes the following three lines:

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

Among them, the cmake_minimum_required (VERSION 3.5) must be placed on the first line, which is used to indicate the minimum CMake version number required by the project. Newer versions of CMake are generally backward compatible with older versions, so adjust the version number accordingly when using newer CMake commands to ensure compatibility.

include($ENV {IDF_PATH}/tools/cmake/project.cmake) imports pre-defined configuration items and commands of ESP-IDF compilation system, including the default build rules of the compilation system described in Section 4.3.3. project(myProject) creates the project itself and specifies its name. This name will be used as the final output binary file name, i.e., myProject.elf and myProject.bin.

A project can have multiple components, including the main component. The top-level directory of each component contains a CMakeLists.txt file, which is called the component compilation script. Component compilation scripts are mainly used to specify component dependencies, configuration parameters, source code files, and included header files for compilation. With ESP-IDF's custom function idf_component_register, the minimum required code for a component compilation script is as follows:

idf_component_register(SRCS "src1.c"
                        INCLUDE_DIRS "include"
                        REQUIRES component1)

The SRCS parameter provides a list of source files in the component, separated by spaces if there are multiple files. The INCLUDE_DIRS parameter provides a list of public header file directories for the component, which will be added to the include search path for other components that depend on the current component. The REQUIRES parameter identifies the public component dependencies for the current component. It is necessary for components to explicitly state which components they depend on, such as component2 depending on component1. However, for the main component, which depends on all components by default, the REQUIRES parameter can be omitted.

In addition, native CMake commands can also be used in the compilation script. For example, use the command set to set variables, such as set(VARIABLE "VALUE").