ESP IDF

• An app is called a ESP-IDF Project and a external library is called a ESP-IDF component. So inshort it is nothing but a CMake project.
• An ESP-IDF project can be seen as an amalgamation of a number of components.
• A “project” is a directory that contains all the files and configuration to build a single “app” (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader.
• “Project configuration” is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via idf.py menuconfig to customise the configuration of the project. A single project contains exactly one project configuration.
• An “app” is an executable which is built by ESP-IDF. A single project will usually build two apps - a “project app” (the main executable, ie your custom firmware) and a “bootloader app” (the initial bootloader program which launches the project app).
• “components” are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
• “Target” is the hardware for which an application is built. At the moment, ESP-IDF supports esp32 and esp32s2 targets.

idf.py

The idf.py command line tool provides a front-end for easily managing your project builds. It manages the following tools:

• CMake, which configures the project to be built
• A command line build tool (either Ninja build or GNU Make)
• esptool.py for flashing the target.
• idf.py is a wrapper around CMake for convenience. However, you can also invoke CMake directly if you prefer.

We can build our app without idf.py too, let’s try that.

cd hello_world
mkdir -p build
cd build
#cmake .. -G Ninja   # or 'Unix Makefiles'
#ninja
cmake ..
make -j8

• we can try make flash and it will get flashed, if you might recall, here flash is a task in the Makefile, even build is task in the Makefile generated by CMake
• Each project has a single top-level CMakeLists.txt file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal.

project cmake

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

The inclusion of these three lines, in the order shown above, is necessary for every project:

• cmake_minimum_required(VERSION 3.5) tells CMake the minimum version that is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.

• include($ENV{IDF_PATH}/tools/cmake/project.cmake) pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.

• project(myProject) creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie myProject.elf, myProject.bin. Only one project can be defined per CMakeLists file.

The build system provides special treatment to the main component. It is a component that gets automatically added to the build provided that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, saving the user from hunting down dependencies and providing a build that works right out of the box.

• EXTRA_COMPONENT_DIRS: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute.

Detailed docs about CMakeLists in esp idf

component cmake

• A component is any directory in the COMPONENT_DIRS list which contains a CMakeLists.txt file. COMPONENT_DIRS = /esp/esp-idf/components/
• never change the esp/esp-idf/components, never add any external components to this, these are important components which are necessary for your basic app to run. Inshort, don’t change anything inside esp/esp-idf/
• The list of directories in COMPONENT_DIRS is searched for the project’s components. Directories in this list can either be components themselves (ie they contain a CMakeLists.txt file), or they can be top-level directories whose sub-directories are components.
• The minimal component CMakeLists.txt file simply registers the component to the build system using idf_component_register:

  idf_component_register(SRCS "foo.c" "bar.c"
                       INCLUDE_DIRS "include"
                       REQUIRES mbedtls)
  

• SRCS is a list of source files (*.c, *.cpp, *.cc, *.S). These source files will be compiled into the component library.
• INCLUDE_DIRS is a list of directories to add to the global include search path for any component which requires this component, and also the main source files.
• REQUIRES is not actually required, but it is very often required to declare what other components this component will use. See Component Requirements.

Bare minimum things needed in a ESP-IDF Project:

myproject
        CMakeLists.txt
        Makefile
        main
            CMakeLists.txt
            main.c
            component.mk

• CMakeLists.txt needed to compile the project
• Makefile only for backward compatibility with old esp-idf
• main directory contains the source code, CMakeLists.txt as main is a special component, main.c is the source file, component.mk is needed in every component to tell the build system that this is a component, since we know main is also a special component.