CMake and VS Code Project Files#

This section describes the generated and user-facing files used in Simplicity Studio CMake-based projects and how they interact with Visual Studio (VS) Code, CMake, and the Silicon Labs tooling ecosystem. Understanding the purpose of these files helps teams manage projects correctly, avoid losing custom changes during regeneration, and maintain projects under source control.

Overview#

CMake-based VS Code projects use a combination of generated CMake files, project configuration files, toolchain files, and optional VS Code configuration files.

A typical project structure may look like this:

<project-root>/
├─ app.c
├─ app.h
├─ main.c
├─ config/
├─ autogen/
├─ .vscode/
│  └─ c_cpp_properties.json
├─ cmake_gcc/
│  ├─ CMakeLists.txt
│  ├─ CMakePresets.json
│  ├─ toolchain.cmake
│  └─ <project-name>.cmake
└─ <project-name>.slcp

File Descriptions#

CMakeLists.txt File#

The CMakeLists.txt file is the primary build configuration file used by CMake.

Responsibilities#

  • Defines project targets.

  • Specifies source files included in the build.

  • Defines compiler options, include paths, and build settings.

  • References generated project content.

Generated or User-Edited?#

Generated initially, but intended to be user-modifiable.

The CMakeLists.txt file is special in that users can—and should—make additions for source files, symbols, and settings they add to the project. If users make such changes, the file should be placed under source control.

By default, include paths, symbols, and compiler flags are applied only to added source files, not to the original project source files or software development kit (SDK) files.

If these settings need to apply to the original project source files in the project root or to SDK files, use a text editor to add them to the project’s .slcp file. They will then be included in the <project-name>.cmake file.

Interaction with Build System#

CMake uses this file as the entry point when configuring the project. Changes made here directly affect project compilation.

When to Modify#

Modify this file when:

  • Adding custom source files.

  • Adding custom include directories.

  • Adding compiler definitions.

  • Adding custom build options.

Avoid modifying generated sections that project regeneration might overwrite.

Source Control Recommendation#

If custom changes are made, place this file under source control.

project-name.cmake File#

The <project-name>.cmake file contains project-specific information generated from the project configuration.

Responsibilities#

  • Defines generated source files.

  • Provides component-generated build settings.

  • Contains information derived from the .slcp project configuration.

Generated or User-Edited?#

Generated by project generation tools.

Avoid modifying generated sections unless you fully understand the impact. If a section is regenerated by the project generation tools, manual edits may be overwritten during project regeneration or upgrade.

Interaction with Build System#

  • Included by CMakeLists.txt during project configuration.

  • Acts as the bridge between the Project Configurator and the CMake build system.

When to Modify#

Do not manually modify this file.

Make any required changes through:

  • Project Configurator

  • Component configuration tools

  • .slcp configuration

Manual modifications may be lost during regeneration.

Source Control Recommendation#

This file should generally not be placed under source control because it is regenerated during project generation.

CMakePresets.json File#

The CMakePresets.json file defines standardized CMake configure and build presets.

Responsibilities#

  • Defines build configurations.

  • Defines generator settings.

  • Defines build directories.

  • Provides consistent build commands across development environments.

Generated or User-Edited?#

Generated by project generation tools.

Interaction with Build System#

  • Consumed directly by CMake and supported by VS Code CMake extensions.

  • Provides a consistent build experience across development environments and continuous integration (CI) systems.

When to Modify#

Typically, no manual modification is required. Project regeneration may overwrite changes.

Source Control Recommendation#

This file should generally not be placed under source control because it is regenerated during project generation.

toolchain.cmake File#

The toolchain.cmake file defines compiler and build tool locations.

Responsibilities#

  • Locates GCC tools.

  • Locates Ninja.

  • Configures toolchain-specific settings.

  • Defines compiler behavior used during CMake configuration.

Generated or User-Edited?#

The toolchain.cmake file is special because the project generator does not update it after creation. As a result, it is safe to modify.

This file plays an important role in maintaining portability across developers, computers, and operating systems. For maximum portability, all users should add the slt command-line tool to their system path.

When slt is available on the system path, it is used to locate the tool paths referenced in this file. For more information about the location of slt, see Useful Paths.

If slt is not available on the system path, users can define the environment variables ARM_GCC_DIR, POST_BUILD_EXE, and NINJA_EXE_PATH to maintain portability.

Starting with the Simplicity Studio 6.1 release, the generated toolchain.cmake file is portable across users on the same operating system because it uses environment variables to locate tools. As an alternative, users working across different operating systems can merge their toolchain.cmake files to achieve portability across all supported operating systems.

