1# Abseil CMake Build Instructions 2 3Abseil comes with a CMake build script ([CMakeLists.txt](../CMakeLists.txt)) 4that can be used on a wide range of platforms ("C" stands for cross-platform.). 5If you don't have CMake installed already, you can download it for free from 6<https://www.cmake.org/>. 7 8CMake works by generating native makefiles or build projects that can 9be used in the compiler environment of your choice. 10 11For API/ABI compatibility reasons, we strongly recommend building Abseil in a 12subdirectory of your project or as an embedded dependency. 13 14## Incorporating Abseil Into a CMake Project 15 16The recommendations below are similar to those for using CMake within the 17googletest framework 18(<https://github.com/google/googletest/blob/master/googletest/README.md#incorporating-into-an-existing-cmake-project>) 19 20### Step-by-Step Instructions 21 221. If you want to build the Abseil tests, integrate the Abseil dependency 23[Google Test](https://github.com/google/googletest) into your CMake project. To disable Abseil tests, you have to pass 24`-DBUILD_TESTING=OFF` when configuring your project with CMake. 25 262. Download Abseil and copy it into a subdirectory in your CMake project or add 27Abseil as a [git submodule](https://git-scm.com/docs/git-submodule) in your 28CMake project. 29 303. You can then use the CMake command 31[`add_subdirectory()`](https://cmake.org/cmake/help/latest/command/add_subdirectory.html) 32to include Abseil directly in your CMake project. 33 344. Add the **absl::** target you wish to use to the 35[`target_link_libraries()`](https://cmake.org/cmake/help/latest/command/target_link_libraries.html) 36section of your executable or of your library.<br> 37Here is a short CMakeLists.txt example of a project file using Abseil. 38 39```cmake 40cmake_minimum_required(VERSION 3.5) 41project(my_project) 42 43# Pick the C++ standard to compile with. 44# Abseil currently supports C++11, C++14, and C++17. 45set(CMAKE_CXX_STANDARD 11) 46 47add_subdirectory(abseil-cpp) 48 49add_executable(my_exe source.cpp) 50target_link_libraries(my_exe absl::base absl::synchronization absl::strings) 51``` 52 53### Running Abseil Tests with CMake 54 55Use the `-DBUILD_TESTING=ON` flag to run Abseil tests. 56 57You will need to provide Abseil with a Googletest dependency. There are two 58options for how to do this: 59 60* Use `-DABSL_USE_GOOGLETEST_HEAD`. This will automatically download the latest 61Googletest source into the build directory at configure time. Googletest will 62then be compiled directly alongside Abseil's tests. 63* Manually integrate Googletest with your build. See 64https://github.com/google/googletest/blob/master/googletest/README.md#using-cmake 65for more information on using Googletest in a CMake project. 66 67For example, to run just the Abseil tests, you could use this script: 68 69``` 70cd path/to/abseil-cpp 71mkdir build 72cd build 73cmake -DBUILD_TESTING=ON -DABSL_USE_GOOGLETEST_HEAD=ON .. 74make -j 75ctest 76``` 77 78Currently, we only run our tests with CMake in a Linux environment, but we are 79working on the rest of our supported platforms. See 80https://github.com/abseil/abseil-cpp/projects/1 and 81https://github.com/abseil/abseil-cpp/issues/109 for more information. 82 83### Available Abseil CMake Public Targets 84 85Here's a non-exhaustive list of Abseil CMake public targets: 86 87```cmake 88absl::algorithm 89absl::base 90absl::debugging 91absl::flat_hash_map 92absl::flags 93absl::memory 94absl::meta 95absl::numeric 96absl::random_random 97absl::strings 98absl::synchronization 99absl::time 100absl::utility 101``` 102 103## Traditional CMake Set-Up 104 105For larger projects, it may make sense to use the traditional CMake set-up where you build and install projects separately. 106 107First, you'd need to build and install Google Test: 108``` 109cmake -S /source/googletest -B /build/googletest -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/installation/dir -DBUILD_GMOCK=ON 110cmake --build /build/googletest --target install 111``` 112 113Then you need to configure and build Abseil. Make sure you enable `ABSL_USE_EXTERNAL_GOOGLETEST` and `ABSL_FIND_GOOGLETEST`. You also need to enable `ABSL_ENABLE_INSTALL` so that you can install Abseil itself. 114``` 115cmake -S /source/abseil-cpp -B /build/abseil-cpp -DCMAKE_PREFIX_PATH=/installation/dir -DCMAKE_INSTALL_PREFIX=/installation/dir -DABSL_ENABLE_INSTALL=ON -DABSL_USE_EXTERNAL_GOOGLETEST=ON -DABSL_FIND_GOOGLETEST=ON 116cmake --build /temporary/build/abseil-cpp 117``` 118 119(`CMAKE_PREFIX_PATH` is where you already have Google Test installed; `CMAKE_INSTALL_PREFIX` is where you want to have Abseil installed; they can be different.) 120 121Run the tests: 122``` 123ctest --test-dir /temporary/build/abseil-cpp 124``` 125 126And finally install: 127``` 128cmake --build /temporary/build/abseil-cpp --target install 129``` 130 131# CMake Option Synposis 132 133## Enable Standard CMake Installation 134 135`-DABSL_ENABLE_INSTALL=ON` 136 137## Google Test Options 138 139`-DBUILD_TESTING=ON` must be set to enable testing 140 141- Have Abseil download and build Google Test for you: `-DABSL_USE_EXTERNAL_GOOGLETEST=OFF` (default) 142 - Download and build latest Google Test: `-DABSL_USE_GOOGLETEST_HEAD=ON` 143 - Download specific Google Test version (ZIP archive): `-DABSL_GOOGLETEST_DOWNLOAD_URL=https://.../version.zip` 144 - Use Google Test from specific local directory: `-DABSL_LOCAL_GOOGLETEST_DIR=/path/to/googletest` 145- Use Google Test included elsewhere in your project: `-DABSL_USE_EXTERNAL_GOOGLETEST=ON` 146- Use standard CMake `find_package(CTest)` to find installed Google Test: `-DABSL_USE_EXTERNAL_GOOGLETEST=ON -DABSL_FIND_GOOGLETEST=ON` 147