1.. _docs-editors: 2 3------------------- 4Code Editor Support 5------------------- 6Pigweed projects can be (and have been!) successfully developed in simple text 7editors. However, if you want to take advantage of the latest code intelligence 8tools and IDE features, those can be configured to work great with Pigweed. 9 10We are building the ideal development experience for Pigweed projects using 11`Visual Studio Code <https://code.visualstudio.com/>`_, a powerful and highly 12extensible code editor. However, most of the features described in this doc are 13available to other popular editors; you may just need to do a little more 14configuration to make it work. 15 16Quick Start for Contributing to Pigweed 17======================================= 18If you're developing on upstream Pigweed, you can use Visual Studio Code, which 19is already configured to work best with Pigweed, or you can use another editor 20and configure it yourself. 21 22With Visual Studio Code 23------------------------ 24There are three quick steps to get started with Pigweed in Visual Studio Code. 25 261. Bootstrap your Pigweed environment (if you haven't already). 27 282. Run ``gn gen out`` (if you haven't already). 29 303. Run ``pw ide sync`` 31 324. Open the Pigweed repository in Visual Studio Code and install the recommended 33 plugins. 34 35You're done! Refer to the ``pw_ide`` documentation for 36:ref:`Visual Studio Code<module-pw_ide-vscode>` for more guidance. 37 38With Other Editors 39------------------- 40There are three short steps to get code intelligence in most editors for C++ and 41Python, the two most prevalent languages in Pigweed. 42 431. Bootstrap your Pigweed environment (if you haven't already). 44 452. Ensure that your Python plugin/language server is configured to use Pigweed's 46 Python virtual environment, located at 47 ``$PW_PROJECT_ROOT/environment/pigweed-venv``. 48 493. Set up C++ code intelligence by running ``pw ide cpp --clangd-command`` to 50 generate the ``clangd`` invocation for your system, and configure your 51 language server to use it. 52 53Quick Start for Setting Up Projects Using Pigweed 54================================================= 55If you're developing on a downstream project using Pigweed, the instructions 56for upstream Pigweed may just work out of the box on your project. Give it a 57try! 58 59If it doesn't work, here are some common reasons why, and ways you can fix it 60for your project. 61 62It can't find any compilation databases 63--------------------------------------- 64You need to generate at least one compilation database before running 65``pw ide sync``. Usually you will do this with your 66:ref:`build system<docs-editors-compdb>`. 67 68It isn't working for my toolchain 69--------------------------------- 70You may need to specify additional `query drivers <https://releases.llvm.org/10.0.0/tools/clang/tools/extra/docs/clangd/Configuration.html#query-driver>`_ 71to allow ``clangd`` to use your toolchains. Refer to the 72:ref:`pw_ide documentation<module-pw_ide-configuration>` for information on 73configuring this. 74 75Using Visual Studio Code 76======================== 77 78Code Intelligence 79----------------- 80If you followed the quick start steps above, you're already set! Here's a 81non-exhaustive list of cool features you can now enjoy: 82 83* C/C++ 84 85 * Code navigation, including routing through facades to the correct backend 86 87 * Code completion, including correct class members and function signatures 88 89 * Tool tips with docs, inferred types for ``auto``, inferred values for 90 ``constexpr``, data type sizes, etc. 91 92 * Compiler errors and warnings 93 94* Python 95 96 * Code navigation and code completion 97 98 * Tool tips with docs 99 100 * Errors, warnings, and linting feedback 101 102Integrated Terminal 103------------------- 104When launching the integrated terminal, it will automatically activate the 105Pigweed environment within that shell session. 106 107Configuration 108------------- 109See the :ref:`pw_ide docs<module-pw_ide-vscode>`. 110 111Code Intelligence Features for Specific Languages 112================================================= 113 114C/C++ 115----- 116Pigweed projects have a few characteristics that make it challenging for some 117IDEs and language servers to support C/C++ code intelligence out of the box: 118 119* Pigweed projects generally don't use the default host toolchain. 120 121* Pigweed projects usually use multiple toolchains for separate targets. 122 123* Pigweed projects rely on the build system to define the relationship between 124 :ref:`facades and backends<docs-module-structure-facades>` for each target. 125 126We've found that the best solution is to use the 127`clangd <https://clangd.llvm.org/>`_ language server or alternative language 128servers that use the same 129`compilation database format <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`_ 130and comply with the language server protocol. We supplement that with Pigweed 131tools to produce target-specific compilation databases that work well with 132the language servers. 133 134.. _docs-editors-compdb: 135 136Producing a Compilation Database 137~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 138If you're using GN, then ``gn gen out --export-compile-commands`` will output 139a compilation database (``compile_commands.json``) in the ``out`` directory 140along with all of the other GN build outputs (in other words, it produces the 141same output as ``gn gen out`` but *additionally* produces the compilation 142database). 143 144If you're using CMake, you can enable the ``CMAKE_EXPORT_COMPILE_COMMANDS`` 145option to ensure a compilation database (``compile_commands.json``) is produced. 146This can be done either in your project's ``CMakeLists.txt`` (i.e. 147``set(CMAKE_EXPORT_COMPILE_COMMANDS ON)``), or by setting the flag when 148invoking CMake (i.e. ``-DCMAKE_EXPORT_COMPILE_COMMANDS=ON``). 149 150Bazel does not natively support generating compilation databases right now, 151though you may find third party extensions that provide this functionality. 152 153Processing the Compilation Database 154~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 155If you examine a ``compile_commands.json`` file produced GN, you'll observe 156two things: 157 158* It contains multiple commands for each file, i.e. ``foo.cc`` will have 159 compile commands for multiple ``clang`` host builds, multiple ``gcc`` host 160 builds, multiple ``gcc-arm-none-eabi`` device builds, etc. 161 162* It contains many commands that are not actually valid compile commands, 163 because they involve targets that use Pigweed Python wrappers to do various 164 static analyses. 165 166Both of these confound ``clangd`` and will produce broken, unexpected, or 167inconsistent results when used for code intelligence. So the 168:ref:`pw_ide<module-pw_ide>` module provides CLI tools that process the "raw" 169compilation database produced by the build system into one or more "clean" 170compilation databases that will work smoothly with ``clangd``. 171 172Once you have a compilation database, run this command to process it: 173 174.. code-block:: bash 175 176 pw ide cpp --process <path to compilation database> 177 178Or better yet, just let ``pw_ide`` find any compilation databases you have 179in your build and process them: 180 181.. code-block:: bash 182 183 pw ide cpp --process 184 185If your ``compile_commands.json`` file *did not* come from GN, it may not 186exhibit any of these problems and therefore not require any processing. 187Nonetheless, you can still run ``pw ide cpp --process``; ``pw_ide`` will 188determine if the file needs processing or not. 189 190.. admonition:: Note 191 :class: warning 192 193 **How often do we need to process the compilation database?** With GN, if 194 you're just editing existing files, there's no need to reprocess the 195 compilation database. But any time the build changes (e.g. adding new source 196 files or new targets), you will need to reprocess the compilation database. 197 198 With CMake, it is usually not necessary to reprocess compilation databases, 199 since ``pw_ide`` will automatically pick up any changes that CMake makes. 200 201Setting the Target to Use for Analysis 202~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 203Discover which targets are available for code analysis: 204 205.. code-block:: 206 207 $ pw ide cpp --list 208 209 C/C++ targets available for language server analysis: 210 pw_strict_host_gcc_debug 211 pw_strict_host_clang_debug 212 stm32f429i_disc1_debug 213 214Select the target you want to use for code analysis: 215 216.. code-block:: 217 218 $ pw ide cpp --set pw_strict_host_gcc_debug 219 220 Set C/C++ langauge server analysis target to: pw_strict_host_gcc_debug 221 222Check which target is currently used for code analysis: 223 224.. code-block:: 225 226 $ pw ide cpp 227 228 Current C/C++ language server analysis target: pw_strict_host_gcc_debug 229 230Your target selection will remain stable even after reprocessing the compilation 231database. Your editor configuration also remains stable; you don't need to 232change the editor configuration to change the target you're analyzing. 233