Leave a Comment / By /

Chapter 25: Build System and CMake in ESP-IDF

Chapter Objectives

  • Understand the purpose and necessity of a build system in embedded development.
  • Learn why ESP-IDF uses CMake as its underlying build system generator.
  • Recognize the standard ESP-IDF project structure and the role of CMakeLists.txt files.
  • Understand the structure and common commands used in top-level and component CMakeLists.txt files.
  • Learn about key CMake functions used in ESP-IDF, particularly idf_component_register.
  • Understand the concept of component dependencies (REQUIRES, PRIV_REQUIRES).
  • Get an overview of the different stages of the ESP-IDF build process (configure, build).
  • Identify key artifacts generated during the build process (ELF file, binary file, map file).

Introduction

Throughout this volume, we’ve been using commands like idf.py build, idf.py flash, and idf.py menuconfig without necessarily diving deep into how they work. These commands are convenient front-ends to a sophisticated build system that automates the complex process of turning our C code and configurations into a runnable binary file for the ESP32.

A build system handles tasks like compiling source files, linking object code with libraries, managing dependencies between different code modules (components), and incorporating configuration settings. Without one, manually compiling and linking even a moderately complex project would be incredibly tedious and error-prone.

ESP-IDF uses CMake as its underlying build system generator. CMake is a powerful, cross-platform tool that uses configuration files (named CMakeLists.txt) to define how a project should be built. Understanding the basics of CMake and how ESP-IDF utilizes it is essential for managing complex projects, creating custom components, and troubleshooting build issues. This chapter demystifies the ESP-IDF build process, explaining the role of CMake, components, and the key configuration files involved.

Theory

What is a Build System?

At its core, a build system automates the process of transforming source code and related assets into an executable program or library. Its responsibilities typically include:

  1. Dependency Management: Determining the correct order to compile files based on dependencies (e.g., header file includes).
  2. Compilation: Invoking the compiler (like GCC or Clang) with the correct flags to turn source code (.c, .cpp) into object files (.o).
  3. Linking: Invoking the linker to combine object files and libraries into a final executable file (e.g., an .elf file for the ESP32).
  4. Configuration Management: Incorporating settings (like those from Kconfig/menuconfig) into the build process, often by defining preprocessor macros.
  5. Automation: Providing simple commands (like make, ninja, or idf.py build) to perform all necessary steps.
Responsibility Description
Dependency Management Determines the correct order to compile files based on includes and component requirements (e.g., compile component A before component B if B depends on A).
Compilation Invokes the compiler (e.g., GCC) with appropriate flags to convert source code files (.c, .cpp) into intermediate object files (.o).
Linking Invokes the linker to combine object files (.o) and necessary libraries (.a) into a single final executable file (e.g., .elf).
Configuration Management Integrates project settings (e.g., from `menuconfig`/`sdkconfig`) into the build, often by defining preprocessor macros (`CONFIG_…`) used in the source code.
Automation Provides simple commands (e.g., `idf.py build`) to execute the entire sequence of compilation, linking, and related tasks reliably.

Why CMake?

ESP-IDF uses CMake because it offers several advantages:

  • Cross-Platform: CMake can generate build files for various native build tools (like Makefiles for make, Ninja build files for ninja) and IDEs (like VS Code, CLion).
  • Widely Used: It’s a popular standard in the C/C++ world, making it familiar to many developers.
  • Extensibility: CMake has its own scripting language, allowing complex build logic and customization, which ESP-IDF leverages extensively.
  • Out-of-Source Builds: CMake encourages keeping generated build files separate from the source code (the build directory), keeping the source tree clean.

Note: While CMake generates the build files, the actual compilation and linking are usually performed by another tool like ninja (default in ESP-IDF, known for speed) or make. idf.py acts as a wrapper around CMake and the underlying build tool (ninja or make).

