embedded-toolchain

Embedded Toolchain (CMake + GCC)

This skill covers the build layer underneath the SDK — the toolchain file, linker script, startup code, and CMake structure that turns C/C++ source into a binary that runs on bare metal.

When to Use

• Setting up a new embedded project with CMake (not CubeIDE or Arduino)
• Debugging linker errors (undefined reference, region overflow, multiple definition)
• Understanding the memory map of a firmware binary
• Adding a new source file, library, or component to the build
• Configuring flashing and debugging with OpenOCD

When NOT to Use

• ESP-IDF projects — IDF has its own CMake integration (idf_component_register), see esp32-idf
• Arduino IDE projects — different build system entirely
• CubeIDE-managed projects — use CMakeLists only if you explicitly export from CubeIDE

Toolchain Setup

arm-none-eabi (Cortex-M: STM32, RP2040, etc.)

# Install on Ubuntu/Debian
sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi

# Or download from ARM developer site (latest):
# https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
# Extract and add to PATH

# Verify
arm-none-eabi-gcc --version

RISC-V (ESP32-C3/C6, RP2350 RISC-V core)

# ESP32-C3/C6 — use IDF toolchain manager
idf.py --version  # IDF installs the correct riscv toolchain automatically

# Standalone RISC-V (RP2350)
# Pico SDK handles toolchain — use SDK's CMake integration

Toolchain File

The toolchain file tells CMake to cross-compile instead of using the host compiler:

# toolchain-arm-cortex-m4.cmake
# Usage: cmake -B build -DCMAKE_TOOLCHAIN_FILE=toolchain-arm-cortex-m4.cmake

set(CMAKE_SYSTEM_NAME      Generic)    # bare metal, no OS
set(CMAKE_SYSTEM_PROCESSOR arm)

# Toolchain binaries (adjust path if not in PATH)
set(CMAKE_C_COMPILER       arm-none-eabi-gcc)
set(CMAKE_CXX_COMPILER     arm-none-eabi-g++)
set(CMAKE_ASM_COMPILER     arm-none-eabi-gcc)
set(CMAKE_AR               arm-none-eabi-ar)
set(CMAKE_OBJCOPY          arm-none-eabi-objcopy)
set(CMAKE_OBJDUMP          arm-none-eabi-objdump)
set(CMAKE_SIZE             arm-none-eabi-size)

# Prevent CMake from testing the compiler by trying to link an executable
# (can't run ARM binary on host)
set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)

# MCU-specific flags — customize per target
# Cortex-M4F (STM32F4, STM32F7 at M4 mode)
set(MCU_FLAGS "-mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard")

# Cortex-M3 (STM32F1, STM32L1)
# set(MCU_FLAGS "-mcpu=cortex-m3 -mthumb")

# Cortex-M0+ (STM32G0, STM32L0, RP2040)
# set(MCU_FLAGS "-mcpu=cortex-m0plus -mthumb")

# Cortex-M7 (STM32H7, STM32F7)
# set(MCU_FLAGS "-mcpu=cortex-m7 -mthumb -mfpu=fpv5-d16 -mfloat-abi=hard")

set(CMAKE_C_FLAGS_INIT   "${MCU_FLAGS}")
set(CMAKE_CXX_FLAGS_INIT "${MCU_FLAGS}")
set(CMAKE_ASM_FLAGS_INIT "${MCU_FLAGS} -x assembler-with-cpp")
set(CMAKE_EXE_LINKER_FLAGS_INIT "${MCU_FLAGS}")