Rework Project-Setup.md

Project-Setup.md

@@ -1,11 +1,38 @@
+ccls typically indexes an entire project. In order for this to work properly,
+`ccls` needs to be able to obtain the source file list and their compilation
+command lines.
+
+There are two main ways this happens:
+
+1. Provide `compile_commands.json` at the project root
+2. Provide `.ccls`. It is a line-based text file describing compiler flags.
+   Recursively listed source files (headers excluded) will be indexed.
+
+If neither exists, then when ccls starts it will not index anything: instead it
+will wait for LSP clients to open files and index only those files.
+
+## `compile_commands.json`
+
 [Guillaume Papin(@Sarcasm)](https://github.com/sarcasm) has [a thorough article about compilation databases](https://sarcasm.github.io/notes/dev/compilation-database.html).
 
+Generally this file is not checked into source control, but rather is
+generated by the build system.  This means it's best to generate it in a new
+project before starting the `ccls` server in that project.
+
+Because this file is auto-generated it's not easy to customize.  As a result
+it's possible to provide _both_ `compile_commands.json` _and_ `.ccls` in the
+same project and have the `.ccls` configuration enhance the options from
+`compile_commands.json`.
+
+If your `compile_commands.json` is not kept in the project root, set the
+initialization option `compilationDatabaseDirectory` to an alternative
+directory containing `compile_commands.json`.
+
 ### [CMake](https://cmake.org/)
 
 ```zsh
-% mkdir build
-% (cd build; cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=YES ..)
-% ln -s build/compile_commands.json
+% cmake -H. -BDebug -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=YES
+% ln -s Debug/compile_commands.json
 ```
 
 Caveat on Windows: CMake dumps Windows shell command line directly into `command`, depends on how ccls was built, it may confuse this field as command line from a POSIX shell, in which Windows path separator '\\' is a escape character. You can use jq to convert such entries to use `arguments` which does not have this issue:
@@ -70,7 +97,7 @@ You may use the initialization option `"compilationDatabaseCommand"` to provide
 ```
 
 ```elisp
-(setq ccls-extra-init-params '(:compilationDatabaseCommand "mycompdb"))
+(setq ccls-initialization-options '(:compilationDatabaseCommand "mycompdb"))
 ```
 
 Suppose the project is at `/tmp/c`, `mycompdb /tmp/c` will be executed with stdin=initializationOptions and the stdout should be a JSON compilation database.
@@ -104,7 +131,72 @@ with open(os.path.join(sys.argv[1], 'compile_commands.json')) as f:
     json.dump(db, sys.stdout)
 ```
 
-## Examples
+## `.ccls`
+
+`.ccls` is a line-based text file at the project root.  It's main function is
+to specify compiler flags needed to properly index your code: `-I` `-D` etc.
+Each line consists of one argument. No whitespace splitting is performed on the
+argument, thus `-I foo` cannot be used (use `-Ifoo` or `-I\nfoo`).
+
+Subdirectories of the project can also contain `.ccls` files, if needed, to
+specify compiler flags specific to those directories.
+
+A line may start with zero or more `%` directives.
+
+Available directives include:
+
+### `%compile_commands.json`
+
+By default `.ccls` specify compiler flags of files not listed in
+`compile_commands.json`.  If this directive appears first in `.ccls` then after
+`compile_commands.json` is parsed, the rest lines of `.ccls` will be appended
+to the compiler flags.
+
+### `%clang`
+
+Resolves to either `clang` (C) or `clang++` (C++). This is useful if your
+project has both C and C++ source files, because if unconditional `clang++` is
+used instead, `clang++ a.c` parses `a.c` as C++.
+
+### `%c` / `%cpp` / `%objective-c` / `%objective-cpp`
+
+This argument should be added only when parsing C (`%c`), C++ (`%cpp`),
+Objective-C (`%objective-c`), or Objective-C++ (`%objective-c++`) files.
+
+### `%h` / `%hpp`
+
+This argument should be added only when indexing C header files (`%h`: `*.h`) or C++
+header files (`%hpp`: `*.hh` `*.hpp`). Note, `*.h` files are considered as C, not C++.
+
+## `.ccls` examples
+
+#### Example A
+
+```
+%clang
+%c -std=c11
+%cpp -std=c++2a
+%h %hpp --include=Global.h
+-Iinc
+-DMACRO
+````
+
+`*.h *.hh *.hpp` files will be parsed with extra `--include=Global.h`
+
+#### Example B
+
+```
+%compile_commands.json
+%c -std=c11
+%cpp -std=c++14
+%c %cpp -pthread
+%h %hpp --include=Global.h
+-Iinc
+```
+
+It appends flags so `%clang` should not be used.
+
+## `compile_commands.json` examples
 
 ### Linux kernel
 
@@ -130,7 +222,3 @@ mkdir Debug; cd Debug
 bear make -j
 cd ..; ln -s Debug/compile_commands.json
 ```
-
-## Misc
-
-`compile_commands.json` should reside in the project root. Set the initialization option `compilationDatabaseDirectory` for an alternative directory containing `compile_commands.json`.

_Sidebar.md

@@ -1,10 +1,6 @@
-* [[Home]]
-  - [[Getting started]]
-  - [[Build]]
-  - [[compile_commands.json]]
-  - [[Initialization options]]
-  - [[FAQ]]
-* Editor configuration
+[[Home]]
+* [[Build]]
+* [[Editor Configuration]]
   - [[Atom]]
   - Emacs
     + [[lsp-mode]] (+ emacs-ccls)
@@ -14,6 +10,8 @@
     + [[LanguageClient-neovim]]
     + [[vim-lsp]]
   - [[Visual Studio Code]]
+* [[Project Setup]]
+* [[Customization]]
 * [[Debugging]]
-* [[Client feature table]]
+* [[FAQ]]
 * [[LSP]]