diff --git a/cmake/README.md b/cmake/README.md index bbad37c8be..523707d406 100644 --- a/cmake/README.md +++ b/cmake/README.md @@ -34,7 +34,17 @@ [dotnet_win_svg]: https://github.com/google/or-tools/workflows/.Net%20Windows%20CI/badge.svg [dotnet_win_link]: https://github.com/google/or-tools/actions?query=workflow%3A".Net+Windows+CI" -OR-Tools comes with a CMake build script ([CMakeLists.txt](../CMakeLists.txt)) +# Introduction + + +OR-Tools comes with a CMake based build ([CMakeLists.txt](../CMakeLists.txt)) that can be used on a wide range of platforms (the "C" stands for cross-platform). If you don't have CMake installed already, you can download it for free from . @@ -44,19 +54,37 @@ the compiler environment of your choice.
You can either build OR-Tools with CMake as a standalone project or it can be incorporated into an existing CMake project. -**warning: Currently OR-Tools CMake doesn't support Java nor C#.** +**warning: Currently OR-Tools CMake doesn't support Java nor .Net, please use +the Makefile based build instead.** -## Table of Contents +# [Dependencies](#deps) -* [Building OR-Tools with CMake](#building-or-tools-with-cmake) -* [Consuming OR-Tools in a CMake Project](#consuming-or-tools-in-a-cmake-project) -* [Incorporating OR-Tools into a CMake Project](#incorporating-or-tools-into-a-cmake-project) +OR-Tools depends on severals mandatory libraries. You can compile them all at +configure time using the option `-DBUILD_DEPS=ON` (`OFF` by default) or you can +compile few of them using the options below. -For API/ABI compatibility reasons, if you will be using OR-Tools inside a larger -C++ project, we recommend using CMake and incorporate OR-Tools as a CMake -subproject (i.e. using `add_sudirectory()`). +* ZLIB (`BUILD_ZLIB`), +* Google Abseil-cpp (`BUILD_absl`), +* Google Gflags (`BUILD_gflags`), +* Google Glog (`BUILD_glog`), +* Google Protobuf (`BUILD_Protobuf`), +* COIN-OR CoinUtils (`BUILD_CoinUtils`), +* COIN-OR Osi (`BUILD_Osi`), +* COIN-OR Clp (`BUILD_Clp`), +* COIN-OR Cgl (`BUILD_Cgl`), +* COIN-OR Cbc (`BUILD_Cbc`), -## Building OR-Tools with CMake +note: You can disable the support of COIN-OR solvers (i.e. Cbc and Clp solver) by using `-DUSE_COINOR=OFF`. + +OR-Tools also have few (ed compile time) optional solvers support (disabled by default): +* SCIP (`USE_SCIP`), +* CPLEX (`USE_CPLEX`), +* XPRESS (`USE_XPRESS`) + +**warning: Since these solvers require license and are proprietary, so we can't test it on public CI and +support can be broken.** + +# [Building OR-Tools C++ with CMake](#build_cpp) When building OR-Tools as a standalone project on Unix-like systems with GNU Make, the typical workflow is: @@ -69,13 +97,13 @@ cd or-tools 2. Run CMake to configure the build tree. ```sh -cmake -H. -Bbuild -G "Unix Makefiles" +cmake -S. -Bbuild -G "Unix Makefiles" -DBUILD_DEPS=ON ``` note: To get the list of available generators (e.g. Visual Studio), use `-G ""` 3. Afterwards, generated files can be used to compile the project. ```sh -cmake --build build +cmake --build build -v ``` 4. Test the build software (optional). @@ -88,13 +116,36 @@ cmake --build build --target test cmake --build build --target install ``` +# [Building OR-Tools with Python support](#build_python) + +TODO + +# [Building OR-Tools with .Net support](#build_dotnet) + +TODO + +# [Building OR-Tools with Java support](#build_java) + +TODO + +# [Integrating OR-Tools in your CMake Project](#integration) + +You should be able to integrate OR-Tools in your C++ CMake project following one +of these methods. + +For API/ABI compatibility reasons, if you will be using OR-Tools inside a larger +C++ project, we recommend using CMake and incorporate OR-Tools as a CMake +subproject (i.e. using `add_sudirectory()` or `FetchContent`). + ## Consuming OR-Tools in a CMake Project -If you already have OR-Tools installed in your system, you can use the CMake -command +If you already have OR-Tools installed in your system, you can use the CMake command [`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html) to include OR-Tools in your C++ CMake Project. +note: You may need to set [`CMAKE_PREFIX_PATH`](https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure) +in order for CMake to find your OR-Tools installation. + ```cmake cmake_minimum_required(VERSION 3.0.2) project(myproj VERSION 1.0) @@ -108,8 +159,8 @@ target_link_libraries(myapp ortools::ortools) Include directories, compile definitions and compile options will be added automatically to your target as needed. -## Incorporating OR-Tools into a CMake Project - +## Incorporating OR-Tools into a CMake Super Project +### Using add_subdirectory The recommendations below are similar to those for using CMake within the googletest framework () @@ -132,3 +183,30 @@ target_link_libraries(myapp ortools::ortools) Again, include directories, compile definitions and compile options will be added automatically to your target as needed. + +### Using FetchContent +If you have `CMake >= 3.11.4` you can use the built-in module [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) instead. +Note: The **ortools::ortools** target is in this case an ALIAS library target +for the **ortools** library target. + +```cmake +cmake_minimum_required(VERSION 3.11.4) +project(myproj VERSION 1.0 LANGUAGES CXX) + +include(FetchContent) +FetchContent_Declare( + or-tools + GIT_REPOSITORY https://github.com/google/or-tools.git + GIT_TAG master +) + +# After the following call, the CMake targets defined by or-tools +# will be defined and available to the rest of the build +FetchContent_MakeAvailable(or-tools) + +add_executable(myapp main.cpp) +target_link_libraries(myapp ortools::ortools) +``` + +note: You may need to use the option `-DBUILD_DEPS=ON` to get all or-tools +dependencies as well.