[PATCH] D66740: [clangd] Add docs for configuration knobs in clangd

[Kadir Cetinkaya via Phabricator via cfe-commits]

kadircet created this revision.
kadircet added a reviewer: sammccall.
Herald added subscribers: cfe-commits, arphaman, jkorous, MaskRay, ilya-biryukov.
Herald added a project: clang.

This is a first step in documenting different configuration knobs we
have in clangd.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D66740

Files:
  clang-tools-extra/docs/clangd/Configuration.rst
  clang-tools-extra/docs/clangd/index.rst


Index: clang-tools-extra/docs/clangd/index.rst
===================================================================
--- clang-tools-extra/docs/clangd/index.rst
+++ clang-tools-extra/docs/clangd/index.rst
@@ -7,6 +7,7 @@
 
    Installation
    Features
+   Configuration
 
 What is clangd?
 ===============
Index: clang-tools-extra/docs/clangd/Configuration.rst
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/clangd/Configuration.rst
@@ -0,0 +1,41 @@
+========
+Configuration
+========
+
+.. contents::
+
+.. role:: raw-html(raw)
+   :format: html
+
+Clangd has a bunch of command-line options and LSP capabilities that can change
+its behaviour in certain situations. This page aims to define those
+configuration knobs.
+
+--query-driver
+==============
+
+Clangd makes use of clang behind the scenes, so it might fail to detect your
+standard library or built-in headers if your project is making use of a custom
+toolchain. That is quite common in hardware-related projects, especially for the
+ones making use of gcc (e.g. ARM's `arm-none-eabi-gcc`).
+
+To get over this clangd can query your toolchain driver to extract implicit
+include paths that are unknown to clang. Since this requires executing a binary,
+we require users of this feature to whitelist their driver using the
+`--query-driver` flag. It accepts a comma-separated list of globs, which will
+match against the compiler driver paths specified in your
+`compile_commands.json`.
+
+For example if you have your compilers at
+`/path/to/my-custom-toolchain/arm-none-eabi-gcc` and
+`/path/to/my-custom-toolchain/arm-none-eabi-g++`; you
+can provide clangd with `--query-driver=**/my-custom-toolchain/arm-none-eabi*`
+to enable execution of any binary that has a name starting with `arm-none-eabi`
+and under a directory called `my-custom-toolchain`.
+
+By default this flag is empty, which disallows execution of any driver.
+
+Full list of flags
+==================
+
+You can find rest of the flags in `source code <https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clangd/tool/ClangdMain.cpp>`__.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D66740.217141.patch
Type: text/x-patch
Size: 2146 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20190826/5c9b0b14/attachment-0001.bin>