CXX-2579 use standard directories in main install instructions (#944)

* fix link rendering on configuration page

* include `/lib` in CMAKE_INSTALL_RPATH instruction

And explain rationale. This can help a consumer locate libbsoncxx.so if the consumer only links to full path of libmongocxx.so.

* replace `/opt/`  with `$HOME`

To prevent requiring users to have additional permissions.
Installing to `/opt` on macOS requires root permissions.

* add "Installing to non-standard directories" section to advanced.md

* add instructions for specifying a custom C driver install

* use standard install directories in main installation instructions

* add instructions for fixes to locate shared libraries

* use <install-dir>, not /usr/local, for uninstall example

Co-authored-by: Ezra Chung <[email protected]>

* exclude `CMAKE_PREFIX_PATH` or `CMAKE_INSTALL_PREFIX` from unrelated examples

* combine `For Linux and macOS` and `For Windows` sections

The instructions are no longer platform specific.

---------

Co-authored-by: Ezra Chung <[email protected]>

Author: kevinAlbs

docs/content/mongocxx-v3/configuration.md

@@ -9,7 +9,7 @@ title = "Configuring the mongocxx driver"
 In the mongocxx driver, most configuration is done via the [connection
 URI](https://docs.mongodb.com/manual/reference/connection-string/).  Some
 additional connection options are possible via the
-[mongocxx::options::client] ({{< api3ref classmongocxx_1_1options_1_1client
+[mongocxx::options::client]({{< api3ref classmongocxx_1_1options_1_1client
 >}}) class.
 
 ## Configuring TLS/SSL
@@ -21,7 +21,7 @@ To enable TLS (SSL), set `tls=true` in the URI:
 By default, mongocxx will verify server certificates against the local
 system CA list.  You can override that either by specifying different settings in
 the connection string, or by creating a
-[mongocxx::options::tls] ({{< api3ref classmongocxx_1_1options_1_1tls >}})
+[mongocxx::options::tls]({{< api3ref classmongocxx_1_1options_1_1tls >}})
 object and passing it to `tls_opts` on mongocxx::options::client.
 
 For example, to use a custom CA or to disable certificate validation,
@@ -109,7 +109,7 @@ See the MongoDB server
 for more information about determining the subject name from the
 certificate.
 
-The PEM file can also be specified using the [mongocxx::options::tls] ({{< api3ref classmongocxx_1_1options_1_1tls >}}) class, see the first "Configuring TLS/SSL" example above.
+The PEM file can also be specified using the [mongocxx::options::tls]({{< api3ref classmongocxx_1_1options_1_1tls >}}) class, see the first "Configuring TLS/SSL" example above.
 
 ### Kerberos (GSSAPI)
 

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

@@ -26,32 +26,26 @@ dependencies as static libraries rather than the typical shared libraries.  Thes
 produce library artifacts that will behave differently.  Ensure you have a complete understanding
 of the implications of the various linking approaches before utilizing these options.
 
-### For Linux and macOS
-
-#### Configuring with `mongocxx` 3.2.x or newer
+### Configuring with `mongocxx` 3.2.x or newer
 
 Users have the option to build `mongocxx` as a static library. **This is not recommended for novice
 users.** A user can enable this behavior with the `-DBUILD_SHARED_LIBS` option:
 
 ```sh
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
-    -DBUILD_SHARED_LIBS=OFF                         \
-    -DCMAKE_PREFIX_PATH=/opt/mongo-c-driver         \
-    -DCMAKE_INSTALL_PREFIX=/opt/mongo-cxx-driver
+    -DBUILD_SHARED_LIBS=OFF
 ```
 
-#### Configuring with `mongocxx` 3.5.0 or newer
+### Configuring with `mongocxx` 3.5.0 or newer
 
 Users have the option to build `mongocxx` as both static and shared libraries. A user can enable
 this behavior with the `-DBUILD_SHARED_AND_STATIC_LIBS` option:
 
 ```sh
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
-    -DBUILD_SHARED_AND_STATIC_LIBS=ON               \
-    -DCMAKE_PREFIX_PATH=/opt/mongo-c-driver         \
-    -DCMAKE_INSTALL_PREFIX=/opt/mongo-cxx-driver
+    -DBUILD_SHARED_AND_STATIC_LIBS=ON
 ```
 
 Users have the option to build `mongocxx` as a shared library that has statically linked
@@ -61,57 +55,220 @@ Users have the option to build `mongocxx` as a shared library that has staticall
 ```sh
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
-    -DBUILD_SHARED_LIBS_WITH_STATIC_MONGOC=ON       \
-    -DCMAKE_PREFIX_PATH=/opt/mongo-c-driver         \
-    -DCMAKE_INSTALL_PREFIX=/opt/mongo-cxx-driver
+    -DBUILD_SHARED_LIBS_WITH_STATIC_MONGOC=ON
 ```
 
-### For Windows
+## Disabling tests
 
-#### Configuring with `mongocxx` 3.2.x or newer
+Pass `-DENABLE_TESTS=OFF` as a cmake option to disable configuration of test targets.
 
-Users have the option to build `mongocxx` as a static library. **This is not recommended for novice
-users.** A user can enable this behavior with the `-DBUILD_SHARED_LIBS` option:
+```sh
+cmake .. -DENABLE_TESTS=OFF
+cmake --build .. --target help
+# No test targets are configured.
+```
+
+## Installing to non-standard directories
+
+To install the C++ driver to a non-standard directory, specify `CMAKE_INSTALL_PREFIX` to the desired
+install path:
 
 ```sh
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
-    -DBUILD_SHARED_LIBS=OFF                         \
-    -DCMAKE_PREFIX_PATH=C:\mongo-c-driver           \
-    -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver
+    -DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver
 ```
 
-#### Configuring with `mongocxx` 3.5.0 or newer
+Consider also specifying the `-DCMAKE_INSTALL_RPATH=` option to the `lib` directory of the install.
+This may enable libmongocxx.so to locate libbsoncxx.so:
 
-Users have the option to build `mongocxx` as both static and shared libraries. A user can enable
-this behavior with the `-DBUILD_SHARED_AND_STATIC_LIBS` option:
+```sh
+cmake ..                                             \
+    -DCMAKE_BUILD_TYPE=Release                       \
+    -DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver    \
+    -DCMAKE_INSTALL_RPATH=$HOME/mongo-cxx-driver/lib
+```
+
+If the C driver is installed to a non-standard directory, specify `CMAKE_PREFIX_PATH` to the install
+path of the C driver:
 
 ```sh
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
-    -DBUILD_SHARED_AND_STATIC_LIBS=ON               \
-    -DCMAKE_PREFIX_PATH=C:\mongo-c-driver           \
-    -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver
+    -DCMAKE_PREFIX_PATH=$HOME/mongo-c-driver        \
+    -DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver
 ```
 
-Users have the option to build `mongocxx` as a shared library that has statically linked
-`libmongoc`. **This is not recommended for novice users.** A user can enable this behavior with the
-`-DBUILD_SHARED_LIBS_WITH_STATIC_MONGOC` option:
+> *Note* If you need multiple paths in a CMake PATH variable, separate them with a semicolon like
+> this:
+> `-DCMAKE_PREFIX_PATH="/your/cdriver/prefix;/some/other/path"`
+
+### Configuring with `mongocxx` 3.1.x or 3.0.x
+
+Instead of the `-DCMAKE_PREFIX_PATH` option, users must specify the `libmongoc` installation
+directory by using the `-DLIBMONGOC_DIR` and `-DLIBBSON_DIR` options:
 
 ```sh
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
-    -DBUILD_SHARED_LIBS_WITH_STATIC_MONGOC=ON       \
-    -DCMAKE_PREFIX_PATH=C:\mongo-c-driver           \
-    -DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver
+    -DLIBMONGOC_DIR=$HOME/mongo-c-driver            \
+    -DLIBBSON_DIR=$HOME/mongo-c-driver              \
+    -DCMAKE_INSTALL_PREFIX=$HOME/mongo-cxx-driver
 ```
 
-## Disabling tests
+### Fixing the "Library not loaded" error on macOS
 
-Pass `-DENABLE_TESTS=OFF` as a cmake option to disable configuration of test targets.
+Applications linking to a non-standard directory installation may encounter an error loading the C++ driver at runtime. Example:
 
 ```sh
-cmake .. -DENABLE_TESTS=OFF
-cmake --build .. --target help
-# No test targets are configured.
-```
+# Tell pkg-config where to find C++ driver installation.
+export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig
+clang++ app.cpp -std=c++11 $(pkg-config --cflags --libs libmongocxx) -o ./app.out
+./app.out
+# Prints the following error:
+# dyld[3217]: Library not loaded: '@rpath/libmongocxx._noabi.dylib'
+#   Referenced from: '/Users/kevin.albertson/code/app.out'
+#   Reason: tried: '/usr/local/lib/libmongocxx._noabi.dylib' (no such file), '/usr/lib/libmongocxx._noabi.dylib' (no such file)
+# zsh: abort      ./app.out
+```
+
+The default `install name` of the C++ driver on macOS includes `@rpath`:
+```sh
+otool -D $HOME/mongo-cxx-driver/lib/libmongocxx.dylib
+# Prints:
+# /Users/kevin.albertson/mongo-cxx-driver/lib/libmongocxx.dylib:
+# @rpath/libmongocxx._noabi.dylib
+```
+
+Including `@rpath` in the install name allows linking applications to control the list of search paths for the library.
+
+`app.out` includes the load command for `@rpath/libmongocxx._noabi.dylib`. `app.out` does not have entries to substitute for `@rpath`.
+
+There are several ways to consider solving this on macOS:
+
+Pass `DYLD_FALLBACK_LIBRARY_PATH` to the directory containing the C++ driver libraries:
+
+```sh
+DYLD_FALLBACK_LIBRARY_PATH=$HOME/mongo-cxx-driver/lib ./app.out
+# Prints "successfully connected with C++ driver"
+```
+
+Alternatively, the linker option `-Wl,-rpath` can be passed to add entries to substitute for `@rpath`:
+```sh
+# Tell pkg-config where to find C++ driver installation.
+export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig
+# Pass the linker option -rpath to set an rpath in the final executable.
+clang++ app.cpp -std=c++11 -Wl,-rpath,$HOME/mongo-cxx-driver/lib $(pkg-config --cflags --libs libmongocxx) -o ./app.out
+./app.out
+# Prints "successfully connected with C++ driver"
+```
+
+If building the application with cmake, the [Default RPATH settings](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling#default-rpath-settings) include the full RPATH to all used libraries in the build tree. However, when installing, cmake will clear the RPATH of these targets so they are installed with an empty RPATH. This may result in a `Library not loaded` error after install.
+
+Example:
+```sh
+# Build application `app` using the C++ driver from a non-standard install.
+cmake \
+    -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \
+    -DCMAKE_INSTALL_PREFIX=$HOME/app \
+    -DCMAKE_CXX_STANDARD=11 \
+    -Bcmake-build -S.
+cmake --build cmake-build --target app.out
+# Running app.out from build tree includes rpath to C++ driver.
+./cmake-build ./cmake-build/app.out
+# Prints: "successfully connected with C++ driver"
+
+cmake --build cmake-build --target install
+# Running app.out from install tree does not include rpath to C++ driver.
+$HOME/app/bin/app.out
+# Prints "Library not loaded" error.
+```
+
+Consider setting `-DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE` so the rpath for the executable is kept in the install target.
+```sh
+# Build application `app` using the C++ driver from a non-standard install.
+# Use CMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE to keep rpath entry on installed app.
+cmake \
+    -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \
+    -DCMAKE_INSTALL_PREFIX=$HOME/app \
+    -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \
+    -DCMAKE_CXX_STANDARD=11 \
+    -Bcmake-build -S.
+
+cmake --build cmake-build --target install
+$HOME/app/bin/app.out
+# Prints "successfully connected with C++ driver"
+```
+
+See the cmake documentation for [RPATH handling](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling) for more information.
+
+### Fixing the "cannot open shared object file" error on Linux
+
+Applications linking to a non-standard directory installation may encounter an error loading the C++ driver at runtime. Example:
+
+```sh
+# Tell pkg-config where to find C++ driver installation.
+export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig
+g++ -std=c++11 app.cpp $(pkg-config --cflags --libs libmongocxx) -o ./app.out
+./app.out
+# Prints the following error:
+# ./app.out: error while loading shared libraries: libmongocxx.so._noabi: cannot open shared object file: No such file or directory
+```
+
+There are several ways to consider solving this on Linux:
+
+Pass `LD_LIBRARY_PATH` to the directory containing the C++ driver libraries:
+
+```sh
+LD_LIBRARY_PATH=$HOME/mongo-cxx-driver/lib ./app.out
+# Prints "successfully connected with C++ driver"
+```
+
+Alternatively, the linker option `-Wl,-rpath` can be passed to add `rpath` entries:
+```sh
+# Tell pkg-config where to find C++ driver installation.
+export PKG_CONFIG_PATH=$HOME/mongo-cxx-driver/lib/pkgconfig
+# Pass the linker option -rpath to set an rpath in the final executable.
+g++ app.cpp -std=c++11 -Wl,-rpath,$HOME/mongo-cxx-driver/lib $(pkg-config --cflags --libs libmongocxx) -o ./app.out
+./app.out
+# Prints "successfully connected with C++ driver"
+```
+
+If building the application with cmake, the [Default RPATH settings](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling#default-rpath-settings) include the full RPATH to all used libraries in the build tree. However, when installing, cmake will clear the RPATH of these targets so they are installed with an empty RPATH. This may result in a `Library not loaded` error after install.
+
+Example:
+```sh
+# Build application `app` using the C++ driver from a non-standard install.
+cmake \
+    -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \
+    -DCMAKE_INSTALL_PREFIX=$HOME/app \
+    -DCMAKE_CXX_STANDARD=11 \
+    -Bcmake-build -S.
+cmake --build cmake-build --target app.out
+# Running app.out from build tree includes rpath to C++ driver.
+./cmake-build ./cmake-build/app.out
+# Prints: "successfully connected with C++ driver"
+
+cmake --build cmake-build --target install
+# Running app.out from install tree does not include rpath to C++ driver.
+$HOME/app/bin/app.out
+# Prints "cannot open shared object file" error.
+```
+
+Consider setting `-DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE` so the rpath for the executable is kept in the install target.
+```sh
+# Build application `app` using the C++ driver from a non-standard install.
+# Use CMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE to keep rpath entry on installed app.
+cmake \
+    -DCMAKE_PREFIX_PATH=$HOME/mongo-cxx-driver \
+    -DCMAKE_INSTALL_PREFIX=$HOME/app \
+    -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=TRUE \
+    -DCMAKE_CXX_STANDARD=11 \
+    -Bcmake-build -S.
+
+cmake --build cmake-build --target install
+$HOME/app/bin/app.out
+# Prints "successfully connected with C++ driver"
+```
+
+See the cmake documentation for [RPATH handling](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling) for more information.

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

@@ -101,54 +101,13 @@ cmake ..                                \
     -DCMAKE_INSTALL_PREFIX=/usr/local
 ```
 
-If installing to a non-standard directory (i.e., one which the dynamic loader does not search),
-consider specifying the `-DCMAKE_INSTALL_RPATH=` option:
-
-```
-cmake ..                                \
-    -DCMAKE_BUILD_TYPE=Release          \
-    -DCMAKE_INSTALL_PREFIX=/opt/mongo   \
-    -DCMAKE_INSTALL_RPATH=/opt/mongo
-```
-
-In the Unix examples that follow, `mongocxx` is customized in these ways:
-
-* `libmongoc` is found in `/opt/mongo-c-driver`.
-* `mongocxx` is to be installed into `/opt/mongo-cxx-driver`.
-
-With those two distinct (arbitrary) install locations, a user would run this `cmake` command:
-```sh
-cmake ..                                            \
-    -DCMAKE_BUILD_TYPE=Release                      \
-    -DCMAKE_PREFIX_PATH=/opt/mongo-c-driver         \
-    -DCMAKE_INSTALL_PREFIX=/opt/mongo-cxx-driver
-```
-
-> *Note* If you need multiple paths in a CMake PATH variable, separate them with a semicolon like
-> this:
-> `-DCMAKE_PREFIX_PATH="/your/cdriver/prefix;/some/other/path"`
-
 These options can be freely mixed with a C++17 polyfill option. For instance, this is how a user
 would run the command above with the Boost polyfill option:
 ```sh
 cmake ..                                            \
     -DCMAKE_BUILD_TYPE=Release                      \
     -DBSONCXX_POLY_USE_BOOST=1                      \
-    -DCMAKE_PREFIX_PATH=/opt/mongo-c-driver         \
-    -DCMAKE_INSTALL_PREFIX=/opt/mongo-cxx-driver
-```
-
-#### Configuring with `mongocxx` 3.1.x or 3.0.x
-
-Instead of the `-DCMAKE_PREFIX_PATH` option, users must specify the `libmongoc` installation
-directory by using the `-DLIBMONGOC_DIR` and `-DLIBBSON_DIR` options:
-
-```sh
-cmake ..                                            \
-    -DCMAKE_BUILD_TYPE=Release                      \
-    -DLIBMONGOC_DIR=/opt/mongo-c-driver             \
-    -DLIBBSON_DIR=/opt/mongo-c-driver               \
-    -DCMAKE_INSTALL_PREFIX=/opt/mongo-cxx-driver
+    -DCMAKE_INSTALL_PREFIX=/usr/local
 ```
 
 ### Step 5: Build and install the driver
@@ -181,6 +140,6 @@ sudo cmake --build . --target uninstall
 Second, the uninstall script can be called:
 
 ```sh
-sudo /opt/mongo-cxx-driver/share/mongo-cxx-driver/uninstall.sh
+sudo <install-dir>/share/mongo-cxx-driver/uninstall.sh
 ```