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

Rework the wiki Build page

Paul Smith 2019-01-01 10:56:04 -05:00 committed by Fangrui Song
parent 1f66c28189
commit 57d1c06d8e
1 changed files with 155 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
Build.md

@ -1,81 +1,179 @@
* CMake 3.8 or higher Some distributions package a pre-built version of **ccls**. See the
* C++ Compiler with C++17 support: system-specific sections below if you'd like to investigate that.
* Clang 5 or higher
Otherwise, you'll need to build **ccls** from source. You will need:
* The source code for **ccls**.
* [CMake](https://cmake.org/) 3.8 or higher.
* A C++ compiler with C++17 support:
* Clang 5 or higher.
* GCC 7.2 or higher (`optional,string_view` require libstdc++7 or higher) * GCC 7.2 or higher (`optional,string_view` require libstdc++7 or higher)
* MSVC 2017 or higher (included with VS2017 Build Tools) * MSVC 2017 or higher (included with VS2017 Build Tools)
* On GNU/Linux, either GNU make or Ninja (optional on other systems)
See [[Getting-started]] for recommended configuration options for common systems. The simplest/quickest build with all defaults (only for POSIX systems) is:
You may append `-G Ninja -DCMAKE_CXX_LINK_FLAGS=-fuse-ld=lld -DCMAKE_CXX_COMPILER=clang++` ```sh
git clone --depth=1 --recursive https://github.com/MaskRay/ccls
cmake -H. -BRelease -DCMAKE_BUILD_TYPE=Release
cmake --build Release
```
The resulting executable will be `Release/ccls`.
See below for other CMake options available for customizing the build, hints
for your system, as well as methods of obtaining and locating Clang+LLVM.
## CMake Options ## CMake Options
* `-G ('Unix Makefiles'|Ninja|Xcode|'Visual Studio 2017 x64')`
Choose a specific CMake generator (build tool). Use `cmake --help` to see
your choices (not all options are available on all systems). If not
specified CMake will choose an appropriate option for your system.
* `-DCMAKE_BUILD_TYPE=(Debug|MinSizeRel|Release|RelWithDebInfo)` * `-DCMAKE_BUILD_TYPE=(Debug|MinSizeRel|Release|RelWithDebInfo)`
Default: Release Default: **Release**
Set the build type. The most important ones are Debug and Release.
Set the build type. The most important ones are **Debug** and **Release**.
* `-DCMAKE_CXX_COMPILER=<compiler>`
Build **ccls** with the C++ compiler `<compiler>`. If not specified CMake
will search for an appropriate C++ compiler.
* `-DCMAKE_CXX_FLAGS=<flags>`
Use extra compiler flags `<flags>` when compiling **ccls**. See the
system-specific sections below for some suggestions.
* `-DCMAKE_INSTALL_PREFIX=<dir>`
Default: **/usr/local**
Set the install location. See [[Install]] for more details.
* `-DUSE_SHARED_LLVM=(ON|OFF)`
Default: **OFF**
Link against `libLLVM.so` instead of static LLVM libraries. This makes
linking faster and the executable significantly smaller but the **ccls**
binary will need access to `libLLVM.so` at runtime as well as link-time.
* `-DCLANG_USE_BUNDLED_LIBC++=(ON|OFF)`
Default: **OFF**
Clang provides libc++ libraries. This option forces **ccls** to link with
these libraries. This can be used on FreeBSD, but likely won't work on
Linux due to conflict of libstdc++ (linked by clang+llvm libraries) and
libc++.
* `-DLLVM_ENABLE_RTTI=(ON|OFF)`
Default: **OFF**
Some system-supplied versions of `libLLVM` enable RTTI in which case
**ccls** must as well: use `-DLLVM_ENABLE_RTTI=ON`. See the system-specific
sections below.
## Choosing Clang+LLVM
**ccls** requires `libLLVM` to implement its code parsing. There are many
ways it can be obtained.
* `-DSYSTEM_CLANG=(ON|OFF)` * `-DSYSTEM_CLANG=(ON|OFF)`
Default: OFF Default: **OFF**
Enable `SYSTEM_CLANG` if you want to link ccls against a system/local Clang instead of downloading Clang from releases.llvm.org during the configure process. You will probably need to install `libclang-*-dev` and `llvm-*-dev` packages (or equivalent) in order to have the correct libraries.
```zsh The default behavior of CMake is to download a pre-built binary of Clang.
% cmake -H. -BRelease -DCMAKE_INSTALL_PREFIX=/usr -DSYSTEM_CLANG=On If you prefer a different approach add `-DSYSTEM_CLANG=ON` and choose a
% cmake --build Release method below.
```
You can also use the option to use a downloaded and unpacked clang+llvm archive: ### System Clang+LLVM
```zsh
cmake -GNinja -H. -BBundled -DSYSTEM_CLANG=on -DCMAKE_PREFIX_PATH=$PWD/build/clang+llvm-7.0.0-x86_64-linux-gnu-ubuntu-14.04
```
cmake will download the releases.llvm.org archive for you. If you want to download it manually: If you want to link against a version of Clang+LLVM already installed on your
```zsh system you will need to install `libclang-*-dev` and `llvm-*-dev` packages (or
rm -r Release equivalent) in order to have the correct libraries. If they are installed
mkdir Release into the standard locations for our system, CMake will locate them.
cd Release
# download clang+llvm-6.0.1-x86_64-linux-gnu-ubuntu-16.04.tar.xz, verify with sha256sum and put it here
tar xf clang+llvm-6.0.1-x86_64-linux-gnu-ubuntu-16.04.tar.xz
cd ..
# cmake -H. -BRelease ...
```
* `-DCMAKE_CXX_COMPILER=/usr/bin/clang++` ```sh
cmake -DSYSTEM_CLANG=ON
```
Build ccls with `/usr/bin/clang++`. You may use the absolute path of `Release/clang+llvm-*/bin/clang++` after clang+llvm archive is downloaded and extracted. ### Alternate Clang+LLVM
* `-DCLANG_USE_BUNDLED_LIBC++=on` If you wish to download and unpack Clang yourself rather than having CMake do
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:
`clang+llvm*` downloaded from releases.llvm.org also provides libc++ libraries. * `-DCMAKE_PREFIX_PATH=<clang-install-path>`
This can be used on FreeBSD, but probably does not work on Linux due to conflict of libstdc++ (linked by clang+llvm libraries) and libc++.
```zsh CMake searches the paths in `CMAKE_PREFIX_PATH` for `include` and `lib`
# If your clang++ is old, you may rerun this command with clang++ replaced to subdirectories containing the required Clang headers and libraries.
# the absolute path of bundled/clang+llvm-*/bin/clang++
cmake -H. -Brelease -G Ninja -DCMAKE_CXX_COMPILER=clang++ -DCLANG_USE_BUNDLED_LIBC++=on
```
* `-DCMAKE_PREFIX_PATH="custom_install_path"` 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"`
When you want to use a system installed Clang but it is not installed into any ## GNU/Linux
default CMake search location (for example if you built LLVM from source) you
can tell CMake where to search by adding search paths to `CMAKE_PREFIX_PATH`.
CMake searches the paths in `CMAKE_PREFIX_PATH` for 'include' and 'lib'
subdirectories containing the required Clang headers and libraries. For example,
to use a system installation of Clang on Windows you can add the following
option: `-DCMAKE_PREFIX_PATH="C:/Program Files/LLVM"`.
You may add directories for `include` and `lib` separated by a `;`, e.g. to use trunk clang: * On GNU/Linux distributions with older versions of glibc (older than
`-DCMAKE_PREFIX_PATH="$HOME/Dev/llvm/release;$HOME/Dev/llvm/tools/clang"` 2013-04-25), such as Red Hat EL 6.x, you may need to add the `-D__STDC_FORMAT_MACROS` option to `CMAKE_CXX_FLAGS`:
* `-DUSE_SHARED_LLVM=on` `-DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS`
Link against `libLLVM.so` instead of `libLLVMSupport.a libLLVMDemangle.a ...` This makes linking faster and the executable significantly smaller. ### Arch Linux
To install pre-built **ccls**, use
[aur/ccls-git](https://aur.archlinux.org/packages/ccls-git).
To build **ccls** on Arch Linux with system Clang+LLVM, you will need to add
`-DLLVM_ENABLE_RTTI=on`.
### Gentoo Linux
To build **ccls** on Gentoo Linux with system Clang+LLVM, you will need to add
`-DLLVM_ENABLE_RTTI=on`.
### Debian / Ubuntu
To build from source you'll need `sudo apt install zlib1g-dev ncurses-dev`
On Ubuntu 16.04 install g++-7 via [these directions](https://gist.github.com/jlblancoc/99521194aba975286c80f93e47966dc5)
### Red Hat / CentOS
Older versions (6.x) use an older GNU libc which requires
`-DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS`
## MacOS
To install **ccls** with Homebrew use https://github.com/twlz0ne/homebrew-ccls
To build from source you need MacOS 10.12 (Sierra) or higher to get a version
of Xcode with a sufficiently-new Clang.
To build using MacPorts Clang add CMake flags `-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`
## FreeBSD
* [devel/ccls](https://www.freshports.org/devel/ccls)
* With `devel/llvm70` add CMake flags `-DSYSTEM_CLANG=on
-DUSE_SHARED_LLVM=on -DCMAKE_PREFIX_PATH=/usr/local/llvm70`
* To use the releases.llvm.org prebuilt archive and its libc++ add CMake flag
`-DCLANG_USE_BUNDLED_LIBC++=on`
## Windows ## Windows
The Windows archive on releases.llvm.org does not contain library headers, since ccls uses Clang C++ APIs, it is not possible to build ccls with these releases. You have to either: The Windows archive on releases.llvm.org does not contain library headers.
Since **ccls** uses Clang C++ APIs, it is not possible to build **ccls** with
these releases. You must either:
1. Build LLVM+Clang by yourself with your favorite toolchain. 1. Build LLVM+Clang by yourself with your favorite toolchain.
2. Get prebuilt LLVM+Clang from other sources. 2. Get prebuilt LLVM+Clang from other sources.
@ -90,20 +188,22 @@ cmake .. -G Ninja -DSYSTEM_CLANG=ON -DCMAKE_CXX_FLAGS=-D__STDC_FORMAT_MACROS
cmake --build . cmake --build .
``` ```
Building ccls with MSVC 2017 and locally built LLVM+Clang on Windows does not work right now, contributions welcome. Building ccls with MSVC 2017 and locally built LLVM+Clang on Windows does not
work right now, contributions welcome.
`-D__STDC_FORMAT_MACROS` is because otherwise `mingw-w64-headers/crt/inttypes.h` does not define `PRIu64`. `-D__STDC_FORMAT_MACROS` is because otherwise `mingw-w64-headers/crt/inttypes.h` does not define `PRIu64`.
## Link against clang+llvm libraries compiled from source ## Notes on compiling Clang+LLVM from source
* `include/llvm/Config/config.h` * `include/llvm/Config/config.h`
* `include/clang/Config/config.h` * `include/clang/Config/config.h`
* `lib/libclangIndex.so` * `lib/libclangIndex.so`
* `lib/libLLVM{Support,...}.so` or `lib/libLLVM{Support,...}.a` or `lib/libLLVM.so` * `lib/libLLVM{Support,...}.so` or `lib/libLLVM{Support,...}.a` or
`lib/libLLVM.so`
MaskRay's config (building trunk LLVM at `~/llvm/Release/`): MaskRay's config (building trunk LLVM at `~/llvm/Release/`):
```zsh ```sh
git clone https://git.llvm.org/git/llvm.git git clone https://git.llvm.org/git/llvm.git
git clone https://git.llvm.org/git/clang.git llvm/tools/clang git clone https://git.llvm.org/git/clang.git llvm/tools/clang
cd llvm cd llvm
@ -117,7 +217,7 @@ ninja -C Release clangFormat clangFrontendTool clangIndex clangTooling
Then build ccls with `-DSYSTEM_CLANG` and `-DCMAKE_PREFIX_PATH`: Then build ccls with `-DSYSTEM_CLANG` and `-DCMAKE_PREFIX_PATH`:
```zsh ```sh
cd ~/ccls cd ~/ccls
cmake -H. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld -DSYSTEM_CLANG=On -DCMAKE_PREFIX_PATH="$HOME/llvm/Release;$HOME/llvm/Release/tools/clang;$HOME/llvm;$HOME/llvm/tools/clang" cmake -H. -BRelease -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld -DSYSTEM_CLANG=On -DCMAKE_PREFIX_PATH="$HOME/llvm/Release;$HOME/llvm/Release/tools/clang;$HOME/llvm;$HOME/llvm/tools/clang"
ninja -C Release ninja -C Release