Comprehensive Guide to ESP-IDF Project Structure and CMake Mechanisms! (VSCode + ESP-IDF Extension)

It’s been quite some time since I wrote the article “Trying Out the ESP-IDF Extension 'Espressif IDF' for VSCode”.
This time, I will focus on how ESP-IDF projects are structured and how the CMake mechanism works.

ESP-IDF uses CMake, a “build system generator.”
With CMake, you can describe and manage the build process in a tool- and environment-agnostic way (cross-platform support).
By properly understanding files like CMakeLists.txt that you may not often touch, ESP-IDF’s unique sdkconfig, and the idf.py mechanism, you can develop in a more flexible and extensible manner.

Also, although it’s not directly related to this article, ESP-IDF can use Ninja as its build system.
If Ninja is installed, it will be used by default.
Ninja is a super-fast build system. Based on the build rules generated by tools like CMake, it efficiently compiles and links source code to create executables.

I’ve been using PlatformIO extensively, but since detailed configurations require invoking ESP-IDF features, I’ve recently been studying ESP-IDF.
When I used ESP-IDF before, I was fed up with slow builds, but after switching to Ninja, builds became very fast and I can use it without stress.

• Those who have just started ESP32 development with ESP-IDF
• Those who are uneasy about editing CMakeLists.txt
• Those who want to add custom libraries or reusable components to their projects

Assuming from the previous article that you have already completed the ESP-IDF development environment installation, we will proceed.

Select “New Project” and create a project.

Set the “Project Name”, “Project Directory”, “Board”, and “Serial Port” accordingly.
(The component directory does not need to be set.)

Select “template-app” and click “Create project using template template-app.”

The created ESP-IDF project structure is as follows.

my_project/ 
├── CMakeLists.txt      ← Project-wide CMake configuration
├── sdkconfig           ← Configuration file reflecting menuconfig settings
├── build/              ← Build outputs are stored here (auto-generated)
├── main/ 
│ ├── CMakeLists.txt    ← CMake configuration specifying source files
│ └── main.c            ← Entry point (main program)
├── .gitignore          ← Git ignore settings

By default, main/CMakeLists.txt looks like the following.

idf_component_register(SRCS "main.c"
                       INCLUDE_DIRS "")

This idf_component_register() is important.
idf_component_register() is a function used to register information about the component to which the current CMakeLists.txt belongs.

It has the following meanings.

By default, the CMakeLists.txt in the project root looks like the following.

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

It has the following meanings.

Normally, you don’t need to edit this file, but you can modify it when you want to add custom settings.

The sdkconfig file is the central configuration file of an ESP-IDF project, managing build options and enabling/disabling features during development. sdkconfig is generated using the Kconfig system. (We will discuss the Kconfig system later, so for now, just think of it as the file that manages build options and feature toggles during development.)

The sdkconfig file begins with the following lines, so you should avoid editing it manually.

#
# Automatically generated file. DO NOT EDIT.
# Espressif IoT Development Framework (ESP-IDF) 5.4.1 Project Configuration
#

When you configure using the following menuconfig subcommand, the settings are reflected in sdkconfig. (We will explain the idf.py command later.)

idf.py menuconfig 

You can also access “menuconfig” from the following menu in VSCode.

The menuconfig in VSCode provides a GUI for easy operation.
To save the configurations, press the “Save” button.

Examples of settings in sdkconfig are as follows. (They may vary slightly depending on the ESP-IDF version.)
For example, UART baud rate, enabling Wi-Fi, etc., are defined here.

※ You can also add custom definitions to sdkconfig (how to do this will be explained later).

The build system (CMake) conditionally compiles the source code based on the settings in sdkconfig.

For example, suppose sdkconfig has the following settings:

CONFIG_MY_LED_ENABLE=y
CONFIG_MY_LED_GPIO=2

You can then use conditional compilation in your code as follows:

#include <stdio.h>
#include "driver/gpio.h"

void app_main(void)
{
#ifdef CONFIG_MY_LED_ENABLE
    gpio_reset_pin(CONFIG_MY_LED_GPIO);
    gpio_set_direction(CONFIG_MY_LED_GPIO, GPIO_MODE_OUTPUT);
    gpio_set_level(CONFIG_MY_LED_GPIO, 1);  // LED ON
#endif
}

Besides the sdkconfig file, there are two closely related files.

When developing in a team and managing artifacts with Git, it is recommended to extract the initial settings needed by the team into sdkconfig.defaults.

