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

- Common use cases
- Context selection
- Workspace file
- Recommended layout
- Build and debug order
- Recommended practices

# Multi-project workspaces

Visual Studio Code can open several folders in one workspace. STM32CubeIDE for Visual Studio Code uses this capability for projects that must be developed together, such as dual-core applications, related examples, or firmware and test projects.

Use a multi-project workspace only when the projects have a practical relationship. For unrelated projects, separate Visual Studio Code windows reduce context mistakes.

A multi-project workspace is a coordination tool. It does not merge the projects into one build system unless tasks, CMake files, or scripts explicitly do that work.

## Common use cases

Multi-project workspaces are useful for these cases:

- Dual-core applications with one project for each core

- A bootloader project and an application project

- A firmware project and a test or validation project

- Several examples used to compare board or middleware behavior

The workspace keeps the related folders visible together and lets Visual Studio Code store the group in a `.code-workspace` file.

This arrangement is useful when developers must inspect shared headers, compare generated files, or run build and debug commands across related targets during the same session.

## Context selection

In a multi-project workspace, always verify which project receives the command. Build, debug, discovery, and setup commands can use the currently selected folder, preset, or launch configuration.

The active editor tab is not always enough to identify the command target. Some commands use the selected folder in the Explorer view, while others use the active CMake project or selected debug configuration.

Before running a project command, check these items:

- Active folder in the Explorer view

- Selected project in the CMake view

- Selected CMake configure preset

- Selected build target

- Selected debug launch configuration

This check prevents building or flashing the wrong STM32 target.

If the workspace includes several connected boards, use clear launch configuration names that include the board or core name. Clear names make the debug selection safer during repeated test cycles.

## Workspace file

A `.code-workspace` file stores the folders that belong to a workspace. It can also store workspace-level settings that apply to all folders in the group.

Use workspace-level settings for shared behavior across the group. Use folder-level `.vscode` files when a setting belongs to only one project.

Store the workspace file near the related project folders when the relationship is part of the product structure. This placement makes the workspace discoverable for new developers and for source-control review.

## Recommended layout

Use a simple folder layout for related projects:

    product_workspace.code-workspace
    bootloader/
    application/
    validation/

Each project folder should keep its own build and debug configuration unless the workflow requires a shared task.

This layout keeps outputs separated and makes it easier to clean, rebuild, or debug one project without changing the other projects.

## Build and debug order

Some multi-project workspaces require an explicit order. For example, a bootloader can require a completed application image before packaging, or a dual-core project can require both core images before flashing.

Document the required order in workspace tasks or project documentation. If a task builds several projects, give the task a clear name and verify that it uses the correct folder for each command.

For ordered workflows, prefer explicit tasks over manual memory. A named task such as `Build bootloader and application` is easier to repeat and easier to review than a sequence of undocumented commands.

## Recommended practices

Apply these practices for multi-project workspaces:

- Keep unrelated projects in separate Visual Studio Code windows

- Use clear folder names that match the hardware or firmware role

- Store reusable workspace groups in `.code-workspace` files

- Confirm the selected preset and launch configuration before flashing

- Keep generated build folders separate for each project

For dual-core project guidance, see Dual-core STM32 projects.