diff options
Diffstat (limited to 'docs/editors.rst')
| -rw-r--r-- | docs/editors.rst | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/docs/editors.rst b/docs/editors.rst new file mode 100644 index 000000000..94ba0209f --- /dev/null +++ b/docs/editors.rst @@ -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-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. |