.

Build.md

@@ -1,7 +1,3 @@
-ccls has experimental support for the CMake build system.
-
-To get started building ccls, first install the required dependencies:
-
 * CMake 3.1 or higher
 * C++ Compiler with C++17 support:
   * Clang 5 or higher
@@ -12,15 +8,12 @@ After installing the required dependencies, clone the repository along with its
 git submodules using:
 `git clone https://github.com/MaskRay/ccls --recursive`
 
-After cloning the repository, open a terminal and navigate to the ccls 
-directory. Then, create a build directory which will contain all files 
-related to the build. Enter the build directory.
-
-From inside the build directory, we can then configure the project with the
-following command:
-
 ```
-$ cmake .. -DCMAKE_INSTALL_PREFIX=release -DCMAKE_EXPORT_COMPILE_COMMANDS=YES
+# create a build directory called `release`
+% cmake -H. -Brelease
+
+# build
+% cmake --build release
 ```
 
 [**Windows**] On Windows you have to explicitly tell CMake to target 64-bit
@@ -30,34 +23,33 @@ are not supported at the moment.
 
 This command generates project files for your system's default generator (Linux:
 make, Windows: MSBuild). CMake defaults to a Release build and links ccls
-against the libclang library which it downloads from https://releases.llvm.org.
+against the libclang library which it downloads from <https://releases.llvm.org>.
-
-After CMake configuration ccls can be built from inside the build directory by
-executing the corresponding generator command (Linux: `make`, Windows:
-`MSBuild.exe`) or the generic CMake build command (`cmake --build .`)
 
 ## CMake Options
 
-CMake options can be specified when running CMake to change its behaviour.
+* `-DCMAKE_BUILD_TYPE=(Debug|MinSizeRel|Release|RelWithDebInfo)`
-Options are passed to CMake via the command line by prepending them with -D. For
-example: `cmake -DCMAKE_BUILD_TYPE=Debug ..` configures ccls to be built in
-release mode.
 
-* `-DCMAKE_BUILD_TYPE=(Debug|Release)`
+Set the build type. The most important ones are Debug and Release.
-
-`CMAKE_BUILD_TYPE` can be used to set the build type. There are a few possible
-options, but the most important ones are Debug and Release. Generally you want
-to pass `-DCMAKE_BUILD_TYPE=Release` to CMake to get the best performance out of
-ccls. Debug is recommended when debugging cquery with a debugger. Since cquery
-defaults to a Release build it usually isn't necessary to define this option
-unless you're debugging an issue in ccls with a debugger.
 
 * `-DSYSTEM_CLANG=(ON|OFF)`
 
 Enable `SYSTEM_CLANG` if you want to link ccls against a system installation
-of Clang instead of downloading Clang during the configure process.
+of Clang instead of downloading Clang from releases.llvm.org during the configure process.
 
-Example: `cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr -DSYSTEM_CLANG=On -Brelease -H. && cmake --build release`
+```
+% cmake -H. -Brelease -DCMAKE_INSTALL_PREFIX=/usr -DSYSTEM_CLANG=On
+% cmake --build release
+```
+
+* `-DCLANG_USE_BUNDLED_LIBC++=on`
+
+`libstdc++ >= 5.3` supports `experimental/filesystem`. If your `libstdc++` is old, you can use `libc++` in the bundled clang+llvm archive:
+
+```zsh
+# If your clang++ is old, you may rerun this command with clang++ replaced to
+# the absolute path of bundled/clang+llvm-*/bin/clang++
+cmake -H. -Brelease -G Ninja -DCMAKE_CXX_COMPILER=clang++ -DCLANG_USE_BUNDLED_LIBC++=on
+```
 
 * `-DCMAKE_PREFIX_PATH="custom_install_path"`
 
@@ -77,12 +69,18 @@ You may add directories for `include` and `lib` separated by a `;`, e.g. to use
 If using Windows the automatically downloaded LLVM binaries are 64-bit; you should build cquery in 64-bit as well. You can tell cmake to build 64-bit using `-DCMAKE_GENERATOR_PLATFORM=x64`
 
 
