Visual Studio Code#

pw_ide: Code editor and IDE support for Pigweed projects

Pigweed provides rich and robust support for development in Visual Studio Code, including:

High-quality C/C++ code intelligence for embedded systems projects using clangd integrated directly with your project’s Bazel build graph
Bundled core Bazel tools, letting you get started immediately without the need to install global system dependencies
Interactive browsing, building, and running Bazel targets

Note

Currently, this document only applies to Bazel projects. We’re working on adding support for bootstrap projects. In the meantime, bootstrap projects can use the command-line interface with the legacy support for Visual Studio Code.

Getting started#

All you need to do is install the Pigweed extension from the extension marketplace. If you start your project from one of Pigweed’s quickstart or showcase example projects, you will be prompted to install the extension as soon as you open the project.

Once installed, the Pigweed extension will do a few things for you automatically when you open Pigweed projects:

The Bazel extension will discover all of the targets in your project
The Pigweed extension will generate compilation databases for the target groups in your project.

You can now select a target group from the status bar item at the bottom of your window or by running the Pigweed: Select Code Analysis Target command.

Once you select a target group, the clangd extension will be automatically configured to use the clang toolchain in the Bazel environment and the compilation database associated with the selected target group.

What this gives you#

Here’s a non-exhaustive list of cool features you can now enjoy:

Code navigation, including routing through facades to the correct backend
Code completion, including correct class members and function signatures
Tooltips with docs, inferred types for auto, inferred values for constexpr, data type sizes, etc.
Compiler errors and warnings as you write your code
Code formatting via the standard Format ... commands, including Starlark files
Linting and debugging for Starlark files
A tree view of all Bazel targets, allowing you to build or run them directly

Code intelligence#

Learn more about using and configuring code intelligence here.

Project settings#

Pigweed manipulates some editor and clangd settings to support features like the ones described above. For example, when you select a code analysis target, Pigweed sets the clangd extensions settings in .vscode/settings.json to configure clangd to use the selected target. Likewise, when using the feature to disable code intelligence for source files not in the target’s build graph, Pigweed will manipulate the .clangd configuration file.

These files shouldn’t be committed to the project repository, because they contain state that is specific to what an individual developer is working on. Nonetheless, most projects will want to commit certain shared settings to their repository to help create a more consistent development environment.

Pigweed provides a mechanism to achieve that through additional settings files.

Visual Studio Code settings#

The .vscode/settings.json file should be excluded from source control. Instead, add your shared project settings to .vscode/settings.shared.json and commit that file to source control.

The Pigweed extension watches the shared settings file and automatically applies those settings to you local settings file. So shared project settings can be committed to .vscode/settings.shared.json, and your current editor state, as well as your personal configuration preferences, can be stored in .vscode/settings.json.

The automatic sync process will respect any settings you have in your personal settings file. In other words, if a conflicting setting appears in the shared settings file, the automatic sync will not override your personal setting.

At some point, you may wish to fully synchronize with the shared settings, overriding any conflicting settings you may already have in your personal settings file. You can accomplish that by running the settings sync command.

`clangd` settings#

Additional configuration for clangd can be stored in .clangd.shared, following the YAML configuration format. The Pigweed extension watches this file and automatically applies its settings to a .clangd file that should not be committed to source control. That file will also be used to configure clangd in ways that are specific to your selected analysis target and the state of your code tree.

Commands#

Access commands by opening the command palette Ctrl+Shift+P (Cmd+Shift+P on Mac).

Pigweed: Check Extensions: The Pigweed extension lets development teams maintain a consistent development environment for all members of the team by ensuring that the recommendations in extensions.json are enforced. Learn more at extension enforcement.

Pigweed: File Bug: Found a problem in the Pigweed Visual Studio Code extension, other Pigweed tools, or Pigweed itself? Add a bug to our bug tracker to help us fix it.

Pigweed: Sync Settings: Pigweed automatically syncronizes shared Visual Studio Code settings from .vscode/settings.shared.json to .vscode/settings.json, but in the case of conflicts, the automatic process will preserve the value in .vscode/settings.json. If you want to do a full sync of the shared settings to your personal settings, including overriding conflicting values, run this command.

