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 24project. To disable Abseil tests, you have to pass either 25`-DBUILD_TESTING=OFF` or `-DABSL_BUILD_TESTING=OFF` when configuring your 26project with CMake. 27 282. Download Abseil and copy it into a subdirectory in your CMake project or add 29Abseil as a [git submodule](https://git-scm.com/docs/git-submodule) in your 30CMake project. 31 323. You can then use the CMake command 33[`add_subdirectory()`](https://cmake.org/cmake/help/latest/command/add_subdirectory.html) 34to include Abseil directly in your CMake project. 35 364. Add the **absl::** target you wish to use to the 37[`target_link_libraries()`](https://cmake.org/cmake/help/latest/command/target_link_libraries.html) 38section of your executable or of your library.<br> 39Here is a short CMakeLists.txt example of an application project using Abseil. 40 41```cmake 42cmake_minimum_required(VERSION 3.10) 43project(my_app_project) 44 45# Pick the C++ standard to compile with. 46# Abseil currently supports C++14, C++17, and C++20. 47set(CMAKE_CXX_STANDARD 14) 48set(CMAKE_CXX_STANDARD_REQUIRED ON) 49 50add_subdirectory(abseil-cpp) 51 52add_executable(my_exe source.cpp) 53target_link_libraries(my_exe absl::base absl::synchronization absl::strings) 54``` 55 56Note that if you are developing a library designed for use by other clients, you 57should instead leave `CMAKE_CXX_STANDARD` unset (or only set if being built as 58the current top-level CMake project) and configure the minimum required C++ 59standard at the target level. If you require a later minimum C++ standard than 60Abseil does, it's a good idea to also enforce that `CMAKE_CXX_STANDARD` (which 61will control Abseil library targets) is set to at least that minimum. For 62example: 63 64```cmake 65cmake_minimum_required(VERSION 3.10) 66project(my_lib_project) 67 68# Leave C++ standard up to the root application, so set it only if this is the 69# current top-level CMake project. 70if(CMAKE_SOURCE_DIR STREQUAL my_lib_project_SOURCE_DIR) 71 set(CMAKE_CXX_STANDARD 17) 72 set(CMAKE_CXX_STANDARD_REQUIRED ON) 73endif() 74 75add_subdirectory(abseil-cpp) 76 77add_library(my_lib source.cpp) 78target_link_libraries(my_lib absl::base absl::synchronization absl::strings) 79 80# Enforce that my_lib requires C++17. Important to document for clients that they 81# must set CMAKE_CXX_STANDARD to 17 or higher for proper Abseil ABI compatibility 82# (since otherwise, Abseil library targets could be compiled with a lower C++ 83# standard than my_lib). 84target_compile_features(my_lib PUBLIC cxx_std_17) 85if(CMAKE_CXX_STANDARD LESS 17) 86 message(FATAL_ERROR 87 "my_lib_project requires CMAKE_CXX_STANDARD >= 17 (got: ${CMAKE_CXX_STANDARD})") 88endif() 89``` 90 91Then the top-level application project that uses your library is responsible for 92setting a consistent `CMAKE_CXX_STANDARD` that is sufficiently high. 93 94### Running Abseil Tests with CMake 95 96Use the `-DABSL_BUILD_TESTING=ON` flag to run Abseil tests. Note that 97BUILD_TESTING must also be on (the default). 98 99You will need to provide Abseil with a Googletest dependency. There are two 100options for how to do this: 101 102* Use `-DABSL_USE_GOOGLETEST_HEAD`. This will automatically download the latest 103Googletest source into the build directory at configure time. Googletest will 104then be compiled directly alongside Abseil's tests. 105* Manually integrate Googletest with your build. See 106https://github.com/google/googletest/blob/master/googletest/README.md#using-cmake 107for more information on using Googletest in a CMake project. 108 109For example, to run just the Abseil tests, you could use this script: 110 111``` 112cd path/to/abseil-cpp 113mkdir build 114cd build 115cmake -DABSL_BUILD_TESTING=ON -DABSL_USE_GOOGLETEST_HEAD=ON .. 116make -j 117ctest 118``` 119 120Currently, we only run our tests with CMake in a Linux environment, but we are 121working on the rest of our supported platforms. See 122https://github.com/abseil/abseil-cpp/projects/1 and 123https://github.com/abseil/abseil-cpp/issues/109 for more information. 124 125### Available Abseil CMake Public Targets 126 127Here's a non-exhaustive list of Abseil CMake public targets: 128 129```cmake 130absl::algorithm 131absl::base 132absl::debugging 133absl::flat_hash_map 134absl::flags 135absl::memory 136absl::meta 137absl::numeric 138absl::random_random 139absl::strings 140absl::synchronization 141absl::time 142absl::utility 143``` 144 145## Traditional CMake Set-Up 146 147For larger projects, it may make sense to use the traditional CMake set-up where you build and install projects separately. 148 149First, you'd need to build and install Google Test: 150``` 151cmake -S /source/googletest -B /build/googletest -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/installation/dir -DBUILD_GMOCK=ON 152cmake --build /build/googletest --target install 153``` 154 155Then 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. 156``` 157cmake -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 158cmake --build /temporary/build/abseil-cpp 159``` 160 161(`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.) 162 163Run the tests: 164``` 165ctest --test-dir /temporary/build/abseil-cpp 166``` 167 168And finally install: 169``` 170cmake --build /temporary/build/abseil-cpp --target install 171``` 172 173# CMake Option Synopsis 174 175## Enable Standard CMake Installation 176 177`-DABSL_ENABLE_INSTALL=ON` 178 179## Google Test Options 180 181`-DABSL_BUILD_TESTING=ON` must be set to enable testing 182 183- Have Abseil download and build Google Test for you: `-DABSL_USE_EXTERNAL_GOOGLETEST=OFF` (default) 184 - Download and build latest Google Test: `-DABSL_USE_GOOGLETEST_HEAD=ON` 185 - Download specific Google Test version (ZIP archive): `-DABSL_GOOGLETEST_DOWNLOAD_URL=https://.../version.zip` 186 - Use Google Test from specific local directory: `-DABSL_LOCAL_GOOGLETEST_DIR=/path/to/googletest` 187- Use Google Test included elsewhere in your project: `-DABSL_USE_EXTERNAL_GOOGLETEST=ON` 188- Use standard CMake `find_package(CTest)` to find installed Google Test: `-DABSL_USE_EXTERNAL_GOOGLETEST=ON -DABSL_FIND_GOOGLETEST=ON` 189