CXX-1201 Support running examples against various topologies (#1190)

* Remove examples/projects/CMakeLists.txt

* Remove obsolete file(GLOB) for Markdown files under examples

* Add examples/add_subdirectory to dist files

* Add MONGOCXX_TEST_TOPOLOGY to EVG config

* Replace add_subdirectory() with file(GLOB_RECURSE) for existing examples

* Replace POST_BUILD COMMAND with run-example-* targets

* CXX-1201 unskip building examples/mongocxx/change_streams.cpp

* CXX-1201 unskip examples/mongocxx/client_session.cpp

* CXX-1201 unskip examples/mongocxx/with_transaction.cpp

* CXX-1201 unskip examples/mongocxx/causal_consistency.cpp

* CXX-1201 unskip building mongocxx encryption examples

* Match replicaSet URI option with mongo orchestration config

* Emit example output to stdout

* Disable printing of error messages on Evergreen due to MSBuild

* Disable implicit build dependency on executable targets

* Add file(GLOB_RECURSE) for API examples

* Avoid compiling fwd.hpp headers

* Add support for Markdown API docs

Author: eramongodb

.evergreen/test.sh

@@ -12,6 +12,7 @@ set -o pipefail
 : "${cse_gcp_email:?}"
 : "${cse_gcp_privatekey:?}"
 : "${distro_id:?}" # Required by find-cmake-latest.sh.
+: "${MONGOCXX_TEST_TOPOLOGY:?}"
 
 : "${CRYPT_SHARED_LIB_PATH:-}"
 : "${disable_slow_tests:-}"
@@ -224,15 +225,20 @@ fi
 pushd "${working_dir:?}/build"
 
 if [[ "${OSTYPE:?}" =~ cygwin ]]; then
-  CTEST_OUTPUT_ON_FAILURE=1 "${cmake_binary:?}" --build . --target RUN_TESTS -- /p:Configuration="${build_type:?}" /verbosity:minimal
+  CTEST_OUTPUT_ON_FAILURE=1 "${cmake_binary:?}" --build . --config "${build_type:?}" --target RUN_TESTS -- /verbosity:minimal
+
+  echo "Building examples..."
+  "${cmake_binary:?}" --build . --config "${build_type:?}" --target examples/examples
+  echo "Building examples... done."
+
   # Only run examples if MONGODB_API_VERSION is unset. We do not append
   # API version to example clients, so examples will fail when requireApiVersion
   # is true.
   if [[ -z "$MONGODB_API_VERSION" ]]; then
     echo "Running examples..."
-    if ! CTEST_OUTPUT_ON_FAILURE=1 "${cmake_binary:?}" --build . --target examples/run-examples -- /p:Configuration="${build_type:?}" /verbosity:minimal >|output.txt 2>&1; then
+    if ! "${cmake_binary:?}" --build . --config "${build_type:?}" --target examples/run-examples --parallel 1 -- /verbosity:minimal >|output.txt 2>&1; then
       # Only emit output on failure.
-      cat output.txt 1>&2
+      cat output.txt
       exit 1
     fi
     echo "Running examples... done."
@@ -278,42 +284,21 @@ else
   run_test ./src/mongocxx/test/test_read_write_concern_specs
   run_test ./src/mongocxx/test/test_unified_format_spec
 
-  # Some platforms like OS X don't support the /mode syntax to the -perm option
-  # of find(1), and some platforms like Ubuntu 16.04 don't support the +mode
-  # syntax, so we use Perl to help us find executable files.
-  EXAMPLES="$(find examples -type f | sort | perl -nlwe 'print if -x')"
+  echo "Building examples..."
+  "${cmake_binary:?}" --build . --target examples
+  echo "Building examples... done."
 
   # Only run examples if MONGODB_API_VERSION is unset. We do not append
   # API version to example clients, so examples will fail when requireApiVersion
   # is true.
   if [[ -z "${MONGODB_API_VERSION:-}" ]]; then
-    for test in ${EXAMPLES:?}; do
-      echo "Running ${test:?}"
-      case "${test:?}" in
-      *encryption*)
-        echo " - Skipping client side encryption example"
-        ;;
-      *change_stream*)
-        echo " - TODO CXX-1201, enable for servers that support change streams"
-        ;;
-      *client_session*)
-        echo " - TODO CXX-1201, enable for servers that support change streams"
-        ;;
-      *with_transaction*)
-        echo " - TODO CXX-1201, enable for servers that support transactions"
-        ;;
-      *causal_consistency*)
-        echo " - TODO CXX-1201, enable for servers that support transactions"
-        ;;
-      *)
-        if ! run_test "${test:?}" >|output.txt 2>&1; then
-          # Only emit output on failure.
-          cat output.txt 1>&2
-          exit 1
-        fi
-        ;;
-      esac
-    done
+    echo "Running examples..."
+    if ! "${cmake_binary:?}" --build . --target run-examples --parallel 1 >|output.txt 2>&1; then
+      # Only emit output on failure.
+      cat output.txt
+      exit 1
+    fi
+    echo "Running examples... done."
   fi
 fi
 