Interaction with Build System#

  • Loaded by CMake before project configuration.

  • Determines which compiler and build tools are used.

Because CMake caches compiler and toolchain information, changing this file after configuration may require cleaning or deleting the build directory and then reconfiguring the project.

When to Modify#

Modify only when:

  • Using a custom compiler installation.

  • Using a custom build tool installation.

  • Adding platform-specific toolchain behavior.

Source Control Recommendation#

Safe to place under source control.

c_cpp_properties.json File#

The c_cpp_properties.json file is a VS Code C/C++ extension configuration file. It is used by VS Code to provide editor features such as code navigation, symbol browsing, and include-path awareness.

This file helps VS Code understand the project structure, available header files, compiler definitions, and the compile commands database.

This file does not define the actual build.

Responsibilities#

Provides VS Code with information about:

  • Project include paths

  • Preprocessor definitions

  • The location of the CMake compile_commands.json file

  • SDK, device, board, CMSIS, and generated header locations

Generated or User-Edited?#

This file is generated or updated by the project generation tools or VS Code extensions.

You typically do not need to edit this file manually. Manual edits may be overwritten if the project is regenerated or if an extension updates the configuration.

Interaction with Build System#

The file points VS Code to project include paths, defines, and the CMake compile commands database.

When to Modify#

Modify only when:

  • Temporarily troubleshooting VS Code IntelliSense behavior.

  • Pointing VS Code to the correct generated compile_commands.json file.

Source Control Recommendation#

This file should generally not be placed under source control.

launch.json File#

The launch.json file defines debug configurations used by VS Code.

Responsibilities#

  • Defines how applications are launched for debugging.

  • Specifies the executable to run.

  • Configures debugger settings and startup behavior.

  • Defines arguments, environment variables, and working directories used during debugging.

Generated or User-Edited?#

Intended to be user-modifiable.

The launch.json file resides in the .vscode folder in the project's root directory.

For simple applications, VS Code typically runs and debugs the currently active file. For more complex applications or debugging scenarios, you can create a launch.json file to define the debugger configuration. For more information, see Visual Studio Code debug configuration.

You can customize debug configurations to match your development workflow, such as changing the executable path, adding command-line arguments, or modifying debugger settings. These changes are generally preserved across normal development activities.

Interaction with Build System#

This file is not used by CMake during project configuration or compilation.

Instead, VS Code uses it when starting a debug session. The configuration often references build artifacts generated by CMake, such as the application executable.

When to Modify#

Modify this file when:

  • Changing debugger settings.

  • Adding command-line arguments.

  • Changing the executable being debugged.

  • Configuring environment variables for debugging.

  • Adding additional debug configurations.

Avoid modifying settings that are automatically managed by project generation tools unless customization is required.

Source Control Recommendation#

If the project uses a common debugging configuration shared by the development team, place this file under source control.

tasks.json File#

The tasks.json file defines tasks that can be executed from within VS Code.

Responsibilities#

  • Defines build, clean, flash, and other development tasks.

  • Integrates external tools with the VS Code task system.

  • Provides commands that can be executed from the Command Palette or Terminal menu.

  • Supports task automation and workflow customization.

Generated or User-Edited?#

Intended to be user-modifiable.

The tasks.json file resides in the .vscode folder in the project's root directory.

VS Code uses this file to define tasks that can be executed from the Command Palette, Terminal menu, or keyboard shortcuts. Tasks are commonly used to build, clean, flash, or otherwise automate project-related actions.

For simple projects, VS Code may provide basic task functionality without a tasks.json file. For more advanced workflows, you can create a tasks.json file to define custom tasks and integrate external tools. For more information, see Visual Studio Code Tasks.

You can customize task definitions to match your development workflow, such as adding custom commands, modifying task arguments, integrating external tools, or automating repetitive actions. These changes are generally preserved across normal development activities.

Interaction with Build System#

This file does not directly participate in the CMake build process.

Instead, it provides convenient shortcuts for invoking build-related commands, such as CMake configure, build, flash, or other project management operations. Tasks can invoke CMake or other command-line tools behind the scenes.

When to Modify#

Modify this file when:

  • Adding custom build or flash tasks.

  • Integrating external tools into the workflow.

  • Automating repetitive development tasks.

  • Customizing task execution parameters.

Avoid modifying generated task definitions unless customization is required, as regeneration may overwrite certain sections.

Source Control Recommendation#

If custom tasks are added or existing tasks are modified for team-wide workflows, place this file under source control.