px-lib  0.8.3 dev
Cross-platform embedded library and documentation for 8/16/32-bit microcontrollers
7.5 How to get started with STM32CubeIDE

1. Introduction

STM32CubeIDE is a free cross-platform Integrated Development Environment (IDE) based on Eclipse CDT to build and debug STM32 microcontroller applications. It includes a GNU GCC build toolchain for C and C++.

Atollic TrueSTUDIO for STM32 is the parent of STM32CubeIDE. It is a mature product with good documentation, video tutorials and discussion forums so if you encounter problems it may also be a good source of info and solutions.

2. Download and Install

HERE is the download page. On the Windows platform, the default installation directory is here:


3. Noteworthy subdirectories

Go ahead and familiarize yourself with the files & folders in the installation directory. Various tools are installed in the "plugins" subdirectory. It follows the standard Java reverse order naming convention (general to specific) which may seem strange and long-winded at first, but there is a method behind the madness.

The GNU C and C++ command-line toolchain (e.g. arm-none-eabi-gcc.exe) is located here:


The Unix tools make.exe and rm.exe are located here:


Documentation is located here:


STMCubeProgrammer (only the command line version) is located here:


4. How to create a Makefile managed C project

The projects in this library can be built on the command-line by using a Makefile script to manage the build process. There are a large number of files and include paths, preprocessor symbol definitions, compiler options, etc. and using a Makefile makes it easier to replicate and maintain the projects. It would be time consuming to add this build info by hand each time a new STM32CubeIDE project is created.

For a gentle introduction to make see 7.2 How to understand and modify Makefiles.

STM32CubeIDE usually manages the build process for you, but it also allows the creation of a Makefile managed C project.

The following steps show how to create a new Makefile managed C project for an existing project in the library. The following example project will be used:


If the project already contains STM32CubeIDE project files, they can be deleted to follow along with the steps outlined below (e.g. delete ".project", ".cproject" and ".settings").

4.1 Use wizard to create a new STM32 project

The project wizard will create new files from a template that may overwrite existing ones.

Rename the existing project directory (e.g. from "gpio" to "gpio_old") and create a new empty directory (e.g. "gpio") where the STM32CubeIDE project will be created.

Start the wizard by creating a new STM32 project:

File > New  Alt+Shift+N > STM32 Project

Specify the target microcontroller (in this example STM32L072RBTx):


Specify the project name and project location (new empty directory). Specify the "Targeted Project Type" as "Empty" and press "Finish":


Use the same project name as used in the Makefile. Edit the Makefile and you will find:

# (1a) Project name
PROJECT = gpio

4.2 Delete wizard generated files & folders and restore original files

This is the wizard generated file & folder structure:

|       language.settings.xml
|       main.c
|       syscalls.c
|       sysmem.c

You only need the ".cproject" and ".project" file and ".settings" folder. Delete the other wizard generated files & folders by selecting the files and folders, right-clicking on the selection and selecting "Delete" (or by pressing the Delete keyboard button):


Copy or move the original files and folders into the new directory (e.g. copy files and folders in "gpio_old" into "gpio"). Refresh the project:


The original files and folders should now be listed under the project:


A common mistake (for me at least) is trying to execute a project related commmand without the project being selected, for example pressing the F5 keyboard button to refresh the project, but the project does not have a light blue background (indicating that it is selected). IDE menu options related to a project may also be unavailable until the project is selected.

4.3 Update project to use the Makefile

Open the project property page by right-clicking on the project and selecting "Properties Alt+Enter":


Select "C/C++ Build", untick "Generate Makefiles Automatically" and change the Build directory to use the root folder where the Makefile is located (remove the "/Debug" part):


Select the "Behaviour" tab, untick "Enable Parallel Build", change the Build command to "build=debug all" and the Clean command to "build=debug clean":


4.4 Create different build configurations

The Makefile supports different builds:

  • make build=debug creates a build suitable for debugging in the "BUILD_DEBUG" output directory.
  • make build=release creates a size optimized build suitable for release in the "BUILD_RELEASE" output directory.
  • make build=release-boot creates a size optimized release build suitable for upload to a bootloader in the "BUILD_RELEASE_BOOT" output directory.

Open the Manage build window:

Project > Build Configurations > Manage ...

Delete the "Release" configuration:


Rename the "Debug" configuration to "BUILD_DEBUG":


Create a new "BUILD_RELEASE" configuration copied from the existing "BUILD_DEBUG" configuration:


Also create a new "BUILD_RELEASE_BOOT" configuration copied from the existing "BUILD_DEBUG" configuration:


Open the project build behavior window again and observe that the configuration name has changed from "Debug" to "BUILD_DEBUG":


Change the configuration to"BUILD_RELEASE" and change the Build command to "build=release all" and the Clean command to "build=release clean":


Change the configuration to"BUILD_RELEASE_BOOT" and change the Build command to "build=release-boot all" and the Clean command to "build=release-boot clean":


4.5 Build the project

You can start the build by clicking on the hammer icon or selecting "Project > Build All Ctrl+B" or pressing the "Ctrl+B" keyboard combo:


The build output will appear in the console window:


Observe that the IDE is executing a make build=debug all command and that the Makefile script is reporting "DEBUG" in the start banner.

4.6 Create a debug configuration

Before debugging can start a debug configuration must exist:

Run > Debug Configurations...

In this case there is already an STM32 MCU Debugging configuration called "gpio build_debug":


If one does not exist, right-click on "STM32 MCU Debugging" and select "New Configuration":


Rename the debug configuration to "gpio.elf BUILD_DEBUG" to make provision for different debug configurations in the future. Observe that the ELF file in the BUILD_DEBUG directory will be used. Change the Build Configuration to "BUILD_DEBUG":


5. Debugging

You can start debugging by clicking on the green bug icon or selecting "Run > Debug F11" or pressing the "F11" keyboard button:


All of the debug commands and keyboard shortcuts can be found in the Run menu:


The SFR (Special Function Register) window is great for inspecting the content of the microcontroller's peripheral registers:


By selecting "Run > Instruction Stepping Mode", the code can be stepped on an assembly level:


The state of the processor core can be inspected in the the Register window: