1.. _module-pw_ide-guide-cli: 2 3========== 4pw_ide CLI 5========== 6.. pigweed-module-subpage:: 7 :name: pw_ide 8 9The ``pw_ide`` command-line interface (CLI) provides an editor-independent 10mechanism for managing code intelligence for Pigweed projects. 11 12.. note:: 13 14 Currently, the CLI only supports :ref:`bootstrap projects<module-pw_ide-design-projects-bootstrap>`, 15 For :ref:`Bazel projects<module-pw_ide-design-projects-bazel>`, we recommend 16 using the :ref:`Visual Studio Code integration<module-pw_ide-guide-vscode>`. 17 18-------------------------------- 19Setting up C++ code intelligence 20-------------------------------- 21`clangd <https://clangd.llvm.org/>`_ is a language server that provides C/C++ 22code intelligence features to any editor that supports the language server 23protocol (LSP). It uses a `compilation database <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`_, 24a JSON file containing the compile commands for the project. Projects that have 25multiple targets and/or use multiple toolchains need separate compilation 26databases for each target toolchain. ``pw_ide`` provides tools for managing 27those databases. 28 29Assuming you have one or more compilation databases that have been generated by 30your build system, start with: 31 32.. code-block:: bash 33 34 pw ide sync 35 36This command will: 37 38- Find every compilation database in your build directory 39 40- Analyze each database 41 42 - If a database is internally consistent (i.e., it only contains valid 43 compile commands for a single target), it will use that database as-is for 44 the target toolchain that database pertains to. This is the typical case for 45 CMake builds. 46 47 - Otherwise, if a database contains commands for multiple target toolchains 48 and/or contains invalid compile commands, the database will be processed, 49 yielding one new compilation database for each target toolchain. Those 50 databases will be used instead of the original. 51 52- Link each target to its respective compilation database 53 54Now, you can list the available target toolchains with: 55 56.. code-block:: bash 57 58 pw ide cpp --list 59 60Then set the target toolchain that ``clangd`` should use with: 61 62.. code-block:: bash 63 64 pw ide cpp --set <selected target name> 65 66``clangd`` will now work as designed since it is configured to use a compilation 67database that is consistent to just a single target toolchain. 68 69``clangd`` must be run with arguments that provide the Pigweed environment paths 70to the correct toolchains and sysroots. One way to do this is to launch your 71editor from the terminal in an activated environment (e.g. running ``vim`` from 72the terminal), in which case nothing special needs to be done as long as your 73toolchains are in the Pigweed environment or ``$PATH``. But if you launch your 74editor outside of the activated environment (e.g. launching Visual Studio Code 75from your GUI shell's launcher), you can generate the command that invokes 76``clangd`` with the right arguments with: 77 78.. code-block:: bash 79 80 pw ide cpp --clangd-command 81 82----------------------------------- 83Setting up Python code intelligence 84----------------------------------- 85Any Python language server should work well with Pigweed projects as long as 86it's configured to use the Pigweed virtual environment. You can output the path 87to the virtual environment on your system with: 88 89.. code-block:: bash 90 91 pw ide python --venv 92 93--------------------------------- 94Setting up docs code intelligence 95--------------------------------- 96The `esbonio <https://github.com/swyddfa/esbonio>`_ language server will provide 97code intelligence for reStructuredText and Sphinx. It works well with Pigweed 98projects as long as it is pointed to Pigweed's Python virtual environment. For 99Visual Studio Code, simply install the esbonio extension, which will be 100recommended to you after setting up ``pw_ide``. Once it's installed, a prompt 101will ask if you want to automatically install esbonio in your Pigweed Python 102environment. After that, give esbonio some time to index, then you're done! 103 104-------------------------------- 105Command-line interface reference 106-------------------------------- 107.. argparse:: 108 :module: pw_ide.cli 109 :func: _build_argument_parser 110 :prog: pw ide 111 112------------- 113Configuration 114------------- 115``pw_ide`` has a built-in default configuration, so you don't need to create 116a configuration file to get started. You can create a configuration file if you 117need to override those defaults. 118 119A project configuration can be defined in ``.pw_ide.yaml`` in the project root. 120This configuration will be checked into source control and apply to all 121developers of the project. Each user can also create a ``.pw_ide.user.yaml`` 122file that overrides both the default and project settings, is not checked into 123source control, and applies only to that checkout of the project. All of these 124files have the same schema, in which these options can be configured: 125 126.. autoproperty:: pw_ide.settings.PigweedIdeSettings.working_dir 127.. autoproperty:: pw_ide.settings.PigweedIdeSettings.compdb_gen_cmd 128.. autoproperty:: pw_ide.settings.PigweedIdeSettings.compdb_search_paths 129.. autoproperty:: pw_ide.settings.PigweedIdeSettings.target_inference 130.. autoproperty:: pw_ide.settings.PigweedIdeSettings.targets_include 131.. autoproperty:: pw_ide.settings.PigweedIdeSettings.targets_exclude 132.. autoproperty:: pw_ide.settings.PigweedIdeSettings.default_target 133.. autoproperty:: pw_ide.settings.PigweedIdeSettings.cascade_targets 134.. autoproperty:: pw_ide.settings.PigweedIdeSettings.sync 135.. autoproperty:: pw_ide.settings.PigweedIdeSettings.clangd_additional_query_drivers 136.. autoproperty:: pw_ide.settings.PigweedIdeSettings.workspace_root 137 138When to provide additional configuration to support your use cases 139================================================================== 140The default configuration for ``clangd`` in ``pw_ide`` should work without 141additional configuration as long as you're using only toolchains provided by 142Pigweed and your native host toolchain. If you're using other toolchains, keep 143reading. 144 145``clangd`` needs two pieces of information to use a toolchain: 146 147#. A path to the compiler, which will be taken from the compile command. 148 149#. The same compiler to be reflected in the 150 `query driver <https://releases.llvm.org/10.0.0/tools/clang/tools/extra/docs/clangd/Configuration.html>`_ 151 argument provided when running ``clangd``. 152 153When using ``pw_ide`` with external toolchains, you only need to add a path to 154the compiler to ``clangd_additional_query_drivers`` in your project's 155``pw_ide.yaml`` file. When processing a compilation database, ``pw_ide`` will 156use the query driver globs to find your compiler and configure ``clangd`` to 157use it. 158 159Using compiler wrappers 160======================= 161If you're using ``ccache`` or any other wrapper command that is configured 162using ``ccache``'s' ``KEY=VALUE`` pattern, it will work out of the box. 163