flowchart LR
    %% Style configuration
    %%{ init: {
        'theme': 'base',
        'themeVariables': {
            'primaryColor': '#EDE9FE',
            'primaryTextColor': '#5B21B6',
            'primaryBorderColor': '#5B21B6',
            'lineColor': '#A78BFA',
            'textColor': '#1F2937',
            'fontFamily': '"Open Sans", sans-serif'
        }
    } }%%

    %% Node definitions
    User["User Command<br>(idf.py build)"]:::userStyle
    CMake["CMake<br>(Configuration)"]:::cmakeStyle
    Ninja["Ninja / Make<br>(Compilation/Link)"]:::ninjaStyle
    Build["Build Artifacts<br>(.elf, .bin, .map, etc.)"]:::artifactStyle

    %% Flow connections
    User -->|"1- Invoke"| CMake
    User -->|"3- Invoke"| Ninja
    CMake -->|"2- Generate<br>Build Files"| Ninja
    Ninja -->|"4- Produce"| Build

    %% Class definitions for styling nodes
    classDef userStyle fill:#EDE9FE,stroke:#5B21B6,stroke-width:1.5px,color:#5B21B6,font-weight:600
    classDef cmakeStyle fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF
    classDef ninjaStyle fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E
    classDef artifactStyle fill:#D1FAE5,stroke:#059669,stroke-width:1px,color:#065F46
Advantage Benefit for ESP-IDF
Cross-Platform Generates native build files (Makefiles, Ninja files) for different operating systems (Linux, macOS, Windows) and IDEs, ensuring consistency.
Widely Used Standard Leverages a familiar tool for many C/C++ developers, reducing the learning curve.
Extensibility Allows ESP-IDF developers to create complex build logic, custom functions (like `idf_component_register`), and integrate tools like Kconfig seamlessly.
Out-of-Source Builds Keeps the project’s source code directory clean by placing generated build files, object files, and binaries in a separate `build` directory.
Dependency Handling Provides robust mechanisms for defining and resolving dependencies between different code modules (components).

Note: `idf.py` acts as a user-friendly wrapper around CMake and the actual build tool (like Ninja or Make).

ESP-IDF Project Structure and CMakeLists.txt

As discussed previously, ESP-IDF projects are typically organized into components. The build system relies on CMakeLists.txt files at different levels to understand the project structure:

  • Project Root CMakeLists.txt: Located in the project’s root directory. It defines the project name, specifies the minimum CMake version required, and crucially, includes ESP-IDF’s core CMake scripts which set up the toolchain and build environment. It also usually defines where to find components.
  • Component CMakeLists.txt: Located in the root directory of each component (including main). It defines the component’s properties: its source files, include directories, and dependencies on other components.

Example project Structure:

