ESP32 ESP-IDF CMake Template

A minimal CMake template for ESP boards built on top of ESP-IDF. Select a board and an application variant, then build. ESP-IDF is vendored as a git submodule under external/, so the build always uses a known IDF version.

Requirements

• Python 3
• CMake (>= 3.19)
• Ninja
• git (for submodules)

The ESP toolchain itself is installed by ESP-IDF (see One-time setup).

One-time setup

Initialize the ESP-IDF submodule and install its toolchain/Python env:

git submodule update --init external/esp-idf

Windows (PowerShell):

external\esp-idf\install.ps1 esp32
external\esp-idf\export.ps1

Linux / macOS:

./external/esp-idf/install.sh esp32
. ./external/esp-idf/export.sh

export must be sourced in every new terminal before building.

Build

Two presets are provided, both targeting esp32:

cmake --preset Default
cmake --build build

cmake --preset Freertos
cmake --build build

Preset	Variant	Target
Default	DEFAULT	esp32
Freertos	FREERTOS	esp32

ESP-IDF always includes FreeRTOS. The Freertos preset additionally defines ESP_STACK_FREERTOS, which spawns an application task in main.c.

Flash and monitor

ESP-IDF exposes native build targets:

cmake --build build --target flash
cmake --build build --target monitor

Options

Variable	Values	Default
ESP_BOARD	any file under cmake/boards/	esp32-devkitc
ESP_STACK	DEFAULT | FREERTOS	DEFAULT

Available boards:

• esp32-devkitc (esp32)
• esp32s3-devkitc (esp32s3)

Build for another board without a preset:

cmake -B build -G Ninja -DESP_BOARD=esp32s3-devkitc .
cmake --build build

When switching board/target, delete the build directory first:

cmake -E rm -rf build

Project layout

CMakeLists.txt        Top-level IDF project, maps board -> IDF target
CMakePresets.json     Default / Freertos presets
cmake/boards/*.cmake  Per-board definitions (sets IDF_TARGET)
main/
  CMakeLists.txt      idf_component_register
  main.c              app_main entry point
  main.h
external/
  esp-idf             ESP-IDF as a git submodule

Application code

Add your .c / .cpp files under main/. They are picked up automatically. The entry point is app_main (ESP-IDF convention). For C++, declare it as extern "C" void app_main(void).

Adding a new board

Create cmake/boards/<name>.cmake setting IDF_TARGET to the desired chip (e.g. esp32, esp32s3, esp32c3).