Add Install wiki page

Paul Smith 2019-01-01 11:46:19 -05:00 committed by Fangrui Song
parent 2750118be1
commit 6eadcd596a

69
Install.md Normal file

@ -0,0 +1,69 @@
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=<dir>`. By default `<dir>` 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 `<dir>/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 `<dir>/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:
```sh
#!/bin/sh
exec "$HOME/src/ccls/obj/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.
## Clang Resource Directory
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.
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
```
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).