forked from google/pigweed
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Change-Id: I6dca9c80aee01b227aeb70df05089302101d5db9 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/110261 Commit-Queue: Chad Norvell <[email protected]> Reviewed-by: Anthony DiGirolamo <[email protected]> Presubmit-Verified: CQ Bot Account <[email protected]>
- Loading branch information
1 parent
2278b06
commit 0482a52
Showing
4 changed files
with
238 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,232 @@ | ||
.. _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:: 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:: 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:: | ||
$ 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:: | ||
$ 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:: | ||
$ 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters