STM32CubeIDE for Visual Studio Code Documentation

Table Of Contents

- STM32CubeIDE for Visual Studio Code
- Introduction
  - Overview
  - System requirements
  - Release note
- Basic Concepts
  - User interface
  - Command-line tools
  - Visual Studio Code extension packs
  - Bundles
  - CMake
  - Toolchains
  - STMicroelectronics Arm Clang Toolchain for STM32
- Getting Started
  - Installation
  - First project creation
- Workspace and extension workflow
  - Workspace overview
  - Extension commands
  - Project files
  - Multi-project workspaces
- Tutorials
  - Migrating from STM32CubeIDE for Visual Studio Code extension 2.x to 3.x
  - Dual-core STM32 projects
  - Power management
  - RTOS-based STM32 projects
  - Firmware security and integrity
- Development
  - Projects
  - Editing
  - Build
  - Debug
  - API manual
  - Integration with external tools
  - Testing and validation
- Troubleshooting
  - Frequently asked questions
  - Known issues
  - Support

### On this page

- Important file groups
- STM32CubeMX configuration
- CMake project files
- Visual Studio Code configuration
- Build output
- Recommended edit boundaries

# Project files

STM32CubeIDE for Visual Studio Code uses project files from STM32 tools, CMake, and Visual Studio Code. Understanding the role of each file helps developers know where to configure the project and which files are generated.

The same workspace can contain files with different owners. Some files come from STM32CubeMX, some files describe the build system, and some files are local editor configuration. Knowing the owner of a file helps prevent edits that are lost during regeneration.

## Important file groups

An STM32 workspace commonly contains these file groups:

- STM32CubeMX configuration files, such as `.ioc` files

- Application source files, headers, startup files, and linker scripts

- CMake files and CMake preset files

- Visual Studio Code files in the `.vscode` folder

- Build output folders, such as `build` or configuration-specific output folders

The exact layout depends on how the project was created, imported, or generated.

Most project folders also contain documentation, scripts, or application-specific assets. These files are part of the product workflow but are not necessarily interpreted by STM32CubeIDE for Visual Studio Code.

## STM32CubeMX configuration

The STM32CubeMX configuration stores the selected device or board, clock configuration, peripheral settings, middleware selections, and code generation options. STM32CubeIDE for Visual Studio Code can use this information when importing or discovering a project.

When STM32CubeMX regenerates code, review the changed files before committing. Regeneration can update startup files, initialization code, middleware configuration, and build files.

Use STM32CubeMX as the main source for hardware and middleware configuration. If a generated source file needs application code, place the code in the user sections provided by the generator when they are available.

## CMake project files

CMake files define how the project builds. They describe source files, include paths, compile definitions, linker inputs, and build targets.

CMake preset files define named configure and build contexts. In Visual Studio Code, selecting a preset tells the CMake extension and STM32CubeIDE workflow which build configuration to use.

The preset name usually reflects the intended build mode, such as Debug or Release. A Debug preset typically keeps debug symbols and lower optimization, while a Release preset usually enables stronger optimization and produces a smaller or faster image.

For CMake concepts, see CMake.

## Visual Studio Code configuration

The `.vscode` folder can contain project-specific configuration files:

- `settings.json` for workspace settings

- `tasks.json` for build, test, or utility tasks

- `launch.json` for debug launch configurations

- `extensions.json` for recommended extensions

Version-control these files when they define the shared team workflow. Keep user-specific values, local paths, and temporary experiments out of shared configuration files.

For example, a shared `launch.json` can define the standard debug probe and executable path for the team. A user-specific setting, such as a local tool path, is better kept in user settings or documented as a setup requirement.

## Build output

Build output folders contain generated files such as object files, executable files, map files, and logs. These files depend on the selected preset and target.

Do not edit build output files manually. If an output is incorrect, change the project configuration or source files, then rebuild.

Build output is useful for diagnosis. The `.elf` file contains symbols for debugging, the `.map` file helps analyze memory usage, and build logs help identify compiler or linker errors.

## Recommended edit boundaries

Use these rules when editing project files:

- Edit application source files and headers directly

- Edit `.vscode` configuration files when the team workflow requires it

- Edit CMake files only when the project build model requires a manual change

- Edit STM32CubeMX settings in STM32CubeMX, then regenerate code

- Avoid manual edits in generated sections that the tools can overwrite

Before committing, inspect the changed files and confirm that generated changes match the intended project update.

A clean commit usually separates source changes, generated configuration changes, and local environment changes. This separation makes code review easier and helps other developers reproduce the same project state.