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 sync`` is all you need to get started. 15 16.. _module-pw_ide-configuration: 17 18Configuration 19------------- 20``pw_ide`` has a built-in default configuration. You can create a configuration 21file if you need to override those defaults. 22 23A project configuration can be defined in ``.pw_ide.yaml`` in the project root. 24This configuration will be checked into source control and apply to all 25developers of the project. Each user can also create a ``.pw_ide.user.yaml`` 26file that overrides both the default and project settings, is not checked into 27source control, and applies only to that checkout of the project. All of these 28files have the same schema, in which these options can be configured: 29 30.. autoproperty:: pw_ide.settings.PigweedIdeSettings.working_dir 31.. autoproperty:: pw_ide.settings.PigweedIdeSettings.compdb_gen_cmd 32.. autoproperty:: pw_ide.settings.PigweedIdeSettings.compdb_search_paths 33.. autoproperty:: pw_ide.settings.PigweedIdeSettings.target_inference 34.. autoproperty:: pw_ide.settings.PigweedIdeSettings.targets_include 35.. autoproperty:: pw_ide.settings.PigweedIdeSettings.targets_exclude 36.. autoproperty:: pw_ide.settings.PigweedIdeSettings.default_target 37.. autoproperty:: pw_ide.settings.PigweedIdeSettings.cascade_targets 38.. autoproperty:: pw_ide.settings.PigweedIdeSettings.sync 39.. autoproperty:: pw_ide.settings.PigweedIdeSettings.clangd_additional_query_drivers 40.. autoproperty:: pw_ide.settings.PigweedIdeSettings.editors 41 42C++ Code Intelligence 43--------------------- 44`clangd <https://clangd.llvm.org/>`_ is a language server that provides C/C++ 45code intelligence features to any editor that supports the language server 46protocol (LSP). It uses a 47`compilation database <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`_, 48a JSON file containing the compile commands for the project. Projects that have 49multiple targets and/or use multiple toolchains need separate compilation 50databases for each target toolchain. ``pw_ide`` provides tools for managing 51those databases. 52 53Assuming you have one or more compilation databases that have been generated by 54your build system, start with: 55 56.. code-block:: bash 57 58 pw ide sync 59 60This command will: 61 62- Find every compilation database in your build directory 63 64- Analyze each database 65 66 - If a database is internally consistent (i.e., it only contains valid 67 compile commands for a single target), it will use that database as-is for 68 the target toolchain that database pertains to. This is the typical case for 69 CMake builds. 70 71 - Otherwise, if a database contains commands for multiple target toolchains 72 and/or contains invalid compile commands, the database will be processed, 73 yielding one new compilation database for each target toolchain. Those 74 databases will be used instead of the original. 75 76- Link each target to its respective compilation database 77 78Now, you can list the available target toolchains with: 79 80.. code-block:: bash 81 82 pw ide cpp --list 83 84Then set the target toolchain that ``clangd`` should use with: 85 86.. code-block:: bash 87 88 pw ide cpp --set <selected target name> 89 90``clangd`` will now work as designed since it is configured to use a compilation 91database that is consistent to just a single target toolchain. 92 93``clangd`` must be run with arguments that provide the Pigweed environment paths 94to the correct toolchains and sysroots. One way to do this is to launch your 95editor from the terminal in an activated environment (e.g. running ``vim`` from 96the terminal), in which case nothing special needs to be done as long as your 97toolchains are in the Pigweed environment or ``$PATH``. But if you launch your 98editor outside of the activated environment (e.g. launching Visual Studio Code 99from your GUI shell's launcher), you can generate the command that invokes 100``clangd`` with the right arguments with: 101 102.. code-block:: bash 103 104 pw ide cpp --clangd-command 105 106Python Code Intelligence 107------------------------ 108Any Python language server should work well with Pigweed projects as long as 109it's configured to use the Pigweed virtual environment. You can output the path 110to the virtual environment on your system with: 111 112.. code-block:: bash 113 114 pw ide python --venv 115 116Docs Code Intelligence 117---------------------- 118The `esbonio <https://github.com/swyddfa/esbonio>`_ language server will provide 119code intelligence for RestructuredText and Sphinx. It works well with Pigweed 120projects as long as it is pointed to Pigweed's Python virtual environment. For 121Visual Studio Code, simply install the esbonio extension, which will be 122recommended to you after setting up ``pw_ide``. Once it's installed, a prompt 123will ask if you want to automatically install esbonio in your Pigweed Python 124environment. After that, give esbonio some time to index, then you're done! 125 126Command-Line Interface Reference 127-------------------------------- 128.. argparse:: 129 :module: pw_ide.cli 130 :func: _build_argument_parser 131 :prog: pw ide 132 133Design 134====== 135 136Supporting ``clangd`` for Embedded Projects 137------------------------------------------- 138There are three main challenges that often prevent ``clangd`` from working 139out-of-the-box with embedded projects: 140 141#. Embedded projects cross-compile using alternative toolchains, rather than 142 using the system toolchain. ``clangd`` doesn't know about those toolchains 143 by default. 144 145#. Embedded projects (particularly Pigweed project) often have *multiple* 146 targets that use *multiple* toolchains. Most build systems that generate 147 compilation databases put all compile commands in a single database, meaning 148 a single file can have multiple, conflicting compile commands. ``clangd`` 149 will typically use the first one it finds, which may not be the one you want. 150 151#. Pigweed projects have build steps that use languages other than C/C++. These 152 steps are not relevant to ``clangd`` but many build systems will include them 153 in the compilation database anyway. 154 155To deal with these challenges, ``pw_ide`` processes the compilation database you 156provide, yielding one or more compilation databases that are valid, consistent, 157and specific to a particular target toolchain. This enables code intelligence 158and navigation features that reflect that build. 159 160After processing a compilation database, ``pw_ide`` knows what target toolchains 161are available and provides tools for selecting which target toolchain is active. 162These tools can be integrated into code editors, but are ultimately CLI-driven 163and editor-agnostic. Enabling code intelligence in your editor may be as simple 164as configuring its language server protocol client to use the ``clangd`` command 165that ``pw_ide`` can generate for you. 166 167When to provide additional configuration to support your use cases 168^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 169The default configuration for ``clangd`` in ``pw_ide`` should work without 170additional configuration as long as you're using only toolchains provided by 171Pigweed and your native host toolchain. If you're using other toolchains, keep 172reading. 173 174``clangd`` needs two pieces of information to use a toolchain: 175 176#. A path to the compiler, which will be taken from the compile command. 177 178#. The same compiler to be reflected in the 179 `query driver <https://releases.llvm.org/10.0.0/tools/clang/tools/extra/docs/clangd/Configuration.html>`_ 180 argument provided when running ``clangd``. 181 182When using ``pw_ide`` with external toolchains, you only need to add a path to 183the compiler to ``clangd_additional_query_drivers`` in your project's 184``pw_ide.yaml`` file. When processing a compilation database, ``pw_ide`` will 185use the query driver globs to find your compiler and configure ``clangd`` to 186use it. 187 188Compiler wrappers 189^^^^^^^^^^^^^^^^^ 190If you're using ``ccache`` or any other wrapper command that is configured 191using ``ccache``'s' ``KEY=VALUE`` pattern, it will work out of the box. 192 193Selected API Reference 194^^^^^^^^^^^^^^^^^^^^^^ 195.. automodule:: pw_ide.cpp 196 :members: CppCompileCommand, CppCompilationDatabase, CppCompilationDatabasesMap, CppIdeFeaturesState, path_to_executable, ClangdSettings 197 198Automated Support for Code Editors & IDEs 199----------------------------------------- 200``pw_ide`` provides a consistent framework for automatically applying settings 201for code editors, where default settings can be defined within ``pw_ide``, 202which can be overridden by project settings, which in turn can be overridden 203by individual user settings. 204 205.. _module-pw_ide-vscode: 206 207Visual Studio Code 208^^^^^^^^^^^^^^^^^^ 209Running ``pw ide sync`` will automatically generate settings for Visual Studio 210Code. ``pw_ide`` comes with sensible defaults for Pigweed projects, but those 211can be augmented or overridden at the project level or the user level using 212``pw_project_settings.json`` and ``pw_user_settings.json`` respectively. The 213generated ``settings.json`` file is essentially a build artifact and shouldn't 214be committed to source control. 215 216.. note:: 217 218 You should treat ``settings.json`` as a build artifact and avoid editing it 219 directly. However, if you do make changes to it, don't worry! The changes 220 will be preserved after running ``pw ide sync`` 221 222The same pattern applies to ``tasks.json``, which provides Visual Studio Code 223tasks for ``pw_ide`` commands. Access these by opening the command palette 224(Ctrl/Cmd-Shift-P), selecting ``Tasks: Run Task``, then selecting the desired 225task. 226 227The same pattern also applies to ``launch.json``, which is used to define 228configurations for running and debugging your project. Create a 229``pw_project_launch.json`` with configurations that conform to the Visual Studio 230Code `debugger configuration format <https://code.visualstudio.com/docs/editor/debugging>`_. 231 232.. tip:: 233 234 What's the difference between "Change C++ Code Analysis Target" and "Set C++ 235 Code Analyis Target"? "Set" will automatically restart the ``clangd`` 236 language server for you to pick up the changed target immediately, while 237 "Change" will not. 238 239Selected API Reference 240^^^^^^^^^^^^^^^^^^^^^^ 241.. automodule:: pw_ide.editors 242 :members: EditorSettingsDefinition, EditorSettingsFile, EditorSettingsManager 243 244.. automodule:: pw_ide.vscode 245 :members: VscSettingsType, VscSettingsManager 246