The sdkconfig.defaults file applies default values only when sdkconfig does not yet exist, for example when running idf.py menuconfig or idf.py build.
If sdkconfig already exists, sdkconfig.defaults is completely ignored, and sdkconfig takes precedence.
Note that even if sdkconfig.defaults contains settings not in sdkconfig, they will not be loaded.

your_project/
├── sdkconfig.defaults        ← Write initial settings here (used only when sdkconfig is absent)
├── sdkconfig                 ← Actual configuration file generated by menuconfig, etc.
├── main/
│   ├── CMakeLists.txt
│   └── ...

The format and content are the same as sdkconfig. For example, you can write:

CONFIG_LOG_DEFAULT_LEVEL=3
CONFIG_PROJECT_USE_LED=y
CONFIG_MY_DRIVER_GPIO_NUM=13

The Kconfig system is a mechanism that automatically generates sdkconfig based on configuration options chosen by the user (e.g., whether to use Wi-Fi).

You create Kconfig files in each component or directory to define which configuration options are available.

Below is an example of a Kconfig file for a custom LED driver.
(The default LED GPIO on a typical ESP32 is 2, but on the ESP32 LOLIN D32 it is 5, so we specify “5.”)

menu "My LED Driver Configuration"

    config MY_LED_ENABLE
        bool "Enable LED driver"
        default y

    config MY_LED_GPIO
        int "GPIO number for LED"
        default 5
        depends on MY_LED_ENABLE

endmenu

When you run idf.py menuconfig, the settings are automatically generated in sdkconfig.
The options set by the user in menuconfig are ultimately written to the sdkconfig file and reflected in the build.

Set the options as shown in the menuconfig screen below, and then save.

Definitions like the following are created in the sdkconfig file:

#
# My LED Driver Configuration
#
CONFIG_MY_LED_ENABLE=y
CONFIG_MY_LED_GPIO=5
# end of My LED Driver Configuration
# end of Component config

There are two types of Kconfig files: Kconfig and Kconfig.projbuild.

Kconfig Files

Kconfig files are used as follows:

• Placed in each component
• Displayed in menuconfig for the user to select settings

Below is an example of a Kconfig file in a component:

menu "My Custom Driver Configuration"

    config USE_MY_DRIVER
        bool "Use my custom driver"
        default y

endmenu

Kconfig.projbuild Files

Kconfig.projbuild files are used as follows:

• Used in the main/ directory or any project scope
• When you want to collectively define additional settings for that project
• Automatically loaded at build time and reflected in menuconfig

Below is an example of a Kconfig.projbuild file in main/:

menu "Project-wide Options"

    config PROJECT_USE_LED
        bool "Enable LED feature for the whole project"
        default y

endmenu

Notes on Writing

When you define USE_XXXX in a Kconfig or Kconfig.projbuild file, it is registered as CONFIG_USE_XXXX in sdkconfig. (The prefix CONFIG_ is automatically added when expanding sdkconfig.)

You can use them as follows:

• Libraries and reusable components: Kconfig
• Project-specific settings: Kconfig.projbuild

my_project/
├── main/
│   ├── CMakeLists.txt
│   ├── my_code.c
│   └── Kconfig.projbuild   ← ※Project-specific settings
├── components/
│   └── my_led_driver/
│       ├── Kconfig         ← ※Component settings
│       └── CMakeLists.txt
├── sdkconfig
└── build/
    └── config/
        └── sdkconfig.h

In ESP-IDF projects, idf.py serves as the central tool for managing builds, flashing, monitoring, and more.
It is a Python-based CLI (command-line interface) that internally calls various tools like CMake and Ninja.

Here are some commonly used idf.py subcommands:

Thus, idf.py acts as a “hub” for ESP-IDF development, simplifying the bridging of various tools and project management.

In the VSCode extension, you can invoke the same subcommands from the following screen:

For example, let's consider creating a custom component (a homemade LED driver) in components/my_led_driver/.

Arrange the directory structure as follows:

components/
└── my_led_driver/
    ├── CMakeLists.txt
    ├── my_led_driver.c
    └── include/
        └── my_led_driver.h

Configure components/my_led_driver/CMakeLists.txt as follows:

idf_component_register(SRCS "my_led_driver.c"
                    INCLUDE_DIRS "include"
                    REQUIRES <required libraries; omit REQUIRES if none>)

In main.c, which calls this custom component, include the following:

#include "my_led_driver.h"

In main/CMakeLists.txt, specify the custom component by setting REQUIRES my_led_driver as follows:

