1.. _module-pw_ide: 2 3------ 4pw_ide 5------ 6This module provides tools for supporting code editor and IDE features for 7Pigweed projects. 8 9Usage 10===== 11 12Setup 13----- 14Most of the time, ``pw ide setup`` is all you need to get started. 15 16Configuration 17------------- 18``pw_ide`` has a built-in default configuration. You can create a configuration 19file if you need to override those defaults. 20 21A project configuration can be defined in ``.pw_ide.yaml`` in the project root. 22This configuration will be checked into source control and apply to all 23developers of the project. Each user can also create a ``.pw_ide.user.yaml`` 24file that overrides both the default and project settings, is not checked into 25source control, and applies only to that checkout of the project. All of these 26files have the same schema, in which these options can be configured: 27 28.. autoproperty:: pw_ide.settings.PigweedIdeSettings.working_dir 29.. autoproperty:: pw_ide.settings.PigweedIdeSettings.build_dir 30.. autoproperty:: pw_ide.settings.PigweedIdeSettings.compdb_paths 31.. autoproperty:: pw_ide.settings.PigweedIdeSettings.targets 32.. autoproperty:: pw_ide.settings.PigweedIdeSettings.target_inference 33.. autoproperty:: pw_ide.settings.PigweedIdeSettings.default_target 34.. autoproperty:: pw_ide.settings.PigweedIdeSettings.setup 35.. autoproperty:: pw_ide.settings.PigweedIdeSettings.clangd_additional_query_drivers 36.. autoproperty:: pw_ide.settings.PigweedIdeSettings.editors 37 38C++ Code Intelligence 39--------------------- 40`clangd <https://clangd.llvm.org/>`_ is a language server that provides C/C++ 41code intelligence features to any editor that supports the language server 42protocol (LSP). It uses a 43`compilation database <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`_, 44a JSON file containing the compile commands for the project. Projects that have 45multiple targets and/or use multiple toolchains need separate compilation 46databases for each target/toolchain. ``pw_ide`` provides tools for managing 47those databases. 48 49Assuming you have a compilation database output from a build system, start with: 50 51.. code-block:: bash 52 53 pw ide cpp --process <path or glob to your compile_commands.json file(s)> 54 55The ``pw_ide`` working directory will now contain one or more compilation 56database files, each for a separate target among the targets defined in 57``.pw_ide.yaml``. If you're using GN, you can generate the initial compilation 58database and process it in a single command by adding the ``--gn`` flag. 59 60List the available targets with: 61 62.. code-block:: bash 63 64 pw ide cpp --list 65 66Then set the target that ``clangd`` should use with: 67 68.. code-block:: bash 69 70 pw ide cpp --set <selected target name> 71 72``clangd`` can now be configured to point to the ``compile_commands.json`` file 73in the ``pw_ide`` working directory and provide code intelligence for the 74selected target. If you select a new target, ``clangd`` *does not* need to be 75reconfigured to look at a new file (in other words, ``clangd`` can always be 76pointed at the same, stable ``compile_commands.json`` file). However, 77``clangd`` may need to be restarted when the target changes. 78 79``clangd`` must be run within the activated Pigweed environment in order for 80``clangd.sh`` instead of directly using the ``clangd`` binary. 81 82``clangd`` must be run with arguments that provide the Pigweed environment paths 83to the correct toolchains and sysroots. One way to do this is to launch your 84editor from the terminal in an activated environment (e.g. running ``vim`` from 85the terminal), in which case nothing special needs to be done as long as your 86toolchains are in the Pigweed environment or ``$PATH``. But if you launch your 87editor outside of the activated environment (e.g. launching Visual Studio Code 88from your GUI shell's launcher), you can generate the command that invokes 89``clangd`` with the right arguments with: 90 91.. code-block:: bash 92 93 pw ide cpp --clangd-command 94 95Python Code Intelligence 96------------------------ 97Any Python language server should work well with Pigweed projects as long as 98it's configured to use the Pigweed virtual environment. You can output the path 99to the virtual environment on your system with: 100 101.. code-block:: bash 102 103 pw ide python --venv 104 105Docs Code Intelligence 106---------------------- 107The `esbonio <https://github.com/swyddfa/esbonio>`_ language server will provide 108code intelligence for RestructuredText and Sphinx. It works well with Pigweed 109projects as long as it is pointed to Pigweed's Python virtual environment. For 110Visual Studio Code, simply install the esbonio extension, which will be 111recommended to you after setting up ``pw_ide``. Once it's installed, a prompt 112will ask if you want to automatically install esbonio in your Pigweed Python 113environment. After that, give esbonio some time to index, then you're done! 114 115Command-Line Interface Reference 116-------------------------------- 117.. argparse:: 118 :module: pw_ide.cli 119 :func: _build_argument_parser 120 :prog: pw ide 121 122Design 123====== 124 125Supporting ``clangd`` for Embedded Projects 126------------------------------------------- 127There are three main challenges that often prevent ``clangd`` from working 128out-of-the-box with embedded projects: 129 130#. Embedded projects cross-compile using alternative toolchains, rather than 131 using the system toolchain. ``clangd`` doesn't know about those toolchains 132 by default. 133 134#. Embedded projects (particularly Pigweed project) often have *multiple* 135 targets that use *multiple* toolchains. Most build systems that generate 136 compilation databases put all compile commands in a single database, meaning 137 a single file can have multiple, conflicting compile commands. ``clangd`` 138 will typically use the first one it finds, which may not be the one you want. 139 140#. Pigweed projects have build steps that use languages other than C/C++. These 141 steps are not relevant to ``clangd`` but many build systems will include them 142 in the compilation database anyway. 143 144To deal with these challenges, ``pw_ide`` processes the compilation database you 145provide, yielding one or more compilation databases that are valid, consistent, 146and specific to a particular build target. This enables code intelligence and 147navigation features that reflect that build. 148 149After processing a compilation database, ``pw_ide`` knows what targets are 150available and provides tools for selecting which target is active. These tools 151can be integrated into code editors, but are ultimately CLI-driven and 152editor-agnostic. Enabling code intelligence in your editor may be as simple as 153configuring its language server protocol client to use the ``clangd`` command 154that ``pw_ide`` can generate for you. 155 156When to provide additional configuration to support your use cases 157^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 158The default configuration for ``clangd`` in ``pw_ide`` should work without 159additional configuration as long as you're using only toolchains provided by 160Pigweed and your native host toolchain. If you're using other toolchains, keep 161reading. 162 163``clangd`` needs two pieces of information to use a toolchain: 164 165#. A path to the compiler, which will be taken from the compile command. 166 167#. The same compiler to be reflected in the 168 `query driver <https://releases.llvm.org/10.0.0/tools/clang/tools/extra/docs/clangd/Configuration.html>`_ 169 argument provided when running ``clangd``. 170 171When using ``pw_ide`` with external toolchains, you only need to add a path to 172the compiler to ``clangd_additional_query_drivers`` in your project's 173``pw_ide.yaml`` file. When processing a compilation database, ``pw_ide`` will 174use the query driver globs to find your compiler and configure ``clangd`` to 175use it. 176 177Selected API Reference 178^^^^^^^^^^^^^^^^^^^^^^ 179.. automodule:: pw_ide.cpp 180 :members: CppCompileCommand, CppCompilationDatabase, CppCompilationDatabasesMap, CppIdeFeaturesState, path_to_executable, target_is_enabled, ClangdSettings 181 182Automated Support for Code Editors & IDEs 183----------------------------------------- 184``pw_ide`` provides a consistent framework for automatically applying settings 185for code editors, where default settings can be defined within ``pw_ide``, 186which can be overridden by project settings, which in turn can be overridden 187by individual user settings. 188 189Selected API Reference 190^^^^^^^^^^^^^^^^^^^^^^ 191.. automodule:: pw_ide.editors 192 :members: EditorSettingsDefinition, EditorSettingsFile, EditorSettingsManager 193 194.. automodule:: pw_ide.vscode 195 :members: VscSettingsType, VscSettingsManager 196