Zengtudor/ccls
1
0
Fork 0
mirror of https://github.com/MaskRay/ccls.git synced 2024-11-22 07:35:08 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Delete Getting-started.md

Fangrui Song 2019-01-04 01:11:49 +08:00
parent e7a4a1f900
commit 2750118be1
5 changed files with 9 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
Getting-started.md

@ -1,145 +0,0 @@
## Outline
1. Build ccls / prebuilt binary (below)
2. Setup your editor
3. Project setup: project root detect and generate `compile_commands.json` or `.ccls`
## Build the ccls language server
* 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++.
* Mac OS X >= 10.12, older versions do not provide `shared_mutex` in libc++
Below are quick commands for the impatient. Detailed instructions can be found at [[Build]].
```zsh
git clone --depth=1 --recursive https://github.com/MaskRay/ccls
cd ccls
cmake -H. -BRelease # This downloads prebuilt clang+llvm from releases.llvm.org
cmake --build Release
```
The executable is at `Release/ccls`.
You may use `-DSYSTEM_CLANG=on` if you have clang and llvm installed somewhere (can be a releases.llvm.org prebuilt archive, not necessarily installed via the system package manager).
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 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
+ [devel/ccls](https://www.freshports.org/devel/ccls)
+ with `devel/llvm70`: `cmake -H. -BRelease -DSYSTEM_CLANG=on -DUSE_SHARED_LLVM=on -DCMAKE_PREFIX_PATH=/usr/local/llvm70`
+ 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
+ MacPorts: `cmake -H. -BRelease -DSYSTEM_CLANG=on -DCMAKE_CXX_COMPILER=clang++-mp-6.0 -DCMAKE_PREFIX_PATH=/opt/local/libexec/llvm-6.0 -DLLVM_ENABLE_RTTI=on -DUSE_SHARED_LLVM=on`
* Windows. [[Build#windows]]
* Debian: `apt install zlib1g-dev ncurses-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 a llvm build with `-DLLVM_BUILD_LLVM_DYLIB=on`)) makes linked executable smaller.
+ `-G Ninja` to build with ninja.
* glibc < 2013-04-25 (e.g. RHEL 6 with modern GCC)
+ `-DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS`
## Setup your editor
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]].
## Project setup
### 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
There are several ways you can choose.
1. [[compile_commands.json]]
Remember to copy/symlink it to the project root.
2. `.ccls`
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.
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`:
```
%clang
%c -std=gnu11
%cpp -std=gnu++17
%objective-c %objective-cpp -DGNUSTEP
%c %cpp -DC_OR_CXX
-pthread
-I/work/ccls/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`
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`
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`
## 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:
`-fms-extensions -fms-compatibility -fdelayed-template-parsing`.
See https://clang.llvm.org/docs/MSVCCompatibility.html
## Standalone mode
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.
```zsh
ccls -index ~/llvm -init='{"clang":{"extraArgs": ["--gcc-toolchain=/usr"]}}'
```
## Cases
On a laptop with one (i7-6600U CPU @ 2.60GHz, hyper-threading, `nproc`=4), 4 indexers.
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)
* `du -sh .ccls-cache` => 580M
radare2 (2017-06-10)
```
CC=clang CXX=clang++ LDFLAGS=-fuse-ld=lld meson . debug --buildtype=debug --prefix ~/.config/radare2/debug
ln -s debug/compile_commands.json
```
* initial indexing: 78s; load: 3s
* 300MiB
* `du -sh .ccls-cache` => 107M
Note: ccls can serve LSP requests while it is doing the initial indexing of the project.

5
LanguageClient-neovim.md

@ -1,7 +1,4 @@
1. See [[Getting started]] to build the `ccls` executable ## Install [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
2. Install [LanguageClient-neovim](https://github.com/autozimu/LanguageClient-neovim)
### Install LanguageClient-neovim
* Check out the `next` branch * Check out the `next` branch
* Systems with prebuilt: `./install.sh` * Systems with prebuilt: `./install.sh`

3
coc.nvim.md

@ -1,5 +1,4 @@
1. See [[Getting started]] to build the `ccls` executable Install [coc.nvim](https://github.com/neoclide/coc.nvim)
2. Install [coc.nvim](https://github.com/neoclide/coc.nvim)
`~/.config/nvim/coc-settings.json` `~/.config/nvim/coc-settings.json`
```jsonc ```jsonc

7
eglot.md

@ -1,7 +1,6 @@
1. See [[Getting started]] to build the `ccls` executable 1. Install [eglot](https://github.com/joaotavora/eglot)
2. Install [eglot](https://github.com/joaotavora/eglot) 2. Open a C/C++/ObjC source file.
3. Open a C/C++/ObjC source file. 3. `M-x eglot-ensure`
4. `M-x eglot-ensure`
eglot uses builtin `project.el` to detect the project root. If you want to use projectile: eglot uses builtin `project.el` to detect the project root. If you want to use projectile:

9
lsp-mode.md

@ -1,8 +1,7 @@
1. See [[Getting started]] to build the `ccls` executable 1. Install [lsp-mode](https://github.com/emacs-lsp/lsp-mode) and optionally, [lsp-ui](https://github.com/emacs-lsp/lsp-ui) + [company-lsp](https://github.com/tigersoldier/company-lsp)
2. Install [lsp-mode](https://github.com/emacs-lsp/lsp-mode) and optionally, [lsp-ui](https://github.com/emacs-lsp/lsp-ui) + [company-lsp](https://github.com/tigersoldier/company-lsp) 2. Install [emacs-ccls](https://github.com/MaskRay/emacs-ccls) (Melpa: https://melpa.org/#/ccls) and [configure](#configure) it
3. Install [emacs-ccls](https://github.com/MaskRay/emacs-ccls) (Melpa: https://melpa.org/#/ccls) and [configure](#configure) it 3. Open a source file where either [[.ccls|Getting-started#ccls]] or [[compile_commands.json]] is in the project root (it works without them, if you don't need extra compiler command line options like `-I`)
4. Open a source file where either [[.ccls|Getting-started#ccls]] or [[compile_commands.json]] is in the project root (it works without them, if you don't need extra compiler command line options like `-I`) 4. `(require 'ccls)`, `M-x lsp`
5. `(require 'ccls)`, `M-x lsp`
`ccls.el` used to be based on the old interface `lsp-mode.el` of lsp-mode and the entry was `lsp-ccls-enable`. `ccls.el` used to be based on the old interface `lsp-mode.el` of lsp-mode and the entry was `lsp-ccls-enable`.