From 5f1ec8fbb6b72230a3a2d9b0d1688d12088b5e7c Mon Sep 17 00:00:00 2001
From: Fangrui Song <i@maskray.me>
Date: Sun, 13 May 2018 15:14:17 -0700
Subject: [PATCH] .

---
 Build.md           | 38 ++++++++++++++++++++++++++++++++++----
 Getting-started.md |  8 +++-----
 2 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/Build.md b/Build.md
index 329d016..f8a7536 100644
--- a/Build.md
+++ b/Build.md
@@ -34,7 +34,7 @@ of Clang instead of downloading Clang from releases.llvm.org during the configur
 * `-DCLANG_USE_BUNDLED_LIBC++=on`
 
 `clang+llvm*` downloaded from releases.llvm.org also provides libc++ libraries.
-`libstdc++ >= 5.3` supports `experimental/filesystem`. If your `libstdc++` is old, you can use `libc++` in the bundled clang+llvm archive:
+If your `libstdc++` is too 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
@@ -55,23 +55,53 @@ option: `-DCMAKE_PREFIX_PATH="C:/Program Files/LLVM"`.
 You may add directories for `include` and `lib` separated by a `;`, e.g. to use trunk clang:
 `-DCMAKE_PREFIX_PATH="$HOME/Dev/llvm/release;$HOME/Dev/llvm/tools/clang"`
 
-# Windows
+## Windows
 
 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`
 
+## Link against clang+llvm libraries compiled from source
+
+MaskRay's config (building trunk LLVM at `~/Dev/llvm/release/`):
+
+```
+cd ~/Dev
+git clone https://git.llvm.org/git/llvm.git
+cd llvm/tools
+git clone https://git.llvm.org/git/clang.git
+cd ~/Dev
+# create a build directory named `release/`
+cmake -H. -Brelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DBUILD_SHARED_LIBS=ON -DLLVM_ENABLE_LLD=ON -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_TESTS=OFF -DLLVM_INCLUDE_GO_TESTS=OFF -DLLVM_INCLUDE_DOCS=OFF -DLLVM_TARGETS_TO_BUILD=X86 -DLLVM_USE_SPLIT_DWARF=On -DLLVM_OPTIMIZED_TABLEGEN=On
+```
+
+Remove `LLVM_ENABLE_LLD` if don't have lld (a much faster linker than bfd/gold) installed
+Remove `BUILD_SHARED_LIBS` if you want to build static libraries (`libclangDriver.a` `libLLVMSupport.a`, note `libclang.so` is still a shared object)
+
+Then build ccls:
 
-MaskRay's config (building trunk LLVM at `~/Dev/llvm/static-release/`):
 ```zsh
 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)
+There are 4 directories specified in `CMAKE_PREFIX_PATH`:
+
+* `Dev/llvm`: llvm source
+* `Dev/llvm/tools/clang`: clang source (`git clone https://git.llvm.org/git/clang.git`)
+* `Dev/llvm/release`: build directory. `include/` contains some generated llvm header files
+* `Dev/llvm/release/tools/clang`: part of the build directory. `include/` contains some generated clang header files
+
+The cmake build system is expected to find these files:
+
 ```
+# generated clang+llvm header files
 ~/Dev/llvm/release/include/llvm/Config/config.h
 ~/Dev/llvm/release/tools/clang/include/clang/Config/config.h
 # libclang
 ~/Dev/llvm/release/lib/libclang.so
 # -resource-dir
 ~/Dev/llvm/release/lib/clang/7.0.0
+# clang+llvm libraries
+~/Dev/llvm/release/lib/libclangDriver.so
+~/Dev/llvm/release/lib/libLLVMSupport.so
+...
 ```
diff --git a/Getting-started.md b/Getting-started.md
index b9934ba..d1d3664 100644
--- a/Getting-started.md
+++ b/Getting-started.md
@@ -18,14 +18,12 @@ 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]].
+If your `libstdc++` is too old (no C++17 header files) 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
+* `cmake -H. -Brelease -DCLANG_USE_BUNDLED_LIBC++=on`, e.g. FreeBSD 11
+* `cmake -H. -Brelease`, Linux with newer libstdc++, e.g. Arch Linux, FreeBSD 12
 
 ### Project setup