How to build and run

This user journey describes how to build and run STM32Cube Software Examples on the STM32 development boards and Discovery kits.

Prerequisite

Get an example project on the local disk by using one of the delivery channels described in the How to get STM32Cube Software Examples? section.

This page assumes that the example project is downloaded from the STM32 Example Library.

To build and run the example projects from the STM32Cube MCU Package, refer to the STM32Cube MCU package documentation for the selected STM32 series.

Note

Replace the element names in brackets ( [ ]) with the actual names of the elements in use.

Step 1: Open the IDE project

First, ensure that Visual Studio Code and the STM32CubeIDE for Visual Studio Code extension are installed on your machine. Refer to the STM32CubeIDE for Visual Studio Code documentation for more details about how to get and install this extension.

To import your cmake project, click on the Open Folder button from the file menu bar and select the root folder of your example project (where the CMakeLists.txt file is located).

Note

For more information about the project structure and code organization, refer to the How to read an example section. To go further and understand the architecture of an example, refer to the Example architecture section.

Step 2: Configure the project

Once the CMake project is open, the STM32Cube for VS Code extension recognizes it. When the pop-up Would you like to configure discovered CMake project(s) as STM32CubeIDE project(s)? is displayed, click Yes. A configuration window appears if the settings are not automatically detected. In this window, select the board or device and the toolchain, then press Configure. The project is configured and ready for build [3].

Important

The CMake projects are delivered with two build profiles: Debug and Release. You can switch between the Debug and Release profiles from the CMake configuration window ( PROJECT STATUS>Configure). The most demanding examples might not run in Debug mode due to the reduced optimization level. Switch to the Release profile to run the example. See Debug build profile for more information.

IDE-managed switches:

  • By default, PRINTF logs are disabled. In order to enable PRINTF logs, set the defined symbol USE_TRACE to 1 in the profile options in the file cmake/flags.cmake.

  • In the same file (cmake/flags.cmake), you can adjust the other compiler switches specific to your example project if exist.

  • Additionaly, some specific compiler switches can be set from the user_modifiable/Pre_Include_Global.h file.

  • See Compiler switches for more information about the compiler switches.

Example: 

target_compile_definitions(${CMAKE_PROJECT_NAME} PUBLIC USE_TRACE=1 STM32C562xx _RTE_)

Linker script edition:

  • You can edit the .ld GNU linker script of the project located under project/user_modifiable/Device/ to change:

    • Flash and RAM sizes

    • Memory region placement (CODE, DATA, BSS, HEAP, STACK)

    • Special sections (such as DMA buffers, shared memory)

Note

The USE_TRACE define has some effect only if the example project implements console logs. See Using the console for more information about this feature.

Note

For more information about how to configure the projects, refer to the How to configure an example section.

Step 3: Build the project

From the activity bar, click on the CMake icon. In PROJECT STATUS section, under Build, select your build profile. Then click on the Build button to build the project.

The build output is displayed in the OUTPUT tab of the terminal panel.

Step 4: Flash and run the project

This possibility is not available yet in the STM32CubeIDE for Visual Studio Code extension. Use the step-by-step debugging method described in Step 5: Step-by-step debugging to flash and run the project.

Note

Refer to the README file of the example project for more details about the expected behavior of the example once it is running on the target. See README for more information about the content of the README files. See User interactions for more information about how to interact with the example once it is running on the target.

Step 5: Step-by-step debugging

From the activity bar, click on the Run and Debug icon. In the Run and Debug view, click on the Run and Debug button and select STM32Cube: STM32 Launch STLink GDB server.

When starting a new debug session, the startup might fail because the debugger firmware needs to be updated. To do so, select the STLINK debug device under the STM32CUBE DEVICES AND BOARDS section. Click the Upgrade STLINK firmware button to update the firmware. Then, launch the debug session again.

Important

The release profile does not enable the debug symbols ( -g3). Therefore the debugger cannot display the source code and variables content, and you cannot set breakpoints in the source code. Switch to the debug profile to be able to debug the application and use all the debugging features such as breakpoints, variable inspection, and stepping through the code.

If you must debug the application in the release profile, you can edit the cmake/flags.cmake file to add the -g3 switch to the target_compile_options of the release profile.

Example: 

target_compile_options(${CMAKE_PROJECT_NAME} PUBLIC "SHELL:-g3 -Os -fdata-sections -ffunction-sections -std=gnu11 -Wall -fstack-usage --specs=nano.specs --specs=nosys.specs -Werror=implicit-function-declaration ${CC_SECURE}")

Note

For more details about how to use the examples in debug mode, refer to the How to debug an example section.