From f951e6d451f5e0a8c5c2db0ed780fd67fca819df Mon Sep 17 00:00:00 2001 From: Fangrui Song Date: Sun, 6 Jan 2019 11:26:15 +0800 Subject: [PATCH] Rework Build.md and Install.md contributed by madscientist --- Build.md | 27 ++++++++-------- Home.md | 10 ++++-- Install.md | 92 +++++++++++++++++++++++------------------------------ _Sidebar.md | 1 + 4 files changed, 62 insertions(+), 68 deletions(-) diff --git a/Build.md b/Build.md index 7ab1976..5c3a5fc 100644 --- a/Build.md +++ b/Build.md @@ -9,12 +9,13 @@ Otherwise, you'll need to build **ccls** from source. You will need: * Clang 5 or higher. * GCC 7.2 or higher (`optional,string_view` require libstdc++7 or higher) * MSVC 2017 or higher (included with VS2017 Build Tools) -* On GNU/Linux, either GNU make or Ninja (optional on other systems) +* On POSIX systems, either GNU make or Ninja (optional on other systems) The simplest/quickest build with all defaults (only for POSIX systems) is: ```sh git clone --depth=1 --recursive https://github.com/MaskRay/ccls +cd ccls cmake -H. -BRelease -DCMAKE_BUILD_TYPE=Release cmake --build Release ``` @@ -81,8 +82,7 @@ for your system, as well as methods of obtaining and locating Clang+LLVM. ## Choosing Clang+LLVM -**ccls** requires `libLLVM` to implement its code parsing. There are many -ways it can be obtained. +**ccls** requires LLVM and Clang. There are many ways they can be obtained. * `-DSYSTEM_CLANG=(ON|OFF)` @@ -99,9 +99,16 @@ system you will need to install `libclang-*-dev` and `llvm-*-dev` packages (or equivalent) in order to have the correct libraries. If they are installed into the standard locations for our system, CMake will locate them. -```sh -cmake -DSYSTEM_CLANG=ON -``` +Use `-DSYSTEM_CLANG=ON`. + +* `-DCMAKE_PREFIX_PATH=` + + CMake searches the paths in `CMAKE_PREFIX_PATH` for `include` and `lib` + subdirectories containing the required Clang headers and libraries, e.g. + + `-DSYSTEM_CLANG=ON -DCMAKE_PREFIX_PATH=/usr/local/llvm70` + + You may add multiple directories for `include` and `lib` separated by a `;`. ### Alternate Clang+LLVM @@ -110,13 +117,7 @@ it for you, or if you want to build Clang+LLVM from source, or if CMake can't find your installation of Clang+LLVM for any other reason, set the `CMAKE_PREFIX_PATH` CMake variable to point to the correct location: -* `-DCMAKE_PREFIX_PATH=` - - CMake searches the paths in `CMAKE_PREFIX_PATH` for `include` and `lib` - subdirectories containing the required Clang headers and libraries. - - You may add multiple directories for `include` and `lib` separated by a `;`, - e.g.: `-DCMAKE_PREFIX_PATH="$HOME/Dev/llvm/release;$HOME/Dev/llvm/tools/clang"` +Similar as System Clang+LLVM, `-DSYSTEM_CLANG=ON -DCMAKE_PREFIX_PATH=clang+llvm-7.0.0-x86_64-linux-gnu-ubuntu-16.04` ## GNU/Linux diff --git a/Home.md b/Home.md index 8012545..4ae9281 100644 --- a/Home.md +++ b/Home.md @@ -1,18 +1,22 @@ **ccls** is a stand-alone server implementing the [Language Server Protocol](https://langserver.org/) for C, C++, and Objective-C languages. It -can be used with [any editor](Editor-Configuration.md) which provides an LSP +can be used with [any editor](Editor-Configuration) which provides an LSP client implementation. It originates from [cquery](https://github.com/cquery-project/cquery). The language client (editor plugin) opens an instance of **ccls** for each project. **ccls** runs in the background, indexing the source code in the project and responding to requests from editors. -**ccls** uses the Clang+LLVM `libLLVM` library to parse your source code, so +**ccls** uses the Clang+LLVM C++ libraries to parse your source code, so it will recognize all language features supported by Clang. ## [[Build]] -First you must build **ccls**. You may (optionally) install it. +First you must build **ccls** + +## [[Install]] + +You may (optionally) install **ccls**. ## [[Editor Configuration]] diff --git a/Install.md b/Install.md index 5fc027d..8a96d79 100644 --- a/Install.md +++ b/Install.md @@ -1,69 +1,57 @@ +## Shell script wrapper + If you're using **ccls** for your own personal use and don't want to bother -installing it, you don't have to. You will need to configure your editor to -locate the `ccls` binary where it's built by CMake. - -If you'd like to install **ccls** into a separate location and clean up the -build environment you can do so. - -## CMake install - -The CMake install rule will copy the **ccls** binary into the install prefix -location set via `-DCMAKE_INSTALL_PREFIX=`. By default `` will be -`/usr/local`: note you may need to run the install with elevated privileges to -write to this directory. - -After building you can run: - -```sh -sudo cmake --build . --config Release --target install -``` - -(`sudo` is not necessary if you have write permissions to the installation -directory). This will install **ccls** as `/bin/ccls` and also install -the LLVM shared libraries (you do not need these unless you've set -`-DUSE_SHARED_LLVM=ON` however). - -If you have `/bin` on your `PATH` then **ccls** should be found. - -## Shell Script Wrapper - -An alternative to installing `ccls` is to use a small shell script wrapper and -put that on your `PATH`. This allows you to customize the invocation of -`ccls`. It's especially useful for implementing relocatable installs, or for -use with [[Editor Configuration]]s that don't make it easy to configure the -server's startup. - -If you build in `$HOME/src/ccls/obj` using Ninja for example then you might -create a shell script wrapper `ccls` like this: +installing it, you don't have to. Consider putting a small shell script wrapper `ccls` +on your `PATH` to customize command line options. ```sh #!/bin/sh -exec "$HOME/src/ccls/obj/ccls" "$@" +exec "$HOME/src/ccls/Release/ccls" "$@" ``` -(be sure to make the script executable!) You might want to add other options -such as `--log-file=/tmp/ccls.out` to force logging. You may also want to add -a `--init` option to set the resource directory as below. If you built `ccls` -using shared libraries you might need to set `LD_LIBRARY_PATH` here before -exec'ing `ccls`. And there are [[Debugging]] environment variables that might -be useful to set as well. +(be sure to make the script executable!) You might want to -## Clang Resource Directory +* add other options such as `--log-file=/tmp/ccls.out` to force logging. `-v=1` and `-init=` are other useful options. See [[Customization]]. +* set `LD_LIBRARY_PATH` if CMake fails to set `DT_RUNPATH` for the built `ccls` executable. +* set [[Debugging]] environment variables that might be useful. -The Clang+LLVM shared library requires Clang system header files to be -available otherwise indexing will fail silently. Clang searches for these -headers in its _resource directory_. The `ccls` binary will be hard-coded to -search for the resource directory where it was found by CMake during the build. +## CMake install + +If you'd like to install **ccls** into a separate location, read on. + +The CMake install rule will copy the **ccls** binary into the install prefix +location set via `-DCMAKE_INSTALL_PREFIX=` (default: `/usr/local`). After +building you can run: + +```sh +cmake --build Release --target install +# cmake --build . --config Release --target install +``` + +This will install **ccls** as `/bin/ccls` (and also install the LLVM +shared libraries if `-DUSE_SHARED_LLVM=ON`). + +If you have `/bin` on your `PATH` then **ccls** should be found. + +## Clang resource directory + +Some header files such as `stddef.h stdint.h` are located in the `include/` +subdirectory of Clang resource directory. + +The location of Clang resource directory is hard-coded in the `ccls` executable +(`-DDEFAULT_RESOURCE_DIRECTORY=` when building ccls). The absence of Clang +resource directory may lead to errors like `unknown type name 'size_t'` and +incomplete index results. If you downloaded Clang+LLVM as part of the build and you want to install **ccls** and delete the build directory, you need to copy the contents of the resource directory; for example something like: ```sh -sudo mkdir -p /usr/local/clang -sudo cp -a clang+llvm-7.0.0-x86_64-linux-gnu-ubuntu-16.04/lib/clang/7.0.0/include /usr/local/clang +sudo mkdir -p /usr/local/clang/7.0.0 +sudo cp -a Release/clang+llvm-7.0.0-x86_64-linux-gnu-ubuntu-16.04/lib/clang/7.0.0/include /usr/local/clang/7.0.0/ ``` Then you must configure `ccls` to locate this directory by adding an option -such as `--init='{"clang": {"resourceDir": "/usr/local/clang"}}'` (see -[`resourceDir`](Customization#clangresourcedir) for more information). +such as `--init='{"clang": {"resourceDir": "/usr/local/clang/7.0.0"}}'` (see +[`clang.resourceDir`](Customization#clangresourcedir) for more information). diff --git a/_Sidebar.md b/_Sidebar.md index 7706552..ec612e8 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,5 +1,6 @@ [[Home]] * [[Build]] +* [[Install]] * [[Editor Configuration]] - [[Atom]] - Emacs