From e7a4a1f900ee0cb3a7b990dbe3e791b6c9ab4709 Mon Sep 17 00:00:00 2001 From: Fangrui Song Date: Fri, 4 Jan 2019 00:55:13 +0800 Subject: [PATCH] Rework Project-Setup.md --- Project-Setup.md | 106 +++++++++++++++++++++++++++++++++++++++++++---- _Sidebar.md | 14 +++---- 2 files changed, 103 insertions(+), 17 deletions(-) diff --git a/Project-Setup.md b/Project-Setup.md index 08c8ee7..1bd6253 100644 --- a/Project-Setup.md +++ b/Project-Setup.md @@ -1,11 +1,38 @@ +ccls typically indexes an entire project. In order for this to work properly, +`ccls` needs to be able to obtain the source file list and their compilation +command lines. + +There are two main ways this happens: + +1. Provide `compile_commands.json` at the project root +2. Provide `.ccls`. It is a line-based text file describing compiler flags. + Recursively listed source files (headers excluded) will be indexed. + +If neither exists, then when ccls starts it will not index anything: instead it +will wait for LSP clients to open files and index only those files. + +## `compile_commands.json` + [Guillaume Papin(@Sarcasm)](https://github.com/sarcasm) has [a thorough article about compilation databases](https://sarcasm.github.io/notes/dev/compilation-database.html). +Generally this file is not checked into source control, but rather is +generated by the build system. This means it's best to generate it in a new +project before starting the `ccls` server in that project. + +Because this file is auto-generated it's not easy to customize. As a result +it's possible to provide _both_ `compile_commands.json` _and_ `.ccls` in the +same project and have the `.ccls` configuration enhance the options from +`compile_commands.json`. + +If your `compile_commands.json` is not kept in the project root, set the +initialization option `compilationDatabaseDirectory` to an alternative +directory containing `compile_commands.json`. + ### [CMake](https://cmake.org/) ```zsh -% mkdir build -% (cd build; cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=YES ..) -% ln -s build/compile_commands.json +% cmake -H. -BDebug -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=YES +% ln -s Debug/compile_commands.json ``` Caveat on Windows: CMake dumps Windows shell command line directly into `command`, depends on how ccls was built, it may confuse this field as command line from a POSIX shell, in which Windows path separator '\\' is a escape character. You can use jq to convert such entries to use `arguments` which does not have this issue: @@ -70,7 +97,7 @@ You may use the initialization option `"compilationDatabaseCommand"` to provide ``` ```elisp -(setq ccls-extra-init-params '(:compilationDatabaseCommand "mycompdb")) +(setq ccls-initialization-options '(:compilationDatabaseCommand "mycompdb")) ``` Suppose the project is at `/tmp/c`, `mycompdb /tmp/c` will be executed with stdin=initializationOptions and the stdout should be a JSON compilation database. @@ -104,7 +131,72 @@ with open(os.path.join(sys.argv[1], 'compile_commands.json')) as f: json.dump(db, sys.stdout) ``` -## Examples +## `.ccls` + +`.ccls` is a line-based text file at the project root. It's main function is +to specify compiler flags needed to properly index your code: `-I` `-D` etc. +Each line consists of one argument. No whitespace splitting is performed on the +argument, thus `-I foo` cannot be used (use `-Ifoo` or `-I\nfoo`). + +Subdirectories of the project can also contain `.ccls` files, if needed, to +specify compiler flags specific to those directories. + +A line may start with zero or more `%` directives. + +Available directives include: + +### `%compile_commands.json` + +By default `.ccls` specify compiler flags of files not listed in +`compile_commands.json`. If this directive appears first in `.ccls` then after +`compile_commands.json` is parsed, the rest lines of `.ccls` will be appended +to the compiler flags. + +### `%clang` + +Resolves to either `clang` (C) or `clang++` (C++). This is useful if your +project has both C and C++ source files, because if unconditional `clang++` is +used instead, `clang++ a.c` parses `a.c` as C++. + +### `%c` / `%cpp` / `%objective-c` / `%objective-cpp` + +This argument should be added only when parsing C (`%c`), C++ (`%cpp`), +Objective-C (`%objective-c`), or Objective-C++ (`%objective-c++`) files. + +### `%h` / `%hpp` + +This argument should be added only when indexing C header files (`%h`: `*.h`) or C++ +header files (`%hpp`: `*.hh` `*.hpp`). Note, `*.h` files are considered as C, not C++. + +## `.ccls` examples + +#### Example A + +``` +%clang +%c -std=c11 +%cpp -std=c++2a +%h %hpp --include=Global.h +-Iinc +-DMACRO +```` + +`*.h *.hh *.hpp` files will be parsed with extra `--include=Global.h` + +#### Example B + +``` +%compile_commands.json +%c -std=c11 +%cpp -std=c++14 +%c %cpp -pthread +%h %hpp --include=Global.h +-Iinc +``` + +It appends flags so `%clang` should not be used. + +## `compile_commands.json` examples ### Linux kernel @@ -130,7 +222,3 @@ mkdir Debug; cd Debug bear make -j cd ..; ln -s Debug/compile_commands.json ``` - -## Misc - -`compile_commands.json` should reside in the project root. Set the initialization option `compilationDatabaseDirectory` for an alternative directory containing `compile_commands.json`. diff --git a/_Sidebar.md b/_Sidebar.md index c4ad61c..7706552 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,10 +1,6 @@ -* [[Home]] - - [[Getting started]] - - [[Build]] - - [[compile_commands.json]] - - [[Initialization options]] - - [[FAQ]] -* Editor configuration +[[Home]] +* [[Build]] +* [[Editor Configuration]] - [[Atom]] - Emacs + [[lsp-mode]] (+ emacs-ccls) @@ -14,6 +10,8 @@ + [[LanguageClient-neovim]] + [[vim-lsp]] - [[Visual Studio Code]] +* [[Project Setup]] +* [[Customization]] * [[Debugging]] -* [[Client feature table]] +* [[FAQ]] * [[LSP]]