Your first project

This walkthrough clones a ready-made example project, installs its pinned toolchain, and builds it, with no board required. By the end, you’ll have used cube to reproduce someone else’s exact toolchain on your machine and build real STM32 firmware from it, without installing or configuring a compiler yourself.

Before you start

Install STM32CubeCLI by following the installation guide, then check that the cube command is available: 

cube --version

Note

Already using STM32CubeIDE for VS Code with a project that has .settings/bundles.store.json committed? Run cube bundle install --project from the project’s root — that’s the whole tutorial for you. The rest of this page walks through cloning and building an example project from scratch.

1. Getting the example project

Clone the tutorial repository: 

git clone https://github.com/stm32-hotspot/STM32CubeCLI-basic-tutorial.git

Then change into the project directory: 

cd STM32CubeCLI-basic-tutorial

The project targets an STM32F407VGTx as a custom target, generated by STM32CubeMX with CMake presets. Its top-level layout looks like this: 

STM32CubeCLI-basic-tutorial/
├── .settings/
│   ├── bundles.store.json
│   └── bundles-lock.store.json
├── Core/
├── Drivers/
├── cmake/
├── CMakeLists.txt
├── CMakePresets.json
├── startup_stm32f407xx.s
├── STM32F407xx_FLASH.ld
└── ...

The cloned project already pins its toolchain — bundles.store.json and bundles-lock.store.json are committed, so the exact same versions resolve on any machine. See Working with a project for the explanation of what these files contain.

2. Installing the pinned toolchain

Run the following command to install the pinned toolchain: 

cube bundle install --project

This reads the project’s lock data and installs the exact bundle versions it requires — CMake, Ninja, the GNU Tools for STM32, and clangd support for editor tooling — without you installing or configuring any of them yourself. The project dependencies can be found in .settings/bundles.store.json: 

{
  "bundles": [
    {
      "name": "cmake",
      "version": "4.3.1+st.1"
    },
    {
      "name": "ninja",
      "version": "1.13.2+st.1"
    },
    {
      "name": "gnu-tools-for-stm32",
      "version": "14.3.1+st.2"
    },
    {
      "name": "st-arm-clangd",
      "version": "21.1.0+st.2"
    }
  ]
}

To view all the bundles used by the project, run: 

cube bundle list --project

3. Building the project

Configure the Debug preset: 

cube cmake --preset Debug

Then build it: 

cube cmake --build --preset Debug

A successful build produces a firmware image in build/Debug/: 

STM32CubeCLI-basic-tutorial/
├── .settings/
├── build/
│   └── Debug/
│       ├── STM32CubeCLI-basic-tutorial.elf
│       └── ...
├── Core/
├── Drivers/
├── cmake/
├── CMakeLists.txt
├── CMakePresets.json
└── ...

The commands above used cube to install the required toolchain and build tools automatically and then use them to build the project. Anyone who clones this project runs the same commands and gets the same toolchain, producing the same firmware image, on any machine.

From here, two natural next steps: running this same install-and-build sequence inside a CI pipeline instead of on your machine, or packaging your own tools as a bundle so others can pin them the same way. Documentation for both is coming; in the meantime, the pages below cover what’s already available.

Where to go next