Opt in to the default CMake install path (#994)

CXX-2703

Allow user to opt in to the default CMake install path by setting -DUSE_DEFAULT_INSTALL_PATH=ON

---------

Co-authored-by: Kevin Albertson <[email protected]>

Author: kkloberdanz

CMakeLists.txt

@@ -130,9 +130,12 @@ To build static libraries only, set both BUILD_SHARED_LIBS and BUILD_SHARED_AND_
 endif()
 
 
-# If the user did not customize the install prefix,
-# set it to live under build so we don't inadvertently pollute /usr/local
-if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
+option(USE_DEFAULT_INSTALL_PATH "Override the CMake default installation path" OFF)
+if(NOT CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT AND USE_DEFAULT_INSTALL_PATH)
+    message(FATAL_ERROR "You cannot set both CMAKE_INSTALL_PREFIX and USE_DEFAULT_INSTALL_PATH")
+endif()
+if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT AND NOT USE_DEFAULT_INSTALL_PATH)
+    message(WARNING "the CMake default install path is being overridden to the build directory. This behavior will not be the default in a future release. Build with -DUSE_DEFAULT_INSTALL_PATH=ON to opt into what will be the default behavior in a future release. Setting install path to: ${CMAKE_BINARY_DIR}/install")
     set (CMAKE_INSTALL_PREFIX "${CMAKE_BINARY_DIR}/install" CACHE PATH "default install path" FORCE)
 endif()
 

docs/content/mongocxx-v3/installation/linux.md

@@ -99,7 +99,7 @@ from source. To configure `mongocxx` for installation into `/usr/local` as well,
 ```
 cmake ..                                \
     -DCMAKE_BUILD_TYPE=Release          \
-    -DCMAKE_INSTALL_PREFIX=/usr/local
+    -DUSE_DEFAULT_INSTALL_PATH=ON
 ```
 
 These options can be freely mixed with a C++17 polyfill option. For instance, this is how a user
@@ -108,7 +108,7 @@ would run the command above with the Boost polyfill option:
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
     -DBSONCXX_POLY_USE_BOOST=1                      \
-    -DCMAKE_INSTALL_PREFIX=/usr/local
+    -DUSE_DEFAULT_INSTALL_PATH=ON
 ```
 
 ### Step 5: Build and install the driver

docs/content/mongocxx-v3/installation/macos.md

@@ -99,7 +99,7 @@ from source. To configure `mongocxx` for installation into `/usr/local` as well,
 ```
 cmake ..                                \
     -DCMAKE_BUILD_TYPE=Release          \
-    -DCMAKE_INSTALL_PREFIX=/usr/local
+    -DUSE_DEFAULT_INSTALL_PATH=ON
 ```
 
 These options can be freely mixed with a C++17 polyfill option. For instance, this is how a user
@@ -108,7 +108,7 @@ would run the command above with the Boost polyfill option:
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
     -DBSONCXX_POLY_USE_BOOST=1                      \
-    -DCMAKE_INSTALL_PREFIX=/usr/local
+    -DUSE_DEFAULT_INSTALL_PATH=ON
 ```
 
 ### Step 5: Build and install the driver