Skip to main content

STM32 Environment Setup

This page applies to CMake projects exported by STM32CubeMX. VS Code is the recommended editor flow. STM32CubeMX2 / HAL2 is currently out of scope.

The video tutorials (Chinese) are recommended alongside this page. They were recorded before libxr 6.0.0 and xrobot 1.0.0 were released and use the old commands: the libxr 5.x xr_* commands and the 6.0.0 libxr subcommands that replace them are listed in the CodeGenerator README, and the xrobot 1.0.0 commands in Project Management.

Basic Environment​

Windows:

  • git
  • python
  • STM32CubeMX
  • CMake and Ninja
  • the compiler arm-none-eabi-gcc (GNU Tools for STM32) or starm-clang (ST Arm Clang)

CMake, Ninja and the compilers can be downloaded by STMicroelectronics.stm32-vscode-extension into %LOCALAPPDATA%\stm32cube\bundles, or installed with STM32CubeCLT. For command-line builds, the directories of these tools must be on PATH, see the section "CLion / Command-Line Builds" below.

Linux:

sudo apt update
sudo apt install -y git python3 python3-pip cmake tar xz-utils wget pipx ninja-build

The Arm compilers are not in apt. They can be installed with the Linux version of STM32CubeCLT, or the Arm GNU Toolchain (arm-none-eabi-gcc) can be downloaded from Arm; after installation, add the bin directory of the compiler to PATH. The docker-image-stm32 image has the Arm GNU Toolchain 14.2 and ST Arm Clang installed, with arm-none-eabi-gcc and starm-clang callable directly.

VS Code Workflow​

Create the project in STM32CubeMX first and export it as a CMake project. In Project Manager, choose gcc or starm-clang as Default Compiler/Linker. CubeMX writes that choice into CMakePresets.json, typically through ${sourceDir}/cmake/gcc-arm-none-eabi.cmake or ${sourceDir}/cmake/starm-clang.cmake.

Recommended extensions:

The views and prerequisites of XRobot.xrobot are described in VS Code Extension.

Toolchain Choice​

Current recommended compiler choices are still:

  • gcc
  • starm-clang

For clangd, CLion or command-line builds, pure gcc or pure starm-clang is recommended; the mixed Hybrid mode is not.

clangd is still not reliable with ST-ARM-CLANG's --multi-lib-config. In Hybrid mode, compile_commands.json often ends up carrying extra arguments that make IDE behavior worse.

With starm-clang, picolibc is the recommended C library. STARM_TOOLCHAIN_CONFIG in starm-clang.cmake accepts STARM_HYBRID, STARM_NEWLIB and STARM_PICOLIBC; STARM_HYBRID is not recommended.

CLion / Command-Line Builds​

For builds from the command line or in CLion, configure the environment as follows.

On Windows, you usually need relevant toolchain paths in PATH. Installing STM32CubeCLT can simplify some of this.

# gcc
$env:PATH += ";$env:LOCALAPPDATA\stm32cube\bundles\gnu-tools-for-stm32\<version>\bin"

# starm-clang
$env:PATH += ";$env:LOCALAPPDATA\stm32cube\bundles\st-arm-clang\<version>\bin"

When STARM_TOOLCHAIN_CONFIG is STARM_HYBRID, starm-clang.cmake also reads these two environment variables:

Windows:

$env:GCC_TOOLCHAIN_ROOT = "$env:LOCALAPPDATA\stm32cube\bundles\gnu-tools-for-stm32\<version>\bin"
$env:CLANG_GCC_CMSIS_COMPILER = "$env:LOCALAPPDATA\stm32cube\bundles\st-arm-clang\<version>"

Linux (the example paths are those of the docker-image-stm32 image, which does not set these two variables; for a local installation use the actual installation directories):

export GCC_TOOLCHAIN_ROOT=/opt/arm-gnu-toolchain-14.2.rel1-x86_64-arm-none-eabi/bin
export CLANG_GCC_CMSIS_COMPILER=/opt/st-arm-clang

Select the toolchain with -DCMAKE_TOOLCHAIN_FILE="cmake/gcc-arm-none-eabi.cmake" or -DCMAKE_TOOLCHAIN_FILE="cmake/starm-clang.cmake". The C library of starm-clang.cmake is set by its set(STARM_TOOLCHAIN_CONFIG ...) line, which overrides -DSTARM_TOOLCHAIN_CONFIG=... on the command line; edit that line, or run libxr stm32 toolchain clang --newlib / --picolibc.

Common Problems​

If the build complains about library ob, add this to the root CMakeLists.txt:

# Remove wrong libob.a library dependency when using cpp files
list(REMOVE_ITEM CMAKE_C_IMPLICIT_LINK_LIBRARIES ob)

Switching toolchains​

With libxr installed, libxr stm32 toolchain switches the toolchain of the default preset of an STM32CubeMX project and the C library of starm-clang, for example:

libxr stm32 toolchain gcc
libxr stm32 toolchain clang --newlib
libxr stm32 toolchain clang --picolibc

The command replaces toolchainFile of the default preset in CMakePresets.json and, when a C library is chosen, rewrites the set(STARM_TOOLCHAIN_CONFIG ...) line in cmake/starm-clang.cmake. When the toolchain changes, it deletes the build/ and cmake-build* directories configured with the old toolchain. Restart VS Code afterwards so the new configuration is picked up.