Pigweed: Open Output Panel: Opens the Pigweed output panel, which contains diagnostic output generated by the Pigweed extension. This is a good first place to look if things go wrong.

Pigweed: Refresh Compile Commands: Manually trigger a refresh of the compilation databases used for C/C++ code intelligence. Normally, the databases are refreshed automatically when build files are changed, but if you have automatic refreshing disabled or need to refresh outside of the automatic cycle, this command will refresh manually.

Pigweed: Refresh Compile Commands and Set Code Analysis Target: This is the same as the Pigweed: Refresh Compile Commands, except that it also triggers Pigweed: Select Code Analysis Target after the refresh is complete.

Pigweed: Select Code Analysis Target: Select the target group that clangd should use for code analysis.

Tip

You might notice that the currently-selected code analysis target is stored in the pigweed.codeAnalysisTarget setting. If you edit this value manually, don’t worry! The Pigweed extension will immediately do everything it would have done if you had run this command.

Pigweed: Disable Inactive File Code Intelligence: See the associated setting.

Pigweed: Enable Inactive File Code Intelligence: See the associated setting.

Pigweed: Set Bazel Recommended Settings

Configure Visual Studio Code to use Pigweed’s recommended Bazel settings. Note that these settings are only applied to the project settings, so they don’t affect any other project’s settings, or your user settings.

Sets the Buildifier path to the version bundled with the Pigweed extension, enabling Starlark code intelligence
Enables Bazel CodeLens support, allowing you to build and run targets directly from Bazel files

Pigweed: Set Bazelisk Path: Pigweed recommends using Bazelisk instead of plain Bazel to ensure that the right version of Bazel is used. This command allows you to set the path to Bazelisk, selecting from versions installed on your system or the version bundled with the Pigweed extension.

Pigweed: Activate Bazelisk in Terminal: This will change the $PATH of your active integrated terminal to include the path to Bazelisk configured in your editor settings. This allows you to run Bazel actions via Visual Studio Code commands or via bazelisk … invocations in the integrated terminal, while working in the same Bazel environment.

Configuration options#

pigweed.activateBazeliskInNewTerminals: boolean = true#: When enabled, the path to Bazelisk will be added to the integrated terminal when launched

pigweed.codeAnalysisTarget: string#: The build target to use for editor code intelligence

Warning

You should only set this value by running the Pigweed: Select Code Analysis Target. The command has other configuration side-effects that won’t be triggered if you manually set the value in settings.json.

pigweed.disableBazelSettingsRecommendation: boolean = false#: Disable reminders to use Pigweed’s Bazel settings recommendations

pigweed.disableBazeliskCheck: boolean = false#: Disable the recommendation to use Bazelisk

pigweed.disableCompileCommandsFileWatcher: boolean = false#: Disable automatically refreshing compile commands

pigweed.disableInactiveFileCodeIntelligence: boolean = true#

When you select a target for code analysis, some source files in the project may not appear in the compilation database for that target because they are not part of the build graph for the target. By default, clangd will attempt to provide code intelligence for those files anyway by inferring compile commands from similar files in the build graph, but this code intelligence is incorrect and meaningless, as the file won’t actually be compiled for that target.

Enabling this option will configure clangd to suppress all diagnostics for any source files that are not part of the build graph for the currently selected target.

pigweed.enforceExtensionRecommendations: boolean = false#: Require installing and disabling extensions recommended in extensions.json

pigweed.hideInactiveFileIndicators: boolean = false#: When code intelligence is enabled for all files, hide indicators for inactive and orphaned files. Note that changing this setting requires you to reload Visual Studio Code to take effect.

pigweed.preserveBazelPath: boolean = false#: When enabled, this extension won’t override the specified Bazel path under any circumstances.

pigweed.projectRoot: string#: The root of the Pigweed project source directory

pigweed.projectType: bootstrap or bazel#: The type of Pigweed project, either bootstrap or Bazel

pigweed.refreshCompileCommandsTarget: string = //:refresh_compile_commands#: The Bazel target to run to refresh compile commands