• Home
    • /
  • Code Editor Support

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.

  1. Bootstrap your Pigweed environment (if you haven’t already).

  2. Run gn gen out (if you haven’t already).

  3. Run pw ide sync

  4. 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.

  1. Bootstrap your Pigweed environment (if you haven’t already).

  2. Ensure that your Python plugin/language server is configured to use Pigweed’s Python virtual environment, located at $PW_PROJECT_ROOT/environment/pigweed-venv.

  3. Set up C++ code intelligence by running pw ide cpp --clangd-command to generate the clangd invocation 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 build system.

It isn’t working for my toolchain#

You may need to specify additional query drivers to allow clangd to use your toolchains. Refer to the pw_ide documentation for information on configuring this.

Using Visual Studio Code#

Code Intelligence#

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:

  • C/C++

    • 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

  • Python

    • Code navigation and code completion

    • Tool tips with docs

    • Errors, warnings, and linting feedback

Integrated Terminal#

When launching the integrated terminal, it will automatically activate the Pigweed environment within that shell session.

Configuration#

See the pw_ide docs.

Code Intelligence Features for Specific Languages#

C/C++#

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 out directory 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 database).

If you’re using CMake, you can enable the CMAKE_EXPORT_COMPILE_COMMANDS option to ensure a compilation database (compile_commands.json) is produced. This can be done either in your project’s CMakeLists.txt (i.e. set(CMAKE_EXPORT_COMPILE_COMMANDS ON)), or by setting the flag when invoking CMake (i.e. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON).

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 two things:

  • It contains multiple commands for each file, i.e. foo.cc will have compile commands for multiple clang host builds, multiple gcc host builds, multiple gcc-arm-none-eabi device 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 clangd.

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

If your 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; pw_ide will determine if the file needs processing or not.

Note

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, since 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:
      pw_strict_host_gcc_debug
      pw_strict_host_clang_debug
      stm32f429i_disc1_debug

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.