From beed394d94c2b246312145038c285e279d3ac154 Mon Sep 17 00:00:00 2001
From: Fangrui Song <i@maskray.me>
Date: Fri, 13 Jul 2018 20:52:37 -0700
Subject: [PATCH] FAQ

---
 FAQ.md | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/FAQ.md b/FAQ.md
index 2bcc431..50a7ce0 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -20,7 +20,8 @@ For CMake this can be achieved in a single line: `target_include_directories(<ta
 
 #### If `-resource-dir` is correct
 
-If the [[initialization option|Initialization options]] `cacheDirectory` is `/tmp/ccls`, and the source file is `/tmp/c/a.cc`, `jq . < /tmp/ccls/@tmp@c/a.cc.json` to see if `-resource-dir` is correct, e.g. `"-resource-dir=/home/ray/Dev/Util/cquery/build/debug/lib/clang+llvm-5.0.1-x86_64-linux-gnu-ubuntu-14.04/lib/clang/5.0.1"`
+If the [[initialization option|Initialization options]] `cacheDirectory` is `/tmp/ccls`, and the source file is `/tmp/c/a.cc`.
+Set [[Initialization options]] `"cacheFormat": "json"` and run `jq . < /tmp/ccls/@tmp@c/a.cc.json` to see if `-resource-dir` is correct, e.g. `"-resource-dir=/home/ray/Dev/Util/ccls/Debug/lib/clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-16.04/lib/clang/6.0.0"`
 
 system C/C++ headers can be detected reliably. For Clang resource directory, there is logic in `wscript` to detect it when you run `./waf configure [OPTIONS]`
 
@@ -34,17 +35,24 @@ system C/C++ headers can be detected reliably. For Clang resource directory, the
 
 #### `-isystem`
 
-`-isystem` system include paths is usually unnecessary. But for cross compiling or on some bizarre system you may have to specify them. A simple approach other than trial and error (changing `.ccls` and restarting your editor) is to use `c-index-test` (if you use `--bundled-clang`, preferably the executable in the extracted tarball; if you link against system libclang, use something like `/usr/bin/c-index-test`)
+ccls infers system search paths (e.g. `/usr/include`). The underneath mechanism is similar to that of `clang -v -E -x c++ /dev/null`.
 
-`build/debug/lib/clang+llvm-5.0.1-x86_64-linux-gnu-ubuntu-14.04/bin/c-index-test -index-file local /tmp/c/a.cc -isystem/usr/include/c++/7.3.0 -isystemyour_include_path2`
+`-isystem` system include paths is usually unnecessary. But for cross compiling or on some bizarre system you may have to specify them. A simple approach other than trial and error (changing `.ccls` and restarting your editor) is to use `c-index-test`.
 
-Play with your `-isystem` options until you get a group of options that you can add to [`.ccls`](https://github.com/MaskRay/cquery/wiki/Getting-started#cquery)
+`Debug/clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-16.04/bin/c-index-test -index-file local /tmp/c/a.cc -isystem/usr/include/c++/7.3.0 -isystemyour_include_path2`
+
+Play with your `-isystem` options until you get a group of options that you can add to [`.ccls`](https://github.com/MaskRay/ccls/wiki/Getting-started#ccls)
 
 If you want the ccls binary at a specific location use a symlink - do not move the binary itself.
 
+If you want to specify additional search paths:
+
+* `print '%clang\n%cpp -std=gnu++14\n-isystem/tmp/include' > .ccls`
+* emacs-ccls: `(setq ccls-extra-init-params '(:clang (:extraArgs ["-isystem", "/tmp/include"])))`
+
 ### `-std=c++1z` `-std=c++17` `bits/unordered_map.h`
 
-In C++17 mode, it is likely to cause libclang to crash when `bits/unordered_map.h` is indexed.
+In C++17 mode, it is possible to cause clang to crash when `bits/unordered_map.h` is indexed.
 See https://bugs.llvm.org/show_bug.cgi?id=37695 for details.
 The workaround is to add `-D__cpp_deduction_guides=0 -Wno-macro-redefined` to the initialization option `clang.extraArgs`
 
@@ -59,15 +67,16 @@ In Emacs, it is:
 [emacs-ccls](https://github.com/MaskRay/emacs-cquery/) locates the project root with `ccls-project-root-matchers`:
 
 * `.ccls-root`. If this file exists in any parent directory, that directory is treated as the project root.
-* `projectile-project-root`. Then this function is called. You likely don't want `/usr/include/c++/8/algorithm` to be treated as in the project `/usr/include/c++/8/`, `(setq projectile-require-project-root t)` inhibit the behavior.
+* `(projectile-project-root)`. Then this function is called. You likely don't want `/usr/include/c++/8/algorithm` to be treated as in the project `/usr/include/c++/8/`, `(setq projectile-require-project-root t)` inhibits the behavior.
 
-Then ccls will find `.ccls` or `compile_commands.json` in the root directory.
+The root directory is sent to ccls (the language server) through the `rootUri` field in the `initialize` request.
+ccls finds `.ccls` or `compile_commands.json` in the directory.
 
 ```
 proj
   .ccls-root  # Use this file if you want subproject files to be associated with the root project
   compile_commands.json
-  subproj0
+  subproj0  # without .ccls-root, files will be associated with this root directory
     .git
   subproj1
     .git
@@ -138,11 +147,6 @@ ccls will save a file in `cacheDirectory`:
   ...
 ```
 
-### System header completion
-
-* `print '%clang\n%cpp -std=gnu++14\n-isystem/usr/include' > .ccls`
-* `(setq ccls-extra-init-params '(:clang (:extraArgs ["-isystem", "/usr/include"])))`
-
 ### AST deserialisation error when precompiled headers are used
 
 Unfortunately, libclang is very picky when it comes to precompiled headers. Even if your system compiler and the bundled libclang are the same versions there will be problems. Namely, to avoid AST deresialisation errors while using PCH, you need to create them with the same toolchain which will be used inside ccls for completions.
@@ -179,7 +183,7 @@ For reference, read [Valloric/ycmd#892](https://github.com/Valloric/ycmd/issues/
 
 * <code>struct <kbd>A</kbd>:B{void <kbd>f</kbd>()override;};</code> lists `B` or `B::f()`
 
-### `$ccls/derived`
+### `textDocument/implementation`
 
 * <code>struct <kbd>B</kbd>{virtual void <kbd>f</kbd>();};</code> derived classes or virtual function overrides
 
@@ -188,20 +192,20 @@ For reference, read [Valloric/ycmd#892](https://github.com/Valloric/ycmd/issues/
 * <code><kbd>A</kbd> <kbd>a</kbd>;</code> lists all instances of user-defined `A`.
 * <code>int <kbd>i</kbd>;</code> lists all instances of `int`.
 
-### [`$ccls/callHierarchy`](https://github.com/MaskRay/cquery/blob/master/src/messages/cquery_call_hierarchy.cc)
+### [`$ccls/callHierarchy`](https://github.com/MaskRay/ccls/blob/master/src/messages/ccls_callHierarchy.cc)
 
 ```elisp
 (ccls-call-hierarchy nil) ; caller hierarchy
 (ccls-call-hierarchy t)   ; callee hierarchy
 ```
 
-### [`$ccls/inheritanceHierarchy`](https://github.com/MaskRay/cquery/blob/master/src/messages/cquery_inheritance_hierarchy.cc)
+### [`$ccls/inheritanceHierarchy`](https://github.com/MaskRay/ccls/blob/master/src/messages/ccls_inheritanceHierarchy.cc)
 
 ```elisp
 (ccls-inheritance-hierarchy nil) ; base hierarchy
 (ccls-inheritance-hierarchy t)   ; derived hierarchy
 ```
 
-### [`$ccls/memberHierarchy`](https://github.com/MaskRay/cquery/blob/master/src/messages/cquery_member_hierarchy.cc)
+### [`$ccls/memberHierarchy`](https://github.com/MaskRay/ccls/blob/master/src/messages/ccls_memberHierarchy.cc)
 
 Recursively list members of a record type. 😂 nobody has implemented UI for the feature. Help wanted!