196 lines
8.3 KiB
ReStructuredText
196 lines
8.3 KiB
ReStructuredText
.. _module-pw_ide:
|
|
|
|
------
|
|
pw_ide
|
|
------
|
|
This module provides tools for supporting code editor and IDE features for
|
|
Pigweed projects.
|
|
|
|
Usage
|
|
=====
|
|
|
|
Setup
|
|
-----
|
|
Most of the time, ``pw ide setup`` is all you need to get started.
|
|
|
|
Configuration
|
|
-------------
|
|
``pw_ide`` has a built-in default configuration. You can create a configuration
|
|
file if you need to override those defaults.
|
|
|
|
A project configuration can be defined in ``.pw_ide.yaml`` in the project root.
|
|
This configuration will be checked into source control and apply to all
|
|
developers of the project. Each user can also create a ``.pw_ide.user.yaml``
|
|
file that overrides both the default and project settings, is not checked into
|
|
source control, and applies only to that checkout of the project. All of these
|
|
files have the same schema, in which these options can be configured:
|
|
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.working_dir
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.build_dir
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.compdb_paths
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.targets
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.target_inference
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.default_target
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.setup
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.clangd_additional_query_drivers
|
|
.. autoproperty:: pw_ide.settings.PigweedIdeSettings.editors
|
|
|
|
C++ Code Intelligence
|
|
---------------------
|
|
`clangd <https://clangd.llvm.org/>`_ is a language server that provides C/C++
|
|
code intelligence features to any editor that supports the language server
|
|
protocol (LSP). It uses a
|
|
`compilation database <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`_,
|
|
a JSON file containing the compile commands for the project. Projects that have
|
|
multiple targets and/or use multiple toolchains need separate compilation
|
|
databases for each target/toolchain. ``pw_ide`` provides tools for managing
|
|
those databases.
|
|
|
|
Assuming you have a compilation database output from a build system, start with:
|
|
|
|
.. code-block:: bash
|
|
|
|
pw ide cpp --process <path or glob to your compile_commands.json file(s)>
|
|
|
|
The ``pw_ide`` working directory will now contain one or more compilation
|
|
database files, each for a separate target among the targets defined in
|
|
``.pw_ide.yaml``. If you're using GN, you can generate the initial compilation
|
|
database and process it in a single command by adding the ``--gn`` flag.
|
|
|
|
List the available targets with:
|
|
|
|
.. code-block:: bash
|
|
|
|
pw ide cpp --list
|
|
|
|
Then set the target that ``clangd`` should use with:
|
|
|
|
.. code-block:: bash
|
|
|
|
pw ide cpp --set <selected target name>
|
|
|
|
``clangd`` can now be configured to point to the ``compile_commands.json`` file
|
|
in the ``pw_ide`` working directory and provide code intelligence for the
|
|
selected target. If you select a new target, ``clangd`` *does not* need to be
|
|
reconfigured to look at a new file (in other words, ``clangd`` can always be
|
|
pointed at the same, stable ``compile_commands.json`` file). However,
|
|
``clangd`` may need to be restarted when the target changes.
|
|
|
|
``clangd`` must be run within the activated Pigweed environment in order for
|
|
``clangd.sh`` instead of directly using the ``clangd`` binary.
|
|
|
|
``clangd`` must be run with arguments that provide the Pigweed environment paths
|
|
to the correct toolchains and sysroots. One way to do this is to launch your
|
|
editor from the terminal in an activated environment (e.g. running ``vim`` from
|
|
the terminal), in which case nothing special needs to be done as long as your
|
|
toolchains are in the Pigweed environment or ``$PATH``. But if you launch your
|
|
editor outside of the activated environment (e.g. launching Visual Studio Code
|
|
from your GUI shell's launcher), you can generate the command that invokes
|
|
``clangd`` with the right arguments with:
|
|
|
|
.. code-block:: bash
|
|
|
|
pw ide cpp --clangd-command
|
|
|
|
Python Code Intelligence
|
|
------------------------
|
|
Any Python language server should work well with Pigweed projects as long as
|
|
it's configured to use the Pigweed virtual environment. You can output the path
|
|
to the virtual environment on your system with:
|
|
|
|
.. code-block:: bash
|
|
|
|
pw ide python --venv
|
|
|
|
Docs Code Intelligence
|
|
----------------------
|
|
The `esbonio <https://github.com/swyddfa/esbonio>`_ language server will provide
|
|
code intelligence for RestructuredText and Sphinx. It works well with Pigweed
|
|
projects as long as it is pointed to Pigweed's Python virtual environment. For
|
|
Visual Studio Code, simply install the esbonio extension, which will be
|
|
recommended to you after setting up ``pw_ide``. Once it's installed, a prompt
|
|
will ask if you want to automatically install esbonio in your Pigweed Python
|
|
environment. After that, give esbonio some time to index, then you're done!
|
|
|
|
Command-Line Interface Reference
|
|
--------------------------------
|
|
.. argparse::
|
|
:module: pw_ide.cli
|
|
:func: _build_argument_parser
|
|
:prog: pw ide
|
|
|
|
Design
|
|
======
|
|
|
|
Supporting ``clangd`` for Embedded Projects
|
|
-------------------------------------------
|
|
There are three main challenges that often prevent ``clangd`` from working
|
|
out-of-the-box with embedded projects:
|
|
|
|
#. Embedded projects cross-compile using alternative toolchains, rather than
|
|
using the system toolchain. ``clangd`` doesn't know about those toolchains
|
|
by default.
|
|
|
|
#. Embedded projects (particularly Pigweed project) often have *multiple*
|
|
targets that use *multiple* toolchains. Most build systems that generate
|
|
compilation databases put all compile commands in a single database, meaning
|
|
a single file can have multiple, conflicting compile commands. ``clangd``
|
|
will typically use the first one it finds, which may not be the one you want.
|
|
|
|
#. Pigweed projects have build steps that use languages other than C/C++. These
|
|
steps are not relevant to ``clangd`` but many build systems will include them
|
|
in the compilation database anyway.
|
|
|
|
To deal with these challenges, ``pw_ide`` processes the compilation database you
|
|
provide, yielding one or more compilation databases that are valid, consistent,
|
|
and specific to a particular build target. This enables code intelligence and
|
|
navigation features that reflect that build.
|
|
|
|
After processing a compilation database, ``pw_ide`` knows what targets are
|
|
available and provides tools for selecting which target is active. These tools
|
|
can be integrated into code editors, but are ultimately CLI-driven and
|
|
editor-agnostic. Enabling code intelligence in your editor may be as simple as
|
|
configuring its language server protocol client to use the ``clangd`` command
|
|
that ``pw_ide`` can generate for you.
|
|
|
|
When to provide additional configuration to support your use cases
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
The default configuration for ``clangd`` in ``pw_ide`` should work without
|
|
additional configuration as long as you're using only toolchains provided by
|
|
Pigweed and your native host toolchain. If you're using other toolchains, keep
|
|
reading.
|
|
|
|
``clangd`` needs two pieces of information to use a toolchain:
|
|
|
|
#. A path to the compiler, which will be taken from the compile command.
|
|
|
|
#. The same compiler to be reflected in the
|
|
`query driver <https://releases.llvm.org/10.0.0/tools/clang/tools/extra/docs/clangd/Configuration.html>`_
|
|
argument provided when running ``clangd``.
|
|
|
|
When using ``pw_ide`` with external toolchains, you only need to add a path to
|
|
the compiler to ``clangd_additional_query_drivers`` in your project's
|
|
``pw_ide.yaml`` file. When processing a compilation database, ``pw_ide`` will
|
|
use the query driver globs to find your compiler and configure ``clangd`` to
|
|
use it.
|
|
|
|
Selected API Reference
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
.. automodule:: pw_ide.cpp
|
|
:members: CppCompileCommand, CppCompilationDatabase, CppCompilationDatabasesMap, CppIdeFeaturesState, path_to_executable, target_is_enabled, ClangdSettings
|
|
|
|
Automated Support for Code Editors & IDEs
|
|
-----------------------------------------
|
|
``pw_ide`` provides a consistent framework for automatically applying settings
|
|
for code editors, where default settings can be defined within ``pw_ide``,
|
|
which can be overridden by project settings, which in turn can be overridden
|
|
by individual user settings.
|
|
|
|
Selected API Reference
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
.. automodule:: pw_ide.editors
|
|
:members: EditorSettingsDefinition, EditorSettingsFile, EditorSettingsManager
|
|
|
|
.. automodule:: pw_ide.vscode
|
|
:members: VscSettingsType, VscSettingsManager
|