Code Editor Support#
Pigweed projects can be (and have been!) successfully developed in simple text editors. However, if you want to take advantage of the latest code intelligence tools and IDE features, those can be configured to work great with Pigweed.
We are building the ideal development experience for Pigweed projects using Visual Studio Code, a powerful and highly extensible code editor. However, most of the features described in this doc are available to other popular editors; you may just need to do a little more configuration to make it work.
Quick Start for Contributing to Pigweed#
If you’re developing on upstream Pigweed, you can use Visual Studio Code, which is already configured to work best with Pigweed, or you can use another editor and configure it yourself.
With Visual Studio Code#
There are three quick steps to get started with Pigweed in Visual Studio Code.
Bootstrap your Pigweed environment (if you haven’t already).
gn gen out(if you haven’t already).
pw ide sync
Open the Pigweed repository in Visual Studio Code and install the recommended plugins.
You’re done! Refer to the
pw_ide documentation for
Visual Studio Code for more guidance.
With Other Editors#
There are three short steps to get code intelligence in most editors for C++ and Python, the two most prevalent languages in Pigweed.
Bootstrap your Pigweed environment (if you haven’t already).
Ensure that your Python plugin/language server is configured to use Pigweed’s Python virtual environment, located at
Set up C++ code intelligence by running
pw ide cpp --clangd-commandto generate the
clangdinvocation for your system, and configure your language server to use it.
Quick Start for Setting Up Projects Using Pigweed#
If you’re developing on a downstream project using Pigweed, the instructions for upstream Pigweed may just work out of the box on your project. Give it a try!
If it doesn’t work, here are some common reasons why, and ways you can fix it for your project.
It can’t find any compilation databases#
You need to generate at least one compilation database before running
pw ide sync. Usually you will do this with your
It isn’t working for my toolchain#
Using Visual Studio Code#
If you followed the quick start steps above, you’re already set! 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
Tool tips with docs, inferred types for
auto, inferred values for
constexpr, data type sizes, etc.
Compiler errors and warnings
Code navigation and code completion
Tool tips with docs
Errors, warnings, and linting feedback
When launching the integrated terminal, it will automatically activate the Pigweed environment within that shell session.
See the pw_ide docs.
Code Intelligence Features for Specific Languages#
Pigweed projects have a few characteristics that make it challenging for some IDEs and language servers to support C/C++ code intelligence out of the box:
Pigweed projects generally don’t use the default host toolchain.
Pigweed projects usually use multiple toolchains for separate targets.
Pigweed projects rely on the build system to define the relationship between facades and backends for each target.
We’ve found that the best solution is to use the clangd language server or alternative language servers that use the same compilation database format and comply with the language server protocol. We supplement that with Pigweed tools to produce target-specific compilation databases that work well with the language servers.
Producing a Compilation Database#
If you’re using GN, then
gn gen out --export-compile-commands will output
a compilation database (
compile_commands.json) in the
along with all of the other GN build outputs (in other words, it produces the
same output as
gn gen out but additionally produces the compilation
If you’re using CMake, you can enable the
option to ensure a compilation database (
compile_commands.json) is produced.
This can be done either in your project’s
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)), or by setting the flag when
invoking CMake (i.e.
Bazel does not natively support generating compilation databases right now, though you may find third party extensions that provide this functionality.
Processing the Compilation Database#
If you examine a
compile_commands.json file produced GN, you’ll observe
It contains multiple commands for each file, i.e.
foo.ccwill have compile commands for multiple
clanghost builds, multiple
gcchost builds, multiple
gcc-arm-none-eabidevice builds, etc.
It contains many commands that are not actually valid compile commands, because they involve targets that use Pigweed Python wrappers to do various static analyses.
Both of these confound
clangd and will produce broken, unexpected, or
inconsistent results when used for code intelligence. So the
pw_ide module provides CLI tools that process the “raw”
compilation database produced by the build system into one or more “clean”
compilation databases that will work smoothly with
Once you have a compilation database, run this command to process it:
pw ide cpp --process <path to compilation database>
Or better yet, just let
pw_ide find any compilation databases you have
in your build and process them:
pw ide cpp --process
compile_commands.json file did not come from GN, it may not
exhibit any of these problems and therefore not require any processing.
Nonetheless, you can still run
pw ide cpp --process;
determine if the file needs processing or not.
How often do we need to process the compilation database? With GN, if you’re just editing existing files, there’s no need to reprocess the compilation database. But any time the build changes (e.g. adding new source files or new targets), you will need to reprocess the compilation database.
With CMake, it is usually not necessary to reprocess compilation databases,
pw_ide will automatically pick up any changes that CMake makes.
Setting the Target to Use for Analysis#
Discover which targets are available for code analysis:
$ pw ide cpp --list
C/C++ targets available for language server analysis:
Select the target you want to use for code analysis:
$ pw ide cpp --set pw_strict_host_gcc_debug
Set C/C++ langauge server analysis target to: pw_strict_host_gcc_debug
Check which target is currently used for code analysis:
$ pw ide cpp
Current C/C++ language server analysis target: pw_strict_host_gcc_debug
Your target selection will remain stable even after reprocessing the compilation database. Your editor configuration also remains stable; you don’t need to change the editor configuration to change the target you’re analyzing.