idf_component_register(SRCS "main.c"
                    INCLUDE_DIRS "."
                    REQUIRES my_led_driver)

Below is a simple sample code for the custom component my_led_driver for ESP-IDF.
This is the basic structure for controlling an LED via GPIO (making the LED blink), commonly called “Blink”.

Below is an example project structure diagram including the custom component:

my_project/
├── CMakeLists.txt          ← Entry point defining the entire project
├── Makefile                ← Wrapper that just invokes the CMake build
├── sdkconfig               ← Build options set by menuconfig
├── build/                  ← Build artifacts (auto-generated)
├── main/
│   ├── CMakeLists.txt      ← Defines build targets in this directory (e.g., main.c)
│   └── main.c              ← Application entry point
│   └── Kconfig.projbuild   ← Project-specific definitions
├── components/             ← Location for custom components
│   └── my_led_driver/
│       ├── CMakeLists.txt  ← Build settings for the custom component
│       ├── my_led_driver.c
│       ├── Kconfig         ← Custom component definitions
│       └── include/
│           └── my_led_driver.h

Below are examples of the Kconfig, header, C file, and CMakeLists.txt.

components/my_led_driver/Kconfig
(Setting the LED GPIO to 5)

menu "My LED Driver Configuration"

    config MY_LED_GPIO
        int "GPIO number for LED"
        default 5

endmenu

components/my_led_driver/my_led_driver.h
(Defines three functions: my_led_init, my_led_on, and my_led_off)

#pragma once

#include "driver/gpio.h"

#ifdef __cplusplus
extern "C" {
#endif

// Initialization function
void my_led_init(gpio_num_t gpio_num);

// ON/OFF control
void my_led_on(void);
void my_led_off(void);

#ifdef __cplusplus
}
#endif

components/my_led_driver/my_led_driver.c
(Implementation of the GPIO operations)

#include "my_led_driver.h"

static gpio_num_t led_gpio = GPIO_NUM_NC;

void my_led_init(gpio_num_t gpio_num)
{
    led_gpio = gpio_num;

    gpio_config_t io_conf = {
        .pin_bit_mask = 1ULL << led_gpio,
        .mode = GPIO_MODE_OUTPUT,
        .pull_up_en = GPIO_PULLUP_DISABLE,
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type = GPIO_INTR_DISABLE,
    };
    gpio_config(&io_conf);

    my_led_off(); // Initial state OFF
}

void my_led_on(void)
{
    if (led_gpio != GPIO_NUM_NC) {
        gpio_set_level(led_gpio, 1);
    }
}

void my_led_off(void)
{
    if (led_gpio != GPIO_NUM_NC) {
        gpio_set_level(led_gpio, 0);
    }
}

components/my_led_driver/CMakeLists.txt
(Since it controls GPIO, the esp_driver_gpio library is required)

idf_component_register(SRCS "my_led_driver.c"
                       INCLUDE_DIRS "include"
                       REQUIRES esp_driver_gpio)

Below are the Kconfig.projbuild, C file, and CMakeLists.txt.

main/Kconfig.projbuild
(Defines a flag for whether to use the LED driver)

menu "My LED Driver Configuration"

    config MY_LED_ENABLE
        bool "Enable LED driver"
        default y

endmenu

main/main.c
(Calls the custom component)

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "my_led_driver.h"

void app_main(void)
{
    my_led_init(CONFIG_MY_LED_GPIO);

    #ifdef CONFIG_MY_LED_ENABLE
    while (1) {
        my_led_on();
        vTaskDelay(pdMS_TO_TICKS(500));
        my_led_off();
        vTaskDelay(pdMS_TO_TICKS(500));
    }
    #endif    
}

main/CMakeLists.txt
(Requires the custom component)

idf_component_register(SRCS "main.c"
                    INCLUDE_DIRS "."
                    REQUIRES my_led_driver)

This way, components/my_led_driver is integrated into the ESP-IDF build as a custom component, resulting in an extensible project structure.

In this article, we explained the components of an ESP-IDF project and their roles, the position of the idf.py command, and how to create custom components.
ESP-IDF projects are centered around CMakeLists.txt and sdkconfig, allowing flexible management of builds and settings.
Additionally, for beginners, using idf.py means you can start development easily without worrying about environment dependencies or the complexities of CMake.

Compared to PlatformIO, ESP-IDF may seem difficult at first glance, but once you understand the purpose of each file and tool, you can confidently engage in development.

I hope this helps your IoT development.