.mci.yml

@@ -512,6 +512,7 @@ functions:
                   - example_projects_ldflags
                   - generator
                   - lib_dir
+                  - MONGOCXX_TEST_TOPOLOGY
                   - MONGODB_API_VERSION
                   - platform
                   - TEST_WITH_ASAN
@@ -789,6 +790,8 @@ tasks:
         # Call "install_c_driver" before "test" to build static C driver libraries. Example projects require static C driver libraries.
         - func: "install_c_driver"
         - func: "test"
+          vars:
+              MONGOCXX_TEST_TOPOLOGY: single
 
     - name: compile_and_test_with_shared_libs_extra_alignment
       commands:
@@ -804,6 +807,8 @@ tasks:
           vars:
               BSON_EXTRA_ALIGNMENT: 1
         - func: "test"
+          vars:
+              MONGOCXX_TEST_TOPOLOGY: single
 
     - name: compile_and_test_with_shared_libs_cxx20
       commands:
@@ -819,8 +824,9 @@ tasks:
         - func: "install_c_driver"
         - func: "test"
           vars:
-              REQUIRED_CXX_STANDARD: 20
               example_projects_cxx_standard: 20
+              MONGOCXX_TEST_TOPOLOGY: single
+              REQUIRED_CXX_STANDARD: 20
 
     - name: compile_and_test_with_shared_libs_extra_alignment_cxx20
       commands:
@@ -839,8 +845,9 @@ tasks:
               BSON_EXTRA_ALIGNMENT: 1
         - func: "test"
           vars:
-              REQUIRED_CXX_STANDARD: 20
               example_projects_cxx_standard: 20
+              MONGOCXX_TEST_TOPOLOGY: single
+              REQUIRED_CXX_STANDARD: 20
 
     - name: compile_with_shared_libs
       commands:
@@ -897,6 +904,7 @@ tasks:
         - func: "install_c_driver"
         - func: "test"
           vars:
+              MONGOCXX_TEST_TOPOLOGY: single
               USE_STATIC_LIBS: 1
 
     - name: compile_and_test_with_static_libs_extra_alignment
@@ -916,6 +924,7 @@ tasks:
               BSON_EXTRA_ALIGNMENT: 1
         - func: "test"
           vars:
+              MONGOCXX_TEST_TOPOLOGY: single
               USE_STATIC_LIBS: 1
 
     - name: compile_and_test_with_shared_libs_replica_set
@@ -932,6 +941,8 @@ tasks:
         - func: "run_kms_servers"
         - func: "install_c_driver"
         - func: "test"
+          vars:
+              MONGOCXX_TEST_TOPOLOGY: replica
 
     - name: compile_and_test_with_shared_libs_sharded_cluster
       commands:
@@ -947,6 +958,8 @@ tasks:
         - func: "run_kms_servers"
         - func: "install_c_driver"
         - func: "test"
+          vars:
+              MONGOCXX_TEST_TOPOLOGY: sharded
 
     # Auto downloading the C driver in the C++ build does not currently include
     # support for libmongocrypt, therefore it is not configured with
@@ -965,6 +978,8 @@ tasks:
         - func: "clone_drivers-evergreen-tools"
         - func: "run_kms_servers"
         - func: "test"
+          vars:
+              MONGOCXX_TEST_TOPOLOGY: replica
 
     - name: compile_and_test_with_shared_libs_sharded_cluster_with_libmongocrypt
       commands:
@@ -979,6 +994,8 @@ tasks:
         - func: "clone_drivers-evergreen-tools"
         - func: "run_kms_servers"
         - func: "test"
+          vars:
+              MONGOCXX_TEST_TOPOLOGY: sharded
 
     - name: uninstall_check
       commands:
@@ -1141,6 +1158,7 @@ tasks:
         - func: "run_kms_servers"
         - func: "test"
           vars:
+              MONGOCXX_TEST_TOPOLOGY: single
               MONGODB_API_VERSION: 1
 
     - name: test_versioned_api_accept_version_two
@@ -1155,6 +1173,8 @@ tasks:
         - func: "clone_drivers-evergreen-tools"
         - func: "run_kms_servers"
         - func: "test"
+          vars:
+              MONGOCXX_TEST_TOPOLOGY: single
 
     - name: docker_build_arm
       run_on:

Doxyfile

@@ -1031,7 +1031,8 @@ EXCLUDE_SYMBOLS        = bsoncxx::detail \
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = examples
+EXAMPLE_PATH           = docs \
+                         examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

docs/CMakeLists.txt

@@ -14,7 +14,7 @@
 
 add_subdirectory (themes)
 
-file (GLOB_RECURSE docs_DIST_mds RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} content/*.md)
+file (GLOB_RECURSE docs_DIST_mds RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} api/*.md content/*.md)
 file (GLOB docs_DIST_htmls RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} layouts/shortcodes/*.html)
 file (GLOB docs_DIST_tomls RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.toml data/*.toml)