system search directories

Customization.md

@@ -142,6 +142,8 @@ Every index action is counted: the initial load, a save action.
 
 Default: _empty_
 
+The clang resource directory (something like `.../lib/clang/9.0.0`) is hard-coded into ccls at compile time. You should be able to find `<resourceDir>/include/stddef.h`. Set this option to a non-empty string to override the hard-coded value.
+
 Use the path provided as the Clang resource directory rather the default.  See
 [Clang Resource Directory](Install#clang-resource-directory) for more
 information.

FAQ.md

@@ -78,14 +78,24 @@ No. https://github.com/MaskRay/ccls/issues/110
 
 ## Some C/C++ headers are not recognized
 
-First, if you are Emacs `company` mode user make sure company-lsp is used: run
-<kbd>M-x</kbd> `company-diag` and make sure`Used backend:` includes
-`company-lsp`.
+Read on if you see bogus diagnostics like the following:
 
-#### Checking header locations
+```
+'stddef.h' file not found
+'stdio.h' file not found
+'iostream' file not found
+use of undeclared identifier 'std'
+```
 
-There are at least three sets of implicit include paths. They take effect
-without your `-I` option in `.ccls` or `compile_commands.json`
+ccls infers system search paths (e.g. `/usr/include`, `/usr/include/c++/9`). The underneath mechanism is provided by clang and the result should be similar to the output of `clang -v -fsyntax-only -x c++ /dev/null`.
+On Linux, if the `clang` command does not print useful search paths, it usually indicates that gcc/g++ is not installed at well-known paths.
+
+For example, if you have `gcc-7`, `g++-7` and `gcc-8` installed (note the omission of `g++-8`).  clang may pick the gcc toolchain with the largest version number. The absence of `g++-8` (actually `libstdc++-8-dev` on Debian) will lead to the issue of unrecognized C++ headers.
+
+#### A simple test
+
+Create a temporary directory. Run `git init; touch .ccls`.
+Create `a.cc`:
 
 ```c++
 // a.cc
@@ -97,9 +107,8 @@ without your `-I` option in `.ccls` or `compile_commands.json`
 #include <stddef.h>
 ```
 
-Put `a.cc` in some directory with `echo clang++ > .ccls`. Open the file, you
-should be able to jump to `stdio.h` `new` `stddef.h` when you trigger
-`textDocument/definition` on the include lines.
+Open `a.cc` in your editor, you should be able to jump to `stdio.h` `new`
+`stddef.h` when you trigger `textDocument/definition` on the include lines.
 
 Note that this might not work on Windows. To solve this, add the system
 include directories to compile_commands.json via your build system of choice
@@ -110,35 +119,30 @@ For CMake this can be achieved in a single line: `target_include_directories(<ta
 
 #### Verify the Clang Resource Directory is correct
 
-The clang resource directory is hard-coded into ccls at compile time.
+See [Install#clang-resource-directory](Install#clang-resource-directory).
 
-Use the `--log-file` command line option to generate a log file and look for
-the line `initialize.cc:nnn I use -resource-dir=<path>`.  Make sure the path
-`<path>` still exists and you can locate the file `<path>/include/stddef.h`.
+## Cross compiled projects
 
-If not, then you need to use the
-[`clang.resourceDir`](Customization#clangresourcedir) initialization option to
-tell `ccls` where to find the Clang resource directory.  See also
-[Clang Resource Directory](Install#clang-resource-directory).
+Check if the search directories of
+`clang -v -fsyntax-only -x c++ /dev/null -target aarch64-linux-gnu`
+match
+`aarch64-linux-gnu-g++ -v -fsyntax-only -x c++ /dev/null`.
 
-#### `-isystem`
+If not, add some missing directories via `-isystem`. Example [`.ccls` file](Project-Setup#ccls-file) :
 
-ccls infers system search paths (e.g. `/usr/include`). The underneath
-mechanism is similar to that of `clang -v -E -x c++ /dev/null`.
-
-Adding system include paths is usually unnecessary, but when cross-compiling
-or in some odd situations 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`.
-
-`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 the [`.ccls` file](Project-Setup#ccls-file) or add through
-`clang.extraArgs`.
+```
+-target
+aarch64-linux-gnu
+-isystem/usr/aarch64-linux-gnu/include/c++/9
+-isystem/usr/lib/gcc-cross/aarch64-linux-gnu/9/include
+```
 
 ## Inspect index files
 
+The `c-index-test` utility shipped with the clang package can give you insights what entities will be indexed:
+`c-index-test -index-file local /tmp/c/a.cc -isystem/usr/include/c++/7.3.0 -isystemyour_include_path2`
+(ccls indexes more entities but the underneath mechanisms are similar).
+
 If you need to inspect the contents of the index files, use
 [`cacheFormat`](Customization#cacheformat) to specify JSON output format.
 

lsp-mode.md

@@ -200,6 +200,8 @@ Add `company-lsp` to `company-backends`. ccls has a fuzzy matching algorithm to
 
 ![company-lsp + company-quickhelp](https://ptpb.pw/AC6J.jpg)
 
+If completion does not work for you, make sure company-lsp is used: run <kbd>M-x</kbd> `company-diag` and make sure`Used backend:` includes `company-lsp`.
+
 ### Semantic highlighting
 
 To enable semantic highlighting: