docs/editors.rst - pigweed/pigweed - Git at Google

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