STM32 development environment with Visual Studio Code and CMake

This tutorial explains steps to effectively develop and debug STM32 application in Visual Studio Code using CMake build generator, Ninja build tool and GCC compiler.

Things you will learn

• How to install and setup all tools
• How to create new STM32 project with STM32CubeMX or STM32CubeIDE tools
• How to install and setup recommended extensions for Visual Studio Code for easier development
• How to setup CMake lists and CMake presets
• How to generate build system for compiler
• How to compile the project with GCC
• How to flash and debug application to the STM32 target

This tutorial is using Windows operating system. Similar procedure will apply for Linux and MAC operating system.

Tools installation

STM32CubeIDE

First step is to install STM32CubeIDE, that will be used to easily start new STM32 project and it comes with integrated STM32CubeMX tool - allowing us graphical configuration.

STM32CubeIDE also provides necessary tools needed later for VSCode development

• ARM none eabi GCC compiler
• ST-LINK GDBServer for debugging
• STM32CubeProgrammer tool for code downloading and respective ST-Link drivers
• Folder with STM32 SVD files
• Drivers for ST-Link

Environmental path setup

3 paths should be added to environmental settings from STM32CubeIDE installation, one path for each of above-mentioned tools. In case of my computer, using STM32CubeIDE 1.8 (updated through eclipse, hence my actual installation path is still showing version 1.0.2) paths are defined as:

• GCC compiler: c:\ST\STM32CubeIDE_1.0.2\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.win32_2.0.0.202105311346\tools\bin\
• ST-Link GDB server: c:\ST\STM32CubeIDE_1.0.2\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.win32_2.0.100.202109301221\tools\bin\
• STM32Cube Programmer CLI: c:\ST\STM32CubeIDE_1.0.2\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.win32_2.0.100.202110141430\tools\bin\

Your paths may differ at version numbers

Verify correct path setup, run:

arm-none-eabi-gcc --version
STM32_Programmer_CLI --version
ST-LINK_gdbserver --version

That should produce output similar to the picture below

CMake

Download and install CMake.

Installation wizard will ask you to add CMake to environmental paths. Select the option or add bin folder of CMake installation folder to environmental path.

Ninja

Download Ninja build system from Github releases page. It comes as portable executable, without need to install anything. However it must be visible at environment level, like all previous tools.

Verify CMake and Ninja installation, run:

cmake --version
ninja --version

Output shall be something similar to

Visual Studio Code

Download and install VSCode. Once installed and opened, window will look similar to the one below.

Visual Studio Code extensions

Visual Studio Code is lightweight text editor with capability to enlarge it using extensions.

List of useful extensions for STM32 development using CMake:

• ms-vscode.cpptools: Syntax highlighting and other core features for C/C++ development
• ms-vscode.cmake-tools: CMake core tools, build system generator tool
• twxs.cmake: CMake color highlighting
• marus25.cortex-debug: Cortex-M debugging extension, mandatory for STM32 debug from VSCode
• dan-c-underwood.arm: ARM Assembly syntax highlighter
• zixuanwang.linkerscript: GCC Linker script syntax highlighter

You can install them by copying below commands in VSCode's internal terminal window.

code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cmake-tools
code --install-extension twxs.cmake
code --install-extension marus25.cortex-debug
code --install-extension dan-c-underwood.arm
code --install-extension zixuanwang.linkerscript

Go to Terminal -> New Terminal to open new terminal window

Alternative way is to use Extension search GUI and manually install from there.

Tools installed - checkpoint

At this point, all the tools are properly installed - you are on the right track towards success.

New project creation

Fundamental requirement to move forward is to have a working project that will be converted to CMake and developed in VSCode. For this purpose, I will guide you through simple new project creation using STM32CubeMX or STM32CubeIDE software tools.

You can skip this part, if you already have your project to work on.

I used STM32CubeIDE tool and STM32H735G-DK board for this demo.

Open STM32CubeIDE and start new project

Select STM32 MCU - I selected STM32H735IG which is used on STM32H735G-DK board

Select project name and path, then create project and wait for Pinout view to open

Our task is to have a simple project that will toggle leds. LEDs are connected to PC2 and PC3 respectively, active LOW. Pins can be configured in output push-pull or open-drain mode

Set pins as outputs with optional labels as LED1 and LED2 respectively

If you are using STM32CubeMX, go to Project manager, set project name and be sure STM32CubeIDE is selected as Toolchain.

Go to advanced settings and select LL as drivers for generated code

We are using LL drivers for the sake of simplicity in this tutorial

Re-generate the project by pressing red button or by saving the project with CTRL + S shortcut

Project is now (re)generated. Yellow highlighted files are sources to build. Blue is linker script.

That's it for the first run, we are ready to compile. Hit CTRL + B or click on hammer icon to start. STM32CubeIDE will compile the project, you should see similar as on picture below. It is now ready for flashing the MCU's flash and start debugging.

This is end of first part, where we successfully created our project. At this point we consider project being ready to be transferred to CMake-based build system.

You can continue your development with STM32CubeIDE in the future, add new sources, modify code, compile, flash the binary and debug directly the microcontroller. This is preferred STM32 development studio, developed and maintained by STMicroelectronics.

CMake configuration

It is expected that project to develop in VSCode has been created. We will move forward for GCC compiler, but others could be used too.

With release of Visual Studio Code, many developers use the tool for many programming languages and fortunately can also develop STM32 applications with single tool. If you are one of developers liking VSCode, most elegant way to move forward is to transfer STM32CubeIDE-based project to CMake, develop code in VSCode and compile with Ninja build system using GCC compiler. It is fast and lightweight.

Development in VSCode is for intermediate or experienced users. I suggest to all STM32 beginners to stay with STM32CubeIDE development toolchain. It will be very easy to move forward and come to VSCode topic later.