Plaintext
my_project/
├── main/
│   ├── CMakeLists.txt
│   ├── Kconfig.projbuild  (We'll create this)
│   └── main.c
├── components/
│   └── custom_module/
│       ├── CMakeLists.txt     (We'll create this)
│       ├── Kconfig            (We'll create this)
│       ├── Kconfig.projbuild  (We'll create this)
│       └── custom_module.c    (We'll create this)
│       └── include/
│           └── custom_module.h (We'll create this)
├── CMakeLists.txt
├── partitions.csv
└── sdkconfig

Top-Level CMakeLists.txt Breakdown

A minimal top-level CMakeLists.txt file looks like this:

CMake
# Specifies the minimum version of CMake required.
cmake_minimum_required(VERSION 3.16)

# Includes ESP-IDF's main project CMake file, setting up the build environment,
# toolchain, and providing IDF-specific functions.
# IDF_PATH environment variable must be set.
include($ENV{IDF_PATH}/tools/cmake/project.cmake)

# Defines the project name. This will be the name of the final .elf and .bin files.
project(my_esp32_project)
  • cmake_minimum_required(): Declares the minimum CMake version needed to process this file. ESP-IDF v5.x generally requires 3.16 or higher.
  • include($ENV{IDF_PATH}/tools/cmake/project.cmake): This is the most critical line. It pulls in the core ESP-IDF build logic, which defines functions like idf_component_register, handles toolchain setup, finds components, and integrates Kconfig. It relies on the IDF_PATH environment variable being set correctly (the ESP-IDF install script usually handles this).
  • project(): Defines the name of your project. This name is used for the final output files (e.g., my_esp32_project.elf, my_esp32_project.bin).
  • set(EXTRA_COMPONENT_DIRS dirs...): (Optional) Specifies additional directories (relative to the project root) where the build system should look for components (e.g., `set(EXTRA_COMPONENT_DIRS components)`).

You might also see set(EXTRA_COMPONENT_DIRS components) if you have custom components in a directory named components.

Component CMakeLists.txt Breakdown

This file defines how a specific component is built. A typical component CMakeLists.txt (e.g., for the main component or a custom one) uses the idf_component_register function:

CMake
# CMakeLists.txt for component 'my_component'

# Register the component with the build system.
idf_component_register(
    SRCS            "my_component.c" "another_source.c" # List of source files
    INCLUDE_DIRS    "include"                         # List of public include directories
    PRIV_INCLUDE_DIRS "private_include"               # List of private include directories
    REQUIRES        "driver" "freertos"               # List of public dependencies
    PRIV_REQUIRES   "spi_flash"                       # List of private dependencies
)

idf_component_register(): This is the primary ESP-IDF function for defining a component. It takes several arguments:

Parameter Description
SRCS A list of source files (.c, .cpp, .S) belonging to this component. Paths are relative to the component’s directory. (e.g., "file1.c" "src/file2.c")
INCLUDE_DIRS List of directories (relative to component dir) containing public header files (.h). These directories are added to the include path of any component that REQUIRES this one. (e.g., "include")
PRIV_INCLUDE_DIRS List of directories (relative to component dir) containing private header files. These are added to the include path only when compiling this component’s own source files. (e.g., "private_include")
REQUIRES List of other component names this component depends on. Ensures dependencies are built first and makes their INCLUDE_DIRS available. Dependencies are propagated (if A requires B, and B requires C, A gets C’s includes too). (e.g., "driver" "freertos")
PRIV_REQUIRES List of other component names this component depends on privately. Similar to REQUIRES but the dependency is not propagated upwards. Used to hide internal implementation details. (e.g., "spi_flash")
LDFRAGMENTS (Less common) Specifies linker script fragments (.lf files) to be included when linking the final application.
EMBED_FILES / EMBED_TXTFILES (Less common) Allows embedding binary or text files directly into the component’s object code, accessible via symbols at runtime.

Tip: The main component is treated like any other component and needs its own CMakeLists.txt (usually just registering its source files and maybe requiring other components).

Comparing Component Dependencies: REQUIRES vs. PRIV_REQUIRES

Feature REQUIRES (Public Dependency) PRIV_REQUIRES (Private Dependency)
Purpose Declare dependency on another component whose features (headers, functions) are needed by this component AND potentially by components that depend on this one. Declare dependency on another component needed only for the internal implementation of this component.
Include Path Access Adds the dependency’s INCLUDE_DIRS to this component’s include path. Adds the dependency’s INCLUDE_DIRS to this component’s include path.
Dependency Propagation Yes. If Component C REQUIRES Component B, and Component B REQUIRES Component A, then Component C also gains access to Component A’s public headers. No. If Component C PRIV_REQUIRES Component B, and Component B REQUIRES Component A, Component C does not automatically gain access to Component A’s headers via this private link.
Typical Use Case Depending on standard libraries (freertos, driver), utility components, or components providing a public API. Depending on components used only internally (e.g., a logging component used by a driver, but not exposed by the driver’s API), or to avoid polluting the include path of higher-level components.

Other Common CMake Functions

  • set(VARIABLE_NAME "value"): Sets a CMake variable. Can be used for various purposes, like defining compiler flags or paths.
  • target_include_directories(): Another way to add include directories, often used for more complex scenarios or when dealing with external libraries not managed as ESP-IDF components.
  • target_link_libraries(): Specifies libraries to link against. While ESP-IDF’s component dependency system (REQUIRES/PRIV_REQUIRES) handles most linking automatically, this might be needed for precompiled third-party libraries.
  • register_component(): An older function similar to idf_component_register. You might see it in older examples, but idf_component_register is preferred in modern ESP-IDF versions.

The Build Process Overview

When you run idf.py build (or related commands like flash, monitor), several stages occur:

  1. Configuration (CMake Phase):
    • CMake is invoked.
    • It reads the top-level CMakeLists.txt.
    • It finds all components (in ESP-IDF, project components/, EXTRA_COMPONENT_DIRS).
    • It processes each component’s CMakeLists.txt.
    • It processes all Kconfig files and generates the sdkconfig file (if menuconfig was run) and the sdkconfig.h header.
    • It resolves component dependencies.
    • It generates the actual build scripts for the underlying build tool (e.g., build.ninja for Ninja) in the build directory. This phase only runs if CMakeLists.txt files, Kconfig files, or the sdkconfig file have changed since the last run, or if it’s the first build.
  2. Build (Ninja/Make Phase):
    • The underlying build tool (ninja or make) is invoked.
    • It reads the generated build scripts (e.g., build.ninja).
    • It compiles source files that have changed since the last build into object files (.o), using the settings from sdkconfig.h and component dependencies.
    • It links the object files and required libraries (from ESP-IDF and components) into a final executable ELF file (<project_name>.elf).
    • It generates the final binary image file (<project_name>.bin) suitable for flashing, along with other artifacts like the partition table binary and bootloader binary.
    %%{ init: { 'theme': 'base', 'themeVariables': {
          'primaryColor': '#DBEAFE',      'primaryTextColor': '#1E40AF', 'primaryBorderColor': '#2563EB',
          'lineColor': '#A78BFA',         'textColor': '#1F2937',
          'mainBkg': '#FFFFFF',           'nodeBorder': '#A78BFA',
          'fontFamily': '"Open Sans", sans-serif'
    } } }%%
    graph TD
        Start["Start (idf.py build)"]:::startNode --> CheckChanges{"Changed Files?<br>(CMakeLists, Kconfig, sdkconfig)"};

        subgraph "Configuration Stage (CMake)"
            direction TB
            C1["Read Top-Level CMakeLists.txt"]:::processNode;
            C2["Find Components<br>(IDF, Project, EXTRA_COMPONENT_DIRS)"]:::processNode;
            C3["Process Component CMakeLists.txt"]:::processNode;
            C4["Process Kconfig / sdkconfig<br>Generate sdkconfig.h"]:::processNode;
            C5["Resolve Dependencies<br>(REQUIRES, PRIV_REQUIRES)"]:::processNode;
            C6["Generate Build Scripts<br>(e.g., build.ninja) in 'build/'"]:::processNode;
            C1 --> C2 --> C3 --> C4 --> C5 --> C6;
        end

        subgraph "Build Stage (Ninja / Make)"
            direction TB
            B1["Read Build Scripts (build.ninja)"]:::processNode;
            B2["Compile Changed Source Files (.c -> .o)"]:::processNode;
            B3["Link Object Files & Libraries"]:::processNode;
            B4["Create Executable (.elf)"]:::processNode;
            B5["Generate Final Binaries (.bin, partition, bootloader)"]:::processNode;
            B1 --> B2 --> B3 --> B4 --> B5;
        end

        CheckChanges -- Yes --> C1;
        CheckChanges -- No --> B1;
        C6 --> B1;
        B5 --> End([Build Complete]):::endNode;

        %% Styling
        classDef startNode fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
        classDef endNode fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46;
        classDef processNode fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
        classDef decisionNode fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;

The build Directory

After a successful build, the build directory contains many intermediate and final files. Some important ones include:

Important Files in the `build/` Directory

File / Path Description
<project_name>.elf The final linked executable file in ELF (Executable and Linkable Format). Contains debugging symbols and section information. Used by GDB for debugging.
<project_name>.bin The final binary image file that gets flashed onto the ESP32’s application partition. It’s stripped of most debugging information to save space.
<project_name>.map The linker map file. Details memory allocation, showing addresses and sizes of functions, variables, and sections. Useful for analyzing code size and debugging memory issues.
config/sdkconfig.h C header file automatically generated from `sdkconfig`. Contains `#define` macros (e.g., `CONFIG_…`) corresponding to the project’s configuration settings selected via `menuconfig`.
compile_commands.json A JSON database listing the exact compile commands used for each source file. Used by IDEs and language servers (like clangd) for accurate code analysis and navigation.
bootloader/bootloader.bin The compiled binary for the ESP-IDF bootloader. Flashed to the bootloader partition.
partition_table/partition-table.bin The compiled binary for the partition table, defining the layout of the flash memory.
esp-idf/<component>/... Subdirectories containing intermediate object files (.o) and static library archives (.a) for each component used in the build.

Warning: Do not modify files in `build/` directly. Use `idf.py fullclean` to remove it if needed (requires reconfiguration).

Warning: You should generally not modify files in the build directory directly, as they are regenerated by the build system. You can safely delete the entire build directory; it will be fully recreated on the next build (though this will trigger a full recompilation).

Practical Examples

Example 1: Analyzing hello_world CMakeLists

  1. Locate Files: Open the standard hello_world example project provided with ESP-IDF. Examine:
    • hello_world/CMakeLists.txt (Top-Level)
    • hello_world/main/CMakeLists.txt (Main Component)
  2. Top-Level Analysis:
    • Notice the cmake_minimum_required(), include(...), and project(hello-world) lines, establishing the basic project setup.
  3. Main Component Analysis:
    • Observe the idf_component_register() call.
    • Identify the SRCS argument listing hello_world_main.c.
    • Note any REQUIRES (might be empty or require basic components like log).

Example 2: Creating and Using a Simple Utility Component

Let’s create a utils component with a simple helper function and use it from main.

Create Component Structure:

Inside your project (e.g., based on hello_world), create:

Plaintext
my_project/
├── components/
│   └── utils/
│       ├── CMakeLists.txt
│       ├── utils.c
│       └── include/
│           └── utils.h
... (rest of project structure) ...

Create components/utils/include/utils.h:

C
#ifndef UTILS_H
#define UTILS_H

int add_two_numbers(int a, int b);

#endif // UTILS_H

Create components/utils/utils.c:

C
#include "utils.h"

int add_two_numbers(int a, int b) {
    return a + b;
}

Create components/utils/CMakeLists.txt:

Plaintext
# CMakeLists.txt for component 'utils'

idf_component_register(SRCS "utils.c"
                       INCLUDE_DIRS "include")
                       # No requirements for this simple example

Modify main/CMakeLists.txt:

Add utils to the REQUIRES list of the main component.

Plaintext
# CMakeLists.txt for component 'main'

idf_component_register(SRCS "your_main_file.c" # Replace with your main C file name
                       INCLUDE_DIRS "."         # Often needed if main.c includes headers in main/
                       REQUIRES utils)          # <<< Add this requirement

(If main didn’t previously have REQUIRES, you’ll need to add the keyword)

Modify main/your_main_file.c:

Include the header and use the function.

C
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "utils.h" // Include the header from our component

static const char *TAG = "MAIN";

void app_main(void)
{
    ESP_LOGI(TAG, "Main application started.");

    int result = add_two_numbers(5, 7);
    ESP_LOGI(TAG, "Result from utils component: 5 + 7 = %d", result);

    ESP_LOGI(TAG, "Entering infinite loop...");
    while(1) {
        vTaskDelay(pdMS_TO_TICKS(10000));
    }
}

Modify Project CMakeLists.txt (if needed):

Ensure set(EXTRA_COMPONENT_DIRS components) is present if you created the components directory yourself.

Build, Flash, Monitor:

  1. idf.py build
  2. idf.py flash
  3. idf.py monitor

Expected Output:

The monitor should show the log message including the result 12 calculated by the function from the utils component. This demonstrates that main successfully depended on, included the header from, and linked against the utils component.

Plaintext
I (xxx) MAIN: Main application started.
I (xxx) MAIN: Result from utils component: 5 + 7 = 12
I (xxx) MAIN: Entering infinite loop...


    %%{ init: { 'theme': 'base', 'themeVariables': {
          'primaryColor': '#DBEAFE',      'primaryTextColor': '#1E40AF', 'primaryBorderColor': '#2563EB',
          'lineColor': '#A78BFA',         'textColor': '#1F2937',
          'mainBkg': '#FFFFFF',           'nodeBorder': '#A78BFA',
          'fontFamily': '"Open Sans", sans-serif'
    } } }%%
    graph TD
        subgraph "Project Components"
            Main["main<br>(Application Entry Point)"]:::mainComp;
            Utils["utils<br>(Utility Functions)"]:::utilComp;
            Driver["low_level_driver<br>(Hardware Access - Example)"]:::driverComp;
        end

        Main -- "REQUIRES" --> Utils;
        Utils -- "REQUIRES" --> Driver;

        subgraph "Build Order & <br> Include Access"
            d["Build Order & <br> Include Access"]
            BuildOrder["Build Order: <br>1. low_level_driver<br>2. utils<br>3. main"]:::infoBox;
            IncludeAccess["Include Access:<br>- 'main' includes 'utils.h'<br>- 'utils' includes 'low_level_driver.h'<br>- 'main' CAN include 'low_level_driver.h' (due to propagation)"]:::infoBox;
        end

        Utils --> BuildOrder;
        Utils --> IncludeAccess;


        %% Styling
        classDef mainComp fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
        classDef utilComp fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
        classDef driverComp fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;
        classDef infoBox fill:#F3F4F6,stroke:#9CA3AF,stroke-width:1px,color:#4B5563,padding:15px;

Example 3: Adding Pre-compiled Library (Conceptual)

While the ESP-IDF component manager is the preferred way to add external libraries, sometimes you might have a pre-compiled static library (.a file). Here’s conceptually how you might integrate it (adapt paths and names):

Place Library: Copy lib_something.a and its header something.h into a component (e.g., my_component/lib/).

Update Component CMakeLists.txt:

Plaintext
# CMakeLists.txt for component 'my_component'

set(MY_LIB_DIR ${CMAKE_CURRENT_LIST_DIR}/lib)

idf_component_register(
    SRCS            "my_component.c"
    INCLUDE_DIRS    "include" "lib" # Add lib dir to includes for something.h
    REQUIRES        # ... other dependencies ...
)

# Explicitly link the precompiled library
target_link_libraries(${COMPONENT_LIB} PRIVATE ${MY_LIB_DIR}/lib_something.a)

# Or if the library itself needs system libs not covered by REQUIRES:
# target_link_libraries(${COMPONENT_LIB} PRIVATE "-L${MY_LIB_DIR}" "-l:lib_something.a" m c) # Example

  • ${COMPONENT_LIB} is a CMake variable representing the component being built.
  • target_link_libraries tells CMake to link the specified library (lib_something.a) when building this component (${COMPONENT_LIB}). PRIVATE means only this component links directly against it.

Note: This is simplified. Integrating pre-compiled libraries can involve handling different architectures, dependencies of the library itself, and toolchain compatibility. Using the component manager is usually much easier.

Variant Notes

The CMake build system structure and the core ESP-IDF CMake functions (idf_component_register, etc.) are consistent across all supported ESP32 variants. The build process itself doesn’t fundamentally change whether you are targeting an ESP32, ESP32-S3, or ESP32-C3.

The primary differences related to variants manifest within the components themselves and the Kconfig options:

  • Target Setting: The specific chip target (e.g., esp32, esp32s3) is set via idf.py set-target <target> and stored (often in sdkconfig). The build system uses this target to select the correct toolchain, core libraries (like HAL), and default component configurations specific to that chip.
  • Component Availability: Some components in ESP-IDF might only be available or applicable for certain variants (e.g., components related to USB OTG for S2/S3, Thread/Zigbee for H2/C6). The build system handles including the correct components based on the target and configuration.
  • Conditional Compilation: Within component source code or CMakeLists.txt, developers might use CONFIG_IDF_TARGET_... macros (defined based on the target) to include/exclude code or change build steps specific to a variant.

So, while you use the same CMake structure, the content being processed and the final binary output are tailored to the specific ESP32 variant you are building for.

Common Mistakes & Troubleshooting Tips

Mistake / Issue Symptom(s) Troubleshooting / Solution
Syntax Errors in CMakeLists.txt
Typos, missing parentheses, invalid commands.		 idf.py build fails early (configure phase) with CMake errors pointing to specific lines. Review CMake syntax carefully. Check parentheses, quotes. Refer to ESP-IDF examples or CMake docs.
Forgetting idf_component_register or Missing SRCS
Component definition incomplete.		 Component source files not compiled. Linker errors (“undefined reference”). Component might not be recognized. Ensure every component has CMakeLists.txt with a valid idf_component_register() call including all source files (.c, .cpp, .S) in SRCS.
Missing Include Dirs (INCLUDE_DIRS / PRIV_INCLUDE_DIRS)
Header locations not specified.		 Compilation errors: “fatal error: header_file.h: No such file or directory”. Add relative path(s) to header directories to the appropriate INCLUDE_DIRS (public) or PRIV_INCLUDE_DIRS (private) list in idf_component_register().
Missing Dependencies (REQUIRES / PRIV_REQUIRES)
Component uses another component without declaring it.		 Compilation errors (“No such file or directory” for dependency headers) OR Linker errors (“undefined reference” for dependency functions/variables). Identify needed components and add their names to the REQUIRES (common) or PRIV_REQUIRES list in the dependent component’s CMakeLists.txt.
Incorrect Component Name in REQUIRES
Typo in dependency name.		 CMake error during configuration: “Component ‘…’ required by ‘…’ not found.” Verify the exact name of the required component (usually directory name). Check spelling and case. Ensure it’s in a standard location or listed in EXTRA_COMPONENT_DIRS.
Build Directory Issues (build/)
Manual edits or stale artifacts.		 Strange build errors, config not updating, runtime behavior mismatching source code. Avoid editing build/. Run idf.py reconfigure or idf.py fullclean (deletes build/ and sdkconfig – requires re-running menuconfig) then idf.py build.

Exercises

  1. Add Source File: Create a new C file (e.g., helper.c) inside your project’s main directory. Define a simple function inside it (e.g., void print_message(const char* msg)). Modify main/CMakeLists.txt to include helper.c in the SRCS list. Call your new function from app_main. Build, flash, and verify it works.
  2. Create Dependency Chain: Create a new minimal component named low_level_driver. Give it a header file (low_level_driver.h) and a C file (low_level_driver.c) with a simple function (e.g., int read_sensor_register(int reg_addr)). Now, modify the utils component (from Example 2) so that its add_two_numbers function also calls read_sensor_register (just return a dummy value from read_sensor_register). Update the utils/CMakeLists.txt to add REQUIRES low_level_driver. Ensure main still REQUIRES utils. Build and verify that the dependency chain (main -> utils -> low_level_driver) compiles and links correctly.
  3. Explore Build Artifacts: After a successful build (idf.py build), navigate into the build/ directory.
    • Locate the final ELF file (<project_name>.elf).
    • Locate the final binary file (<project_name>.bin).
    • Locate the map file (<project_name>.map) and open it in a text editor. Try to find the addresses of familiar functions like app_main or functions from your custom components.
    • Locate the generated config/sdkconfig.h file and observe how Kconfig options are defined as C macros.

Summary

  • Build systems automate the compilation and linking process. ESP-IDF uses CMake as its build system generator.
  • Projects are structured into components, each potentially having its own source files, headers, and CMakeLists.txt.
  • The top-level CMakeLists.txt initializes the project and includes ESP-IDF’s core build logic.
  • Component CMakeLists.txt files use idf_component_register to define source files (SRCS), public include directories (INCLUDE_DIRS), private include directories (PRIV_INCLUDE_DIRS), public dependencies (REQUIRES), and private dependencies (PRIV_REQUIRES).
  • Dependencies declared via REQUIRES automatically handle include paths and linking order.
  • The build process involves a configuration phase (CMake generates build scripts) and a build phase (Ninja/Make compiles and links).
  • The build/ directory contains intermediate files and final outputs like the .elf, .bin, and .map files.

Further Reading

Related Posts

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top