index.initialBlacklist

Getting-started.md

@@ -6,29 +6,30 @@
 
 ### Build the ccls language server
 
-If you are on Linux, building requires libstdc++ shipped with GCC > 7 for good support of C++17 header files, even if you use clang++.
+* On Linux, building requires libstdc++ shipped with GCC > 7.0 for C++17 header files, even if you use clang++.
+* Mac OS X >= 10.12, older versions do not provide `shared_mutex` in libc++
 
-Below are the quick commands for the impatient. Detailed instructions can be found at [[Build]].
+Below are quick commands for the impatient. Detailed instructions can be found at [[Build]].
 
 ```zsh
 git clone https://github.com/MaskRay/ccls --depth=1
 cd ccls
 git submodule update --init
-cmake -H. -BRelease
+cmake -H. -BRelease # This downloads prebuilt clang+llvm from releases.llvm.org
 cmake --build Release
 ```
 
 The executable is at `Release/ccls`.
 
-FreeBSD and some Linux distributions provide system clang. You may use `-DSYSTEM_CLANG=on`.
+You may use `-DSYSTEM_CLANG=on` if you have clang and llvm installed somewhere.
 But caution is that you need to identify whether the clang library is compiled with `-DLLVM_ENABLE_RTTI=on`
 
 * Arch Linux
-  + [aur/ccls-git](https://aur.archlinux.org/packages/ccls-git). There was a [SIGSEGV issue](https://github.com/MaskRay/ccls/issues/30) which has been fixed.
+  + [aur/ccls-git](https://aur.archlinux.org/packages/ccls-git). There was a [SIGSEGV issue caused by LLVM_ENABLE_RTTI](https://github.com/MaskRay/ccls/issues/30) which has been fixed.
   + `cmake -H. -BRelease -DSYSTEM_CLANG=on -DUSE_SHARED_LLVM=on -DLLVM_ENABLE_RTTI=on`
 * FreeBSD
-  + with `llvm60` installed: `cmake -H. -BRelease -DSYSTEM_CLANG=on -DUSE_SHARED_LLVM=on -DCMAKE_PREFIX_PATH=/usr/local/llvm60`
-  + use libc++: `cmake -H. -BRelease -DCLANG_USE_BUNDLED_LIBC++=on`
+  + with `devel/llvm60`: `cmake -H. -BRelease -DSYSTEM_CLANG=on -DUSE_SHARED_LLVM=on -DCMAKE_PREFIX_PATH=/usr/local/llvm60`
+  + use releases.llvm.org prebuilt archive and its libc++: `cmake -H. -BRelease -DCLANG_USE_BUNDLED_LIBC++=on`
 * Gentoo Linux: `cmake -H. -BRelease -DSYSTEM_CLANG=on -DCMAKE_PREFIX_PATH=/usr/lib/llvm/6 -DLLVM_ENABLE_RTTI=on`
 * Mac OS X
   + Homebrew: https://github.com/twlz0ne/homebrew-ccls
@@ -38,7 +39,7 @@ But caution is that you need to identify whether the clang library is compiled w
 Debian: `apt install zlib1g-dev`
 
 * Install g++-7 on Ubuntu 16.04: https://gist.github.com/jlblancoc/99521194aba975286c80f93e47966dc5
-* `-DUSE_SHARED_LLVM=on` (optional, if you have `libLLVM.so` provided by `-DLLVM_BUILD_LLVM_DYLIB=on`) makes linked executable smaller.
+* `-DUSE_SHARED_LLVM=on` (optional, if you have `libLLVM.so` (provided by a llvm build with `-DLLVM_BUILD_LLVM_DYLIB=on`)) makes linked executable smaller.
 * `-G Ninja` to build with ninja.
 
 ### Setup your editor
@@ -48,15 +49,19 @@ If you use other editors not listed there (LSP decouples servers and clients, so
 
 ### Project setup
 
+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
+
 #### [[compile_commands.json]] (Best)
 
 Remember to copy/symlink it to the project root.
 
 #### `.ccls`
 
-Another way is to create a file named `.ccls` located in the project root. ccls recursively finds source files and indexes them. `.ccls` can also exist in subdirectories which will affect the options in its subtree. *Notice* If you use emacs-ccls, read the document of [`ccls-project-root-matchers`](https://github.com/MaskRay/ccls/wiki/FAQ#project-root-detection) to locate the project root correctly.
+Alternatively, create a file named `.ccls` located in the project root. Easy to use for simple projects.
 
-If `%clang` is used, it expands to `clang/clang++` according to the extension name. Prefix options with `%c ` or `%cpp ` to make it specific to C or C++.
+ccls recursively finds source files and indexes them. 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++.
 
 Example `.ccls`:
 
@@ -71,14 +76,11 @@ Example `.ccls`:
 -I/work/ccls/another_third_party
 # -I space_is_not_allowed
 ```
+
 Note:
 `.ccls` does not do *word splitting* or *command substitution* for you,
 you cannot use space-separated arguments like `%cpp -std=gnu++14 -pthread`
 
-### Linux
-
-If your project uses `-std=c++1z` `-std=c++17`, you likely need to add `-D__cpp_deduction_guides=0 -Wno-macro-redefined` to the initialization option `clang.extraArgs`. See [[FAQ]] for details.
-
 ### 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:
@@ -90,7 +92,7 @@ See https://clang.llvm.org/docs/MSVCCompatibility.html
 
 On a laptop with one (i7-6600U CPU @ 2.60GHz, hyper-threading, `nproc`=4), 4 indexers.
 
-llvm+clang+extra+lld+compiler-rt (2017-06-10)
+llvm+clang+extra+lld+compiler-rt (2018-06-10)
 
 * initial indexing: 1 hour; load: 20s
 * resident set size is about 1GiB (the peak RSS during indexing is below 2GiB)

Initialization-options.md

@@ -90,6 +90,10 @@ You usually want to use `index.multiVersionBlacklist` to exclude system headers.
 }
 ```
 
+## `index.initialBlacklist`
+
+Files that should not be loaded on initialization, but will still be indexed after you open them.
+
 ## `index.onChange`: re-index for every change
 
 Default: `false`