Prepare CMakeLists.txt file

Every CMake-based application requires CMakeLists.txt file in the root directory, that describes the project and provides input information for build system generation.

Root CMakeLists.txt file is sometimes called top-level CMake file

Essential things described in CMakeLists.txt file:

• Toolchain information, such as GCC configuration with build flags
• Project name
• Source files to build with compiler, C, C++ or Assembly files
• List of include paths for compiler to find functions, defines, ... (-I)
• Linker script path
• Compilation defines, or sometimes called preprocessor defines (-D)
• Cortex-Mxx and floating point settings for instruction set generation

Open VSCode in project root folder

Visual Studio Code has been installed and will be used as further file editor.

Find your generated project path and open folder with VSCode:

• Option 1: Go to the folder with explorer, then right click and select Open in Code.
• Option 2: Alternatively, open VScode as new empty solution and add folder to it manually. Use File -> Open Folder... to open folder
• Option 3: Go to folder with cmd or powershell tool and run code .

Final result should look similar to the one below

Toolchain information

CMake needs to be aware about Toolchain we would like to use to finally compile the project with. As same toolchain is usually reused among different projects, it is advised to create this part in separate file for easier reuse. These are generic compiler settings and not directly linked to projects itself.

A simple .cmake file can be used and later reused among your various projects. I am using name cmake/gcc-arm-none-eabi.cmake for this tutorial and below is its example:

set(CMAKE_SYSTEM_NAME               Generic)
set(CMAKE_SYSTEM_PROCESSOR          arm)

# Some default GCC settings
# arm-none-eabi- must be part of path environment
set(TOOLCHAIN_PREFIX                arm-none-eabi-)
set(FLAGS                           "-fdata-sections -ffunction-sections --specs=nano.specs -Wl,--gc-sections")
set(CPP_FLAGS                       "-fno-rtti -fno-exceptions -fno-threadsafe-statics")

# Define compiler settings
set(CMAKE_C_COMPILER                ${TOOLCHAIN_PREFIX}gcc ${FLAGS})
set(CMAKE_ASM_COMPILER              ${CMAKE_C_COMPILER})
set(CMAKE_CXX_COMPILER              ${TOOLCHAIN_PREFIX}g++ ${FLAGS} ${CPP_FLAGS})
set(CMAKE_OBJCOPY                   ${TOOLCHAIN_PREFIX}objcopy)
set(CMAKE_SIZE                      ${TOOLCHAIN_PREFIX}size)

set(CMAKE_EXECUTABLE_SUFFIX_ASM     ".elf")
set(CMAKE_EXECUTABLE_SUFFIX_C       ".elf")
set(CMAKE_EXECUTABLE_SUFFIX_CXX     ".elf")

set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)

Create a file in the cmake/ folder of root project directory.

If CMake highlighter plugin is installed, VSCode will nicely highlight CMake commands for you

Toolchain setup is complete. You can freely close the file and move to next step.

Create main CMakeLists.txt file

We need to create main CMakeLists.txt, also called root CMake file.

Make sure you really name it CMakeLists.txt with correct upper and lowercase characters.

I prepared simple template file for you, that can be reused for all of your projects in the future. You will just need to change things like project name, source files, include paths, etc.

```cmake cmake_minimum_required(VERSION 3.22)

Setup compiler settings

set(CMAKE_C_STANDARD 11) set(CMAKE_C_STANDARD_REQUIRED ON) set(CMAKE_C_EXTENSIONS ON) set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS ON) set(PROJ_PATH ${CMAKE_CURRENT_SOURCE_DIR}) message("Build type: " ${CMAKE_BUILD_TYPE})

Core project settings

project(your-project-name) enable_language(C CXX ASM)

Core MCU flags, CPU, instruction set and FPU setup

Needs to be set properly for your MCU

set(CPU_PARAMETERS -mthumb

# This needs attention to properly set for used MCU
-mcpu=cortex-m7
-mfpu=fpv5-d16
-mfloat-abi=hard

)

Set linker script

set(linker_script_SRC ${PROJ_PATH}/path-to-linker-script.ld) set(EXECUTABLE ${CMAKE_PROJECT_NAME})

List of source files to compile

set(sources_SRCS # Put here your source files, one in each line, relative to CMakeLists.txt file location )

Include directories

set(include_path_DIRS # Put here your include dirs, one in each line, relative to CMakeLists.txt file location )

Symbols definition

set(symbols_SYMB # Put here your symbols (preprocessor defines), one in each line # Encapsulate them with double quotes for safety purpose )

Executable files

add_executable(${EXECUTABLE} ${sources_SRCS})

Include paths

target_include_directories(${EXECUTABLE} PRIVATE ${include_path_DIRS})

Project symbols

target_compile_definitions(${EXECUTABLE} PRIVATE ${symbols_SYMB})

Compiler options

target_compile_options(${EXECUTABLE} PRIVATE ${CPU_PARAMETERS} -Wall -Wextra -Wpedantic -Wno-unused-parameter # Full debug configuration -Og -g3 -ggdb )

Linker options

target_link_options(${EXECUTABLE} PRIVATE -T${linker_script_SRC} ${CPU_PARAMETERS} -Wl,-Map=${CMAKE_PROJECT_NAME}.map --specs=nosys.specs -u _printf_float # STDIO float formatting support -Wl,--start-group -lc -lm -lstdc++ -lsupc++ -Wl,--end-group -Wl,--print-memory-usage )

Execute post-build to print size

add_custom_command(TARGET ${EXECUTABLE} POST_BUILD COMMAND ${CMAKE_SIZE} $ )

Convert output to hex and binary

add_custom_command(TARGET ${EXECUTABLE