From 57d1c06d8e6632fad0989a2d9a9677b458dce261 Mon Sep 17 00:00:00 2001 From: Paul Smith Date: Tue, 1 Jan 2019 10:56:04 -0500 Subject: [PATCH] Rework the wiki Build page --- Build.md | 210 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 155 insertions(+), 55 deletions(-) diff --git a/Build.md b/Build.md index 1a232a6..7ab1976 100644 --- a/Build.md +++ b/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=` + + Build **ccls** with the C++ compiler ``. If not specified CMake + will search for an appropriate C++ compiler. + +* `-DCMAKE_CXX_FLAGS=` + + Use extra compiler flags `` when compiling **ccls**. See the + system-specific sections below for some suggestions. + +* `-DCMAKE_INSTALL_PREFIX=` + + 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=` - ```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