diff --git a/Build.md b/Build.md new file mode 100644 index 0000000..3b8ec36 --- /dev/null +++ b/Build.md @@ -0,0 +1,73 @@ +cquery has experimental support for the CMake build system. + +To get started building cquery, first install the required dependencies: + +* CMake 3.1 or higher +* C++ Compiler with C++14 support: + * Clang 3.4 or higher + * GCC 5 or higher + * MSVC 2017 or higher (included with VS2017 Build Tools) + +After installing the required dependencies, clone the repository along with its +git submodules using: +`git clone https://github.com/cquery-project/cquery.git --recursive` + +After cloning the repository, open a terminal and navigate to the cquery +directory. Then, create a build directory which will contain all files +related to the build. Enter the build directory. + +From inside the build directory, we can then configure the project with the +following command: `cmake ..` + +[**Windows**] On Windows you have to explicitly tell CMake to target 64-bit +architecture by adding the `-DCMAKE_GENERATOR_PLATFORM=x64` option to the +cmake invocation (`cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..`). 32-bit builds +are not supported at the moment. + +This command generates project files for your system's default generator (Linux: +make, Windows: MSBuild). CMake defaults to a Release build and links cquery +against the libclang library which it downloads from https://releases.llvm.org. + +After CMake configuration cquery can be built from inside the build directory by +executing the corresponding generator command (Linux: `make`, Windows: +`MSBuild.exe`) or the generic CMake build command (`cmake --build .`) + +## CMake Options + +CMake options can be specified when running CMake to change its behaviour. +Options are passed to CMake via the command line by prepending them with -D. For +example: `cmake -DCMAKE_BUILD_TYPE=Debug ..` configures cquery to be built in +release mode. + +* `-DCMAKE_BUILD_TYPE=(Debug|Release)` + +`CMAKE_BUILD_TYPE` can be used to set the build type. There are a few possible +options, but the most important ones are Debug and Release. Generally you want +to pass `-DCMAKE_BUILD_TYPE=Release` to CMake to get the best performance out of +cquery. Debug is recommended when debugging cquery with a debugger. Since cquery +defaults to a Release build it usually isn't necessary to define this option +unless you're debugging an issue in cquery with a debugger. + +* `-DSYSTEM_CLANG=(ON|OFF)` + +Enable `SYSTEM_CLANG` if you want to use your own system installation of Clang +instead of downloading Clang during the configure process. This requires you to +have a recent installation of Clang/LLVM installed on your system. Note that +using system Clang is not recommended and there is a higher chance of bugs due +to possible version differences between downloaded Clang and system installed +Clang. + +* `-DCMAKE_PREFIX_PATH="custom_install_path"` + +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"`. + +If the 'include' and 'lib' directories reside in two different parent +directories (possible when building LLVM from source) you will have to add both +these directories to CMAKE_PREFIX_PATH separated by a ';' +(`-DCMAKE\_PREFIX\_PATH=";"`).