.

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,16 +37,16 @@ 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
 
 ccls filters and sorts completions to try to be nicer to clients that can't handle big numbers of completion candidates. This behaviour can be disabled by specifying `false` for the option.
 
-This option is the most useful for LSP clients that implement their own filtering and sorting logic.
+This option is the most useful for LSP clients that implement their own filtering and sorting logic.