-MaskRay's config (building trunk LLVM at `~/Dev/llvm/static-release/` to get read/write/addr references and other features):
+MaskRay's config (building trunk LLVM at `~/Dev/llvm/static-release/`):
 ```zsh
-cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld -DCMAKE_EXPORT_COMPILE_COMMANDS=On -DSYSTEM_CLANG=On -DCMAKE_PREFIX_PATH="$HOME/Dev/llvm/static-release;$HOME/Dev/llvm/tools/clang" -Brelease -H.
+cmake -H. -Brelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld -DCMAKE_EXPORT_COMPILE_COMMANDS=On -DSYSTEM_CLANG=On -DCMAKE_PREFIX_PATH="$HOME/Dev/llvm/release;$HOME/Dev/llvm/release/tools/clang;$HOME/Dev/llvm;$HOME/Dev/llvm/tools/clang"
 cmake --build release
 ```
 
+`CMAKE_PREFIX_PATH` is specified to point to both source directories (clang and llvm) and build directories (clang and llvm)
+```
+~/Dev/llvm/release/include/llvm/Config/config.h
+~/Dev/llvm/release/tools/clang/include/clang/Config/config.h
+```
+
 ```
 % tree ~/Dev/llvm/static-release/lib/ -L 3
 ├── clang
@@ -93,9 +91,3 @@ cmake --build release
 ├── libclang.so.7 -> libclang.so.7.0
 └── libclang.so.7.0
 ```
-
-If you don't have an up-to-date `libstdc++` and want to use `libc++` in the bundled clang+llvm archive:
-
-```zsh
-cmake -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_CXX_COMPILER=clang++ -DCLANG_USE_BUNDLED_LIBC++=on -Brelease -H.
-```

Emacs.md

@@ -6,8 +6,6 @@
 
 ### Install [emacs-ccls](https://github.com/MaskRay/emacs-ccls)
 
-https://github.com/melpa/melpa/pull/5405
-
 https://melpa.org/#/ccls
 
 ### Configure

Getting-started.md

@@ -12,15 +12,20 @@ Detailed instructions at [[Build]].
 git clone https://github.com/MaskRay/ccls --depth=1
 cd ccls
 git submodule update --init
-mkdir release
 cmake -DCMAKE_BUILD_TYPE=Release -Brelease -H.
 cmake --build release
 ```
 
 The executable is at `release/ccls`.
 
+If your `libstdc++ < 5.3` or have an old GCC/Clang, you may use the `-DCLANG_USE_BUNDLED_LIBC++=on` command at [[Build]].
+
 * Mac OS X: [homebrew-ccls](https://github.com/twlz0ne/homebrew-ccls)
 * Arch Linux: [aur/ccls-git](https://aur.archlinux.org/packages/ccls-git)
+* `cmake -H. -Brelease -DCLANG_USE_BUNDLED_LIBC++=on`
+  + FreeBSD 11, as `base` does not provide `libc++experimental.a`.
+  + Linux with `libstdc++<5.3`, e.g. Ubuntu 16.04
+* `cmake -H. -Brelease`, Linux with newer libstdc++, e.g. Arch Linux
 
 ### Project setup
 

Initialization-options.md

@@ -12,9 +12,9 @@ You can also pass options through the command line option `--init`:
 * shell: `--init='{"enableComments": 2}'` . Single quotes are used to escape words in shell.
 * Emacs: `(setq ccls-extra-init-params '(:enableComments 2 :cacheFormat "msgpack"))`
 
-## `indexerCount` number of indexer threads
+## `index.threads` number of indexer threads
 
-If `indexerCount` is 0, use 80% of `std::thread::hardware_concurrency()`.
+If `index.threads` is 0, use `std::thread::hardware_concurrency()`.
 
 ## `index.comments`: indexing comments
 
@@ -37,13 +37,13 @@ This feature requires UI support as multi-line hover results poses a problem to
 Two cache serialization formats are supported.
 
 ```json
+"cacheFormat": "binary"
 "cacheFormat": "json"
-"cacheFormat": "msgpack"
 ```
 
-`"json"` generates `cacheDirectory/.../xxx.json` files which can be pretty printed with jq.
+`"binary"` uses a compact binary serialization format which typically takes only 60% of the corresponding JSON size, but is difficult to inspect. It does not store map keys and you need to re-index whenever a struct member has changed.
 
-`"msgpack"` uses a compact binary serialization format (the underlying wire format is [MessagePack](https://msgpack.org/index.html)) which typically takes only 60% of the corresponding JSON size, but is difficult to inspect. `"msgpack"` does not store map keys and you need to re-index whenever a struct member has changed.
+`"json"` generates `cacheDirectory/.../xxx.json` files which can be pretty printed with jq.
 
 ## `completion.filterAndSort`: completion filtering and sorting