diff --git a/Build.md b/Build.md index 31eb702..707e9cd 100644 --- a/Build.md +++ b/Build.md @@ -48,14 +48,10 @@ 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)` +* `-DSYSTEM_LIBCLANG=(ON|OFF)` -Enable `SYSTEM_CLANG` if you want to use your own system installation of Clang -instead of downloading Clang during the configure process. This requires you to -have a recent installation of Clang/LLVM installed on your system. Note that -using system Clang is not recommended and there is a higher chance of bugs due -to possible version differences between downloaded Clang and system installed -Clang. +Enable `SYSTEM_LIBCLANG` if you want to link ccls against a system installation +of libclang instead of downloading libclang during the configure process. * `-DCMAKE_PREFIX_PATH="custom_install_path"` @@ -67,15 +63,18 @@ subdirectories containing the required Clang headers and libraries. For example, to use a system installation of Clang on Windows you can add the following option: `-DCMAKE_PREFIX_PATH="C:/Program Files/LLVM"`. -If the 'include' and 'lib' directories reside in two different parent -directories (possible when building LLVM from source) you will have to add both -these directories to CMAKE_PREFIX_PATH separated by a ';' -(`-DCMAKE\_PREFIX\_PATH=";"`). +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 + +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` -My personal config: +MaskRay's config: ```zsh -CXX=clang++ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_LINKER=/usr/bin/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 -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_LINKER=ld.lld -DCMAKE_EXPORT_COMPILE_COMMANDS=On -DSYSTEM_LIBCLANG=On -DCMAKE_PREFIX_PATH="$HOME/Dev/llvm/static-release;$HOME/Dev/llvm/tools/clang" -Brelease -H. +cmake --build release ``` ``` @@ -87,4 +86,4 @@ CXX=clang++ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_LINKER=/usr/bin/ld ├── libclang.so -> libclang.so.7 ├── libclang.so.7 -> libclang.so.7.0 └── libclang.so.7.0 -``` \ No newline at end of file +``` diff --git a/FAQ.md b/FAQ.md index 2fbed1a..1000ab1 100644 --- a/FAQ.md +++ b/FAQ.md @@ -38,13 +38,13 @@ system C/C++ headers can be detected reliably. For Clang resource directory, the `build/debug/lib/clang+llvm-5.0.1-x86_64-linux-gnu-ubuntu-14.04/bin/c-index-test -index-file local /tmp/c/a.cc -isystem/usr/include/c++/7.3.0 -isystemyour_include_path2` -Play with your `-isystem` options until you get a group of options that you can add to [`.ccls`](https://github.com/ccls-project/cquery/wiki/Getting-started#cquery) +Play with your `-isystem` options until you get a group of options that you can add to [`.ccls`](https://github.com/MaskRay/cquery/wiki/Getting-started#cquery) If you want the ccls binary at a specific location use a symlink - do not move the binary itself. ### Project root detection -For C++ projects, `compile_commands.json` is used by [emacs-ccls](https://github.com/ccls-project/emacs-cquery/) to mark the project root. This is usually a symlink to the real `compile_commands.json` in a build directory: +For C++ projects, `compile_commands.json` is used by [emacs-ccls](https://github.com/MaskRay/emacs-cquery/) to mark the project root. This is usually a symlink to the real `compile_commands.json` in a build directory: ``` proj @@ -55,7 +55,7 @@ proj compile_commands.json -> build/compile_commands.json ``` -In this example, the `:rootUri` of the generated C++ file is `proj/build/` because of `proj/build/compile_commands.json`. However, the user wants it to be `proj/`. Customize `ccls-project-root-matchers`. +In this example, the `:rootUri` of the generated C++ file is `proj/build/` because of `proj/build/compile_commands.json`. However, the user wants it to be `proj/`. Customize `MaskRay-root-matchers`. ### Includes @@ -108,6 +108,16 @@ ccls will save a file in `cacheDirectory`: ... ``` +#### AST deserialisation error when precompiled headers are used + +Unfortunately, libclang is very picky when it comes to precompiled headers. Even if your system compiler and the bundled libclang are the same versions there will be problems. Namely, to avoid AST deresialisation errors while using PCH, you need to create them with the same toolchain which will be used inside ccls for completions. + +However, making ccls use precompiled headers doesn't make much sense. Libclang will internally create the precompiled headers, but won't store them on permanent storage, so having precompiled headers upfront only speeds up the initial parse - precompiled headers shouldn't make a difference on subsequent parses. + +Going back to "create precompiled headers with the same toolchain that will be used by ccls", you can still use precompiled headers, but you will be forced to use your system's libclang, not the one bundled with cquery (even though the bundled one is what's tested). + +For reference, read [Valloric/ycmd#892](https://github.com/Valloric/ycmd/issues/892) and [cquery-project/cquery#545](https://github.com/cquery-project/cquery/issues/545). + ### Definitions `textDocument/definition` can be used in many places. Some are current implementation details and may subject to change. @@ -142,20 +152,20 @@ ccls will save a file in `cacheDirectory`: * A a; lists all instances of user-defined `A`. * int i; lists all instances of `int`. -### [`$ccls/callHierarchy`](https://github.com/ccls-project/cquery/blob/master/src/messages/cquery_call_hierarchy.cc) +### [`$ccls/callHierarchy`](https://github.com/MaskRay/cquery/blob/master/src/messages/cquery_call_hierarchy.cc) ```elisp (ccls-call-hierarchy nil) ; caller hierarchy (ccls-call-hierarchy t) ; callee hierarchy ``` -### [`$ccls/inheritanceHierarchy`](https://github.com/ccls-project/cquery/blob/master/src/messages/cquery_inheritance_hierarchy.cc) +### [`$ccls/inheritanceHierarchy`](https://github.com/MaskRay/cquery/blob/master/src/messages/cquery_inheritance_hierarchy.cc) ```elisp (ccls-inheritance-hierarchy nil) ; base hierarchy (ccls-inheritance-hierarchy t) ; derived hierarchy ``` -### [`$ccls/memberHierarchy`](https://github.com/ccls-project/cquery/blob/master/src/messages/cquery_member_hierarchy.cc) +### [`$ccls/memberHierarchy`](https://github.com/MaskRay/cquery/blob/master/src/messages/cquery_member_hierarchy.cc) -Recursively list members of a record type. 😂 nobody has implemented UI for the feature. Help wanted! \ No newline at end of file +Recursively list members of a record type. 😂 nobody has implemented UI for the feature. Help wanted! diff --git a/Getting-started.md b/Getting-started.md index 40a7ee9..5e30a89 100644 --- a/Getting-started.md +++ b/Getting-started.md @@ -50,4 +50,7 @@ you cannot use `` `command` `` or space-separated arguments like `%cpp -std=gnu+ ### Windows -`-fms-extensions -fms-compatibility -fdelayed-template-parsing` in clang-cl mode. \ No newline at end of file +If your project is compiled with MSVC, you may change the compiler driver to `clang-cl`, and use the initialization option `extraClangArguments` pass three options: +`-fms-extensions -fms-compatibility -fdelayed-template-parsing`. + +See https://clang.llvm.org/docs/MSVCCompatibility.html diff --git a/compile_commands.json.md b/compile_commands.json.md index 156ae17..c6b7755 100644 --- a/compile_commands.json.md +++ b/compile_commands.json.md @@ -97,4 +97,8 @@ with open(os.path.join(sys.argv[1], 'compile_commands.json')) as f: wget 'https://git.archlinux.org/svntogit/packages.git/plain/trunk/config?h=packages/linux' -O .config yes '' | make config bear make -j bzImage modules -``` \ No newline at end of file +``` + +## Misc + +`compile_commands.json` should reside in the project root. Set the initialization option `compilationDatabaseDirectory` for an alternative directory containing `compile_commands.json`.