mirror of
https://github.com/MaskRay/ccls.git
synced 2024-11-21 23:25:07 +00:00
Rework the wiki Build page
Paul Smith
Fangrui Song
parent
1f66c28189
commit
57d1c06d8e
210
Build.md
210
Build.md
@ -1,81 +1,179 @@
|
||||
* CMake 3.8 or higher
|
||||
* C++ Compiler with C++17 support:
|
||||
* Clang 5 or higher
|
||||
Some distributions package a pre-built version of **ccls**. See the
|
||||
system-specific sections below if you'd like to investigate that.
|
||||
|
||||
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)
|
||||
* 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
|
||||
|
||||
* `-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)`
|
||||
|
||||
Default: Release
|
||||
Set the build type. The most important ones are Debug and Release.
|
||||
Default: **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)`
|
||||
|
||||
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.
|
||||
Default: **OFF**
|
||||
|
||||
```zsh
|
||||
% cmake -H. -BRelease -DCMAKE_INSTALL_PREFIX=/usr -DSYSTEM_CLANG=On
|
||||
% cmake --build Release
|
||||
```
|
||||
The default behavior of CMake is to download a pre-built binary of Clang.
|
||||
If you prefer a different approach add `-DSYSTEM_CLANG=ON` and choose a
|
||||
method below.
|
||||
|
||||
You can also use the option to use a downloaded and unpacked clang+llvm archive:
|
||||
```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
|
||||
```
|
||||
### System Clang+LLVM
|
||||
|
||||
cmake will download the releases.llvm.org archive for you. If you want to download it manually:
|
||||
```zsh
|
||||
rm -r Release
|
||||
mkdir Release
|
||||
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 ...
|
||||
```
|
||||
If you want to link against a version of Clang+LLVM already installed on your
|
||||
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.
|
||||
|
||||
* `-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.
|
||||
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++.
|
||||
* `-DCMAKE_PREFIX_PATH=<clang-install-path>`
|
||||
|
||||
```zsh
|
||||
# If your clang++ is old, you may rerun this command with clang++ replaced to
|
||||
# the absolute path of bundled/clang+llvm-*/bin/clang++
|
||||
cmake -H. -Brelease -G Ninja -DCMAKE_CXX_COMPILER=clang++ -DCLANG_USE_BUNDLED_LIBC++=on
|
||||
```
|
||||
CMake searches the paths in `CMAKE_PREFIX_PATH` for `include` and `lib`
|
||||
subdirectories containing the required Clang headers and libraries.
|
||||
|
||||
* `-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
|
||||
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"`.
|
||||
## GNU/Linux
|
||||
|
||||
You may add directories for `include` and `lib` separated by a `;`, e.g. to use trunk clang:
|
||||
`-DCMAKE_PREFIX_PATH="$HOME/Dev/llvm/release;$HOME/Dev/llvm/tools/clang"`
|
||||
* On GNU/Linux distributions with older versions of glibc (older than
|
||||
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
|
||||
|
||||
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.
|
||||
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 .
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
## Link against clang+llvm libraries compiled from source
|
||||
## Notes on compiling Clang+LLVM from source
|
||||
|
||||
* `include/llvm/Config/config.h`
|
||||
* `include/clang/Config/config.h`
|
||||
* `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/`):
|
||||
|
||||
```zsh
|
||||
```sh
|
||||
git clone https://git.llvm.org/git/llvm.git
|
||||
git clone https://git.llvm.org/git/clang.git llvm/tools/clang
|
||||
cd llvm
|
||||
@ -117,7 +217,7 @@ ninja -C Release clangFormat clangFrontendTool clangIndex clangTooling
|
||||
|
||||
Then build ccls with `-DSYSTEM_CLANG` and `-DCMAKE_PREFIX_PATH`:
|
||||
|
||||
```zsh
|
||||
```sh
|
||||
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"
|
||||
ninja -C Release
|
||||
|
||||
Loading…
Reference in New Issue
Block a user