From 27d6b87b0bd998203d8605a890658773cd530c86 Mon Sep 17 00:00:00 2001 From: Fangrui Song Date: Fri, 11 May 2018 22:05:29 -0700 Subject: [PATCH] . --- Build.md | 70 +++++++++++++++++---------------------- Emacs.md | 2 -- Getting-started.md | 7 +++- Initialization-options.md | 12 +++---- 4 files changed, 43 insertions(+), 48 deletions(-) diff --git a/Build.md b/Build.md index 41edd6f..6e1e779 100644 --- a/Build.md +++ b/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. - -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 .`) +against the libclang library which it downloads from . ## CMake Options -CMake options can be specified when running CMake to change its behaviour. -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|MinSizeRel|Release|RelWithDebInfo)` -* `-DCMAKE_BUILD_TYPE=(Debug|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. +Set the build type. The most important ones are Debug and Release. * `-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. -``` \ No newline at end of file diff --git a/Emacs.md b/Emacs.md index 46eca52..6e0b81b 100644 --- a/Emacs.md +++ b/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 diff --git a/Getting-started.md b/Getting-started.md index 78556d6..b9934ba 100644 --- a/Getting-started.md +++ b/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 diff --git a/Initialization-options.md b/Initialization-options.md index a0a27d7..bdcb406 100644 --- a/Initialization-options.md +++ b/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. \ No newline at end of file +This option is the most useful for LSP clients that implement their own filtering and sorting logic.