.ccls extension

Getting-started.md

@@ -1,10 +1,10 @@
-### Outline
+## Outline
 
 1. Build ccls / prebuilt binary (below)
 2. Setup your editor
 3. Project setup: project root detect and generate `compile_commands.json` or `.ccls`
 
-### Build the ccls language server
+## Build the ccls language server
 
 * cmake >= 3.8 for C++17 support
 * On Linux, building requires libstdc++ shipped with GCC >= 7.3 for C++17 header files, even if you use clang++.
@@ -43,18 +43,18 @@ But caution is that you need to identify whether the clang library is compiled w
 * glibc < 2013-04-25 (e.g. RHEL 6 with modern GCC)
   + `-DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS`
 
-### Setup your editor
+## Setup your editor
 
 Find your editor from the sidebar under the section "Editor configuration".
 If you use other editors not listed there (LSP decouples servers and clients, so every language client should work), make sure to configure `cacheDirectory` in [[Initialization options]].
 
-### Project setup
+## Project setup
 
-#### Root Detection
+### Root Detection
 
 If your project has subprojects (e.g. separate repos), some setup in your editor is needed for proper root detection: https://github.com/MaskRay/ccls/wiki/FAQ#project-root-detection
 
-#### Parameters Configuration
+### Parameters Configuration
 There are several ways you can choose.
 
 1. [[compile_commands.json]]
@@ -63,9 +63,10 @@ Remember to copy/symlink it to the project root.
 
 2. `.ccls`
 
-Alternatively, create a file named `.ccls` located in the project root. Easy to use for simple projects.
+If `.ccls` is located in the project root, ccls recursively finds source files and indexes them.
+`.ccls` can be empty (files will be parsed as `%clang $filename`) or contain compiler command line options including the compiler driver (`gcc/cc/clang/...`) minus the filename.
 
-ccls recursively finds source files and indexes them. Subdirectories can include `.ccls` files to affect compiler options in its subtree.
+Subdirectories can include `.ccls` files to affect compiler options in its subtree.
 
 If `%clang` is used, it expands to `clang` or `clang++` according to the extension name. Prefix options with `%c ` or `%cpp ` to make it specific to C or C++.
 
@@ -74,14 +75,12 @@ Example `.ccls`:
 ```
 %clang
 %c -std=gnu11
-%cpp -std=gnu++14
+%cpp -std=gnu++17
 %objective-c %objective-cpp -DGNUSTEP
-%c %cpp -DFOO
+%c %cpp -DC_OR_CXX
 -pthread
 
-# Includes
 -I/work/ccls/third_party
--I/work/ccls/another_third_party
 # -I space_is_not_allowed
 ```
 
@@ -89,20 +88,31 @@ Note:
 `.ccls` does not do *word splitting* or *command substitution* for you,
 you cannot use space-separated arguments like `%cpp -std=gnu++14 -pthread`
 
+If the first line of `.ccls` is `%compile_commands.json`, it appends flags to `compile_commands` "arguments", instead of overriding. Example:
+
+```
+%compile_commands.json
+-DEXTRA_MACRO
+%h %hpp --include=types.h
+```
+
+Like `%c` `%cpp`, `%h` denotes flags for `.h`, while `%hpp` is for `.hh` `.hpp` `.hxx`.
+This is useful for header files that are not self-contained, see [[FAQ#diagnostics-in-headers]].
+
 3. No `.ccls` or `compile_commands.json`
 
-If neither file exists, ccls assumes there is an imaginary `.ccls` with one line: `%clang`.
+If neither file exists, ccls does not index any file when started. Opened files will still be indexed, and they will be parsed as `%clang $filename`.
 
 This is convenient for trying out a one-file project. `git init` to let the language client know it is a project, e.g. `cd /tmp; mkdir c; cd c; git init; touch a.cc`
 
-### Windows
+## Windows
 
 If your project is compiled with MSVC, you may change the compiler driver (`%clang` above) to `clang-cl`, and use the initialization option `clang.extraArgs` to pass three options:
 `-fms-extensions -fms-compatibility -fdelayed-template-parsing`.
 
 See https://clang.llvm.org/docs/MSVCCompatibility.html
 
-### Standalone mode
+## Standalone mode
 
 ccls indexer can be used standalone. The following command indexes the project and creates `~/llvm/.ccls-cache/`.
 If you have `clang.extraArgs`, make sure your client uses the same initialization option, otherwise cflags mismatch will cause re-indexing.
@@ -111,7 +121,7 @@ If you have `clang.extraArgs`, make sure your client uses the same initializatio
 ccls -index ~/llvm -init='{"clang":{"extraArgs": ["--gcc-toolchain=/usr"]}}'
 ```
 
-### Cases
+## Cases
 
 On a laptop with one (i7-6600U CPU @ 2.60GHz, hyper-threading, `nproc`=4), 4 indexers.