.. _docs-editors:

-------------------
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 <https://code.visualstudio.com/>`_, 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
:ref:`Visual Studio Code<module-pw_ide-vscode>` 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
:ref:`build system<docs-editors-compdb>`.

It isn't working for my toolchain
---------------------------------
You may need to specify additional `query drivers <https://releases.llvm.org/10.0.0/tools/clang/tools/extra/docs/clangd/Configuration.html#query-driver>`_
to allow ``clangd`` to use your toolchains. Refer to the
:ref:`pw_ide documentation<module-pw_ide-configuration>` 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 :ref:`pw_ide docs<module-pw_ide-vscode>`.

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
  :ref:`facades and backends<docs-module-structure-facades>` for each target.

We've found that the best solution is to use the
`clangd <https://clangd.llvm.org/>`_ language server or alternative language
servers that use the same
`compilation database format <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`_
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.

.. _docs-editors-compdb:

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
:ref:`pw_ide<module-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:

.. code-block:: bash

   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:

.. code-block:: bash

   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.

.. admonition:: Note
   :class: warning

   **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:

.. code-block::

   $ 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:

.. code-block::

   $ 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:

.. code-block::

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