Zengtudor/ccls
1
0
Fork 0
mirror of https://github.com/MaskRay/ccls.git synced 2024-11-26 09:31:59 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

.ccls extension

Fangrui Song 2018-12-22 14:29:52 -08:00
parent 0b227cd7a0
commit 90f42ef3b7
1 changed files with 26 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
Getting-started.md

@ -1,10 +1,10 @@
### Outline ## Outline
1. Build ccls / prebuilt binary (below) 1. Build ccls / prebuilt binary (below)
2. Setup your editor 2. Setup your editor
3. Project setup: project root detect and generate `compile_commands.json` or `.ccls` 3. Project setup: project root detect and generate `compile_commands.json` or `.ccls`
### Build the ccls language server ## Build the ccls language server
* cmake >= 3.8 for C++17 support * cmake >= 3.8 for C++17 support
* On Linux, building requires libstdc++ shipped with GCC >= 7.3 for C++17 header files, even if you use clang++. * On Linux, building requires libstdc++ shipped with GCC >= 7.3 for C++17 header files, even if you use clang++.
@ -43,18 +43,18 @@ But caution is that you need to identify whether the clang library is compiled w
* glibc < 2013-04-25 (e.g. RHEL 6 with modern GCC) * glibc < 2013-04-25 (e.g. RHEL 6 with modern GCC)
+ `-DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS` + `-DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS`
### Setup your editor ## Setup your editor
Find your editor from the sidebar under the section "Editor configuration". Find your editor from the sidebar under the section "Editor configuration".
If you use other editors not listed there (LSP decouples servers and clients, so every language client should work), make sure to configure `cacheDirectory` in [[Initialization options]]. If you use other editors not listed there (LSP decouples servers and clients, so every language client should work), make sure to configure `cacheDirectory` in [[Initialization options]].
### Project setup ## Project setup
#### Root Detection ### Root Detection
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 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
#### Parameters Configuration ### Parameters Configuration
There are several ways you can choose. There are several ways you can choose.
1. [[compile_commands.json]] 1. [[compile_commands.json]]
@ -63,9 +63,10 @@ Remember to copy/symlink it to the project root.
2. `.ccls` 2. `.ccls`
Alternatively, create a file named `.ccls` located in the project root. Easy to use for simple projects. If `.ccls` is located in the project root, ccls recursively finds source files and indexes them.
`.ccls` can be empty (files will be parsed as `%clang $filename`) or contain compiler command line options including the compiler driver (`gcc/cc/clang/...`) minus the filename.
ccls recursively finds source files and indexes them. Subdirectories can include `.ccls` files to affect compiler options in its subtree. 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++. 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++.
@ -74,14 +75,12 @@ Example `.ccls`:
``` ```
%clang %clang
%c -std=gnu11 %c -std=gnu11
%cpp -std=gnu++14 %cpp -std=gnu++17
%objective-c %objective-cpp -DGNUSTEP %objective-c %objective-cpp -DGNUSTEP
%c %cpp -DFOO %c %cpp -DC_OR_CXX
-pthread -pthread
# Includes
-I/work/ccls/third_party -I/work/ccls/third_party
-I/work/ccls/another_third_party
# -I space_is_not_allowed # -I space_is_not_allowed
``` ```
@ -89,20 +88,31 @@ Note:
`.ccls` does not do *word splitting* or *command substitution* for you, `.ccls` does not do *word splitting* or *command substitution* for you,
you cannot use space-separated arguments like `%cpp -std=gnu++14 -pthread` you cannot use space-separated arguments like `%cpp -std=gnu++14 -pthread`
If the first line of `.ccls` is `%compile_commands.json`, it appends flags to `compile_commands` "arguments", instead of overriding. Example:
```
%compile_commands.json
-DEXTRA_MACRO
%h %hpp --include=types.h
```
Like `%c` `%cpp`, `%h` denotes flags for `.h`, while `%hpp` is for `.hh` `.hpp` `.hxx`.
This is useful for header files that are not self-contained, see [[FAQ#diagnostics-in-headers]].
3. No `.ccls` or `compile_commands.json` 3. No `.ccls` or `compile_commands.json`
If neither file exists, ccls assumes there is an imaginary `.ccls` with one line: `%clang`. If neither file exists, ccls does not index any file when started. Opened files will still be indexed, and they will be parsed as `%clang $filename`.
This is convenient for trying out a one-file project. `git init` to let the language client know it is a project, e.g. `cd /tmp; mkdir c; cd c; git init; touch a.cc` This is convenient for trying out a one-file project. `git init` to let the language client know it is a project, e.g. `cd /tmp; mkdir c; cd c; git init; touch a.cc`
### Windows ## 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: 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:
`-fms-extensions -fms-compatibility -fdelayed-template-parsing`. `-fms-extensions -fms-compatibility -fdelayed-template-parsing`.
See https://clang.llvm.org/docs/MSVCCompatibility.html See https://clang.llvm.org/docs/MSVCCompatibility.html
### Standalone mode ## Standalone mode
ccls indexer can be used standalone. The following command indexes the project and creates `~/llvm/.ccls-cache/`. ccls indexer can be used standalone. The following command indexes the project and creates `~/llvm/.ccls-cache/`.
If you have `clang.extraArgs`, make sure your client uses the same initialization option, otherwise cflags mismatch will cause re-indexing. If you have `clang.extraArgs`, make sure your client uses the same initialization option, otherwise cflags mismatch will cause re-indexing.
@ -111,7 +121,7 @@ If you have `clang.extraArgs`, make sure your client uses the same initializatio
ccls -index ~/llvm -init='{"clang":{"extraArgs": ["--gcc-toolchain=/usr"]}}' ccls -index ~/llvm -init='{"clang":{"extraArgs": ["--gcc-toolchain=/usr"]}}'
``` ```
### Cases ## Cases
On a laptop with one (i7-6600U CPU @ 2.60GHz, hyper-threading, `nproc`=4), 4 indexers. On a laptop with one (i7-6600U CPU @ 2.60GHz, hyper-threading, `nproc`=4), 4 indexers.