impl(generator): emit ud samples and ud dox md files

BUILD.bazel

@@ -249,7 +249,7 @@ cc_library(
 )
 
 cc_library(
-    name = "experimental-universe_domain",
+    name = "universe_domain",
     deps = [
         "//google/cloud:google_cloud_cpp_universe_domain",
     ],

bazel/gapic.bzl

@@ -82,6 +82,7 @@ def cc_gapic_library(name, service_dirs = [], googleapis_deps = [], additional_d
         tags = ["integration-test"],
         deps = [
             "//:" + name,
+            "//:universe_domain",
             "//google/cloud/testing_util:google_cloud_cpp_testing_private",
         ],
     ) for sample in native.glob([d + "samples/*_samples.cc" for d in service_dirs])]

ci/cloudbuild/builds/check-api.sh

@@ -31,10 +31,10 @@ if [ "${GOOGLE_CLOUD_CPP_CHECK_API:-}" ]; then
   readonly ENABLED_FEATURES="${GOOGLE_CLOUD_CPP_CHECK_API}"
   IFS=',' read -ra library_list <<<"${GOOGLE_CLOUD_CPP_CHECK_API}"
 else
-  readonly ENABLED_FEATURES="__ga_libraries__,opentelemetry"
+  readonly ENABLED_FEATURES="__ga_libraries__,opentelemetry,universe_domain"
   mapfile -t library_list < <(cmake -P cmake/print-ga-libraries.cmake 2>&1)
   # These libraries are not "features", but they are part of the public API
-  library_list+=("common" "grpc_utils")
+  library_list+=("common" "grpc_utils" "universe_domain")
   # This is a GA library, not included in __ga_libraries__
   library_list+=("opentelemetry")
 fi
@@ -67,7 +67,7 @@ function check_abi() {
 
   local shortlib="${library#google_cloud_cpp_}"
   local public_headers="${prefix}/include/google/cloud/${shortlib}"
-  if [[ "${shortlib}" == "common" || "${shortlib}" == "grpc_utils" || "${shortlib}" == "oauth2" ]]; then
+  if [[ "${shortlib}" == "common" || "${shortlib}" == "grpc_utils" || "${shortlib}" == "universe_domain" || "${shortlib}" == "oauth2" ]]; then
     # These are special and share their header location.
     public_headers="${prefix}/include/google/cloud"
   elif [[ "${shortlib}" == "storage_grpc" ]]; then

ci/cloudbuild/builds/cmake-install.sh

@@ -164,6 +164,7 @@ expected_dirs+=(
   ./lib64/cmake/google_cloud_cpp_rest_protobuf_internal
   ./lib64/cmake/google_cloud_cpp_storage_grpc
   ./lib64/cmake/google_cloud_cpp_storage_grpc_mocks
+  ./lib64/cmake/google_cloud_cpp_universe_domain
   ./lib64/pkgconfig
 )
 

ci/cloudbuild/builds/lib/features.sh

@@ -42,6 +42,8 @@ function features::always_build() {
     opentelemetry
     # Enable storage_grpc in most builds.
     storage_grpc
+    # Samples require universe domain support.
+    universe_domain
   )
   printf "%s\n" "${list[@]}" | sort -u
 }
@@ -63,6 +65,7 @@ function features::_internal_extra() {
   local list=(
     experimental-bigquery_rest
     opentelemetry
+    universe_domain
   )
   printf "%s\n" "${list[@]}"
 }

ci/cloudbuild/builds/publish-docs.sh

@@ -35,7 +35,7 @@ elif [[ "${LIBRARIES}" == "all_bar_compute" ]]; then
   ENABLED_FEATURES="${ENABLED_FEATURES},-compute"
 else
   mapfile -t FEATURE_LIST < <(printf '%s' "${LIBRARIES}")
-  ENABLED_FEATURES="compute"
+  ENABLED_FEATURES="compute,universe_domain"
 fi
 
 doc_args=(

ci/generate-markdown/update-library-landing-dox.sh

@@ -39,6 +39,7 @@ readonly EXPECTED=(
   "override-authentication.dox"
   "override-endpoint.dox"
   "override-retry-policies.dox"
+  "override-universe-domain.dox"
 )
 for file in "${EXPECTED[@]}"; do
   if [[ ! -r "${DOCDIR}/${file}" ]]; then
@@ -50,6 +51,7 @@ readonly MAIN_DOX="${DOCDIR}/main.dox"
 readonly ENVIRONMENT_DOX="${DOCDIR}/environment-variables.dox"
 readonly OVERRIDE_AUTHENTICATION_DOX="${DOCDIR}/override-authentication.dox"
 readonly OVERRIDE_ENDPOINT_DOX="${DOCDIR}/override-endpoint.dox"
+readonly OVERRIDE_UNIVERSE_DOMAIN_DOX="${DOCDIR}/override-universe-domain.dox"
 readonly OVERRIDE_RETRY_POLICIES_DOX="${DOCDIR}/override-retry-policies.dox"
 
 inject_start="<!-- inject-endpoint-env-vars-start -->"
@@ -196,6 +198,39 @@ _EOF_
   sed -n '/<!-- inject-endpoint-pages-end -->/,$p' "${OVERRIDE_ENDPOINT_DOX}"
 ) | sponge "${OVERRIDE_ENDPOINT_DOX}"
 
+(
+  sed '/<!-- inject-universe-domain-snippet-start -->/q' "${OVERRIDE_UNIVERSE_DOMAIN_DOX}"
+  if [[ ${#samples_cc[@]} -gt 0 ]]; then
+    sample_cc="${samples_cc[0]}"
+    client_name="${clients[${sample_cc}]}"
+    echo 'For example, this will override the default universe domain for `'"${client_name}"'`:'
+    echo
+    echo "@snippet $(basename "${sample_cc}") set-client-universe-domain"
+    if [[ ${#samples_cc[@]} -gt 1 ]]; then
+      echo
+      echo "Follow these links to find examples for other \\c *Client classes:"
+      echo
+      for sample_cc in "${samples_cc[@]}"; do
+        client_name="${clients[${sample_cc}]}"
+        # shellcheck disable=SC2016
+        printf -- '- [\c %s](@ref %s-universe-domain-snippet)\n' "${client_name}" "${client_name}"
+      done
+    fi
+  fi
+  echo
+  sed -n '/<!-- inject-universe-domain-snippet-end -->/,$p' "${OVERRIDE_UNIVERSE_DOMAIN_DOX}"
+) | sponge "${OVERRIDE_UNIVERSE_DOMAIN_DOX}"
+
+(
+  sed '/<!-- inject-universe-domain-pages-start -->/q' "${OVERRIDE_UNIVERSE_DOMAIN_DOX}"
+  for sample_cc in "${samples_cc[@]}"; do
+    client_name="${clients[${sample_cc}]}"
+    printf '\n/*! @page %s-universe-domain-snippet Override %s Universe Domain\n\n@snippet %s set-client-universe-domain\n\n*/\n' \
+      "${client_name}" "${client_name}" "${sample_cc}"
+  done
+  sed -n '/<!-- inject-universe-domain-pages-end -->/,$p' "${OVERRIDE_UNIVERSE_DOMAIN_DOX}"
+) | sponge "${OVERRIDE_UNIVERSE_DOMAIN_DOX}"
+
 (
   sed '/<!-- inject-retry-snippet-start -->/q' "${OVERRIDE_RETRY_POLICIES_DOX}"
   if [[ ${#samples_cc[@]} -gt 0 ]]; then

ci/lib/shard.sh

@@ -36,11 +36,13 @@ readonly DEFAULT_SHARD=(
   bigtable
   spanner
   logging
+  universe_domain
 )
 
 readonly BIGQUERY_SHARD=(
   bigquery
   experimental-bigquery_rest
+  universe_domain
 )
 
 readonly PUBSUB_SHARD=(
@@ -51,6 +53,7 @@ readonly PUBSUB_SHARD=(
   # IAM is included because it has hand-crafted tests and/or examples and is
   # required by Pub/Sub
   iam
+  universe_domain
 )
 
 readonly STORAGE_SHARD=(
@@ -66,6 +69,7 @@ readonly STORAGE_SHARD=(
 readonly TOOLS_SHARD=(
   generator
   docfx
+  universe_domain
 )
 
 function shard::cmake_features() {

cmake/GoogleCloudCppCommon.cmake

@@ -132,12 +132,16 @@ function (google_cloud_cpp_add_samples_relative library path)
         google_cloud_cpp_add_executable(target "${library}" "${source}")
         if (TARGET google-cloud-cpp::${library})
             target_link_libraries(
-                "${target}" PRIVATE google-cloud-cpp::${library}
-                                    google_cloud_cpp_testing)
+                "${target}"
+                PRIVATE google-cloud-cpp::${library}
+                        google-cloud-cpp::universe_domain
+                        google_cloud_cpp_testing)
         elseif (TARGET google-cloud-cpp::experimental-${library})
             target_link_libraries(
-                "${target}" PRIVATE google-cloud-cpp::experimental-${library}
-                                    google_cloud_cpp_testing)
+                "${target}"
+                PRIVATE google-cloud-cpp::experimental-${library}
+                        google-cloud-cpp::universe_domain
+                        google_cloud_cpp_testing)
         endif ()
         google_cloud_cpp_add_common_options("${target}")
         add_test(NAME "${target}" COMMAND "${target}")

generator/integration_tests/BUILD.bazel

@@ -145,6 +145,7 @@ filegroup(
     tags = ["integration-test"],
     deps = [
         ":google_cloud_cpp_generator_golden",
+        "//:universe_domain",
         "//google/cloud/testing_util:google_cloud_cpp_testing_private",
     ],
 ) for sample in glob(["golden/v1/samples/*.cc"])]

generator/integration_tests/CMakeLists.txt

@@ -131,7 +131,9 @@ foreach (fname IN LISTS samples_cc)
     target_link_libraries(
         ${target}
         PRIVATE google_cloud_cpp_generator_golden_testing
-                google_cloud_cpp_generator_golden google_cloud_cpp_testing
+                google_cloud_cpp_generator_golden
+                google_cloud_cpp_universe_domain
+                google_cloud_cpp_testing
                 google_cloud_cpp_testing_grpc)
     google_cloud_cpp_add_common_options(${target})
     add_test(NAME ${target} COMMAND ${target})

generator/integration_tests/golden/doc/override-universe-domain.dox

@@ -0,0 +1,15 @@
+/*!
+@page golden-override-universe-domain How to Override the Default Universe Domain
+
+In some cases, you may need to override the default universe domain used by the client
+library. Use the
+[AddUniverseDomainOption](@ref google::cloud::AddUniverseDomainOption) when initializing the
+client library to change this default.
+
+<!-- inject-universe-domain-snippet-start -->
+<!-- inject-universe-domain-snippet-end -->
+
+*/
+
+// <!-- inject-universe-domain-pages-start -->
+// <!-- inject-universe-domain-pages-end -->

generator/integration_tests/golden/v1/samples/deprecated_client_samples.cc

@@ -23,6 +23,7 @@
 #include "google/cloud/credentials.h"
 #include "google/cloud/internal/getenv.h"
 #include "google/cloud/testing_util/example_driver.h"
+#include "google/cloud/universe_domain.h"
 #include <fstream>
 #include <iostream>
 #include <string>
@@ -47,6 +48,25 @@ void SetClientEndpoint(std::vector<std::string> const& argv) {
   //! [set-client-endpoint]
 }
 
+void SetClientUniverseDomain(std::vector<std::string> const& argv) {
+  if (!argv.empty()) {
+    throw google::cloud::testing_util::Usage{"set-client-universe-domain"};
+  }
+  //! [set-client-universe-domain]
+  google::cloud::Options options;
+
+  // AddUniverseDomainOption interrogates the UnifiedCredentialsOption, if set,
+  // in the provided Options for the Universe Domain associated with the
+  // credentials and adds it to the set of Options.
+  // If no UnifiedCredentialsOption is set, GoogleDefaultCredentials are used.
+  auto ud_options = google::cloud::AddUniverseDomainOption(std::move(options));
+
+  if (!ud_options.ok()) throw std::move(ud_options).status();
+  auto ud_client = google::cloud::golden_v1::DeprecatedServiceClient(
+      google::cloud::golden_v1::MakeDeprecatedServiceConnection(*ud_options));
+  //! [set-client-universe-domain]
+}
+
 //! [custom-idempotency-policy]
 class CustomIdempotencyPolicy
    : public google::cloud::golden_v1::DeprecatedServiceConnectionIdempotencyPolicy {
@@ -130,6 +150,9 @@ void AutoRun(std::vector<std::string> const& argv) {
 
   std::cout << "\nRunning WithServiceAccount() example" << std::endl;
   WithServiceAccount({keyfile});
+
+  std::cout << "\nRunning SetClientUniverseDomain() example" << std::endl;
+  SetClientUniverseDomain({});
 }
 
 }  // namespace
@@ -139,6 +162,7 @@ int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
       {"set-client-endpoint", SetClientEndpoint},
       {"set-retry-policy", SetRetryPolicy},
       {"with-service-account", WithServiceAccount},
+      {"set-client-universe-domain", SetClientUniverseDomain},
       {"auto", AutoRun},
   });
   return example.Run(argc, argv);

generator/integration_tests/golden/v1/samples/golden_kitchen_sink_client_samples.cc

@@ -23,6 +23,7 @@
 #include "google/cloud/credentials.h"
 #include "google/cloud/internal/getenv.h"
 #include "google/cloud/testing_util/example_driver.h"
+#include "google/cloud/universe_domain.h"
 #include <fstream>
 #include <iostream>
 #include <string>
@@ -47,6 +48,25 @@ void SetClientEndpoint(std::vector<std::string> const& argv) {
   //! [set-client-endpoint]
 }
 
+void SetClientUniverseDomain(std::vector<std::string> const& argv) {
+  if (!argv.empty()) {
+    throw google::cloud::testing_util::Usage{"set-client-universe-domain"};
+  }
+  //! [set-client-universe-domain]
+  google::cloud::Options options;
+
+  // AddUniverseDomainOption interrogates the UnifiedCredentialsOption, if set,
+  // in the provided Options for the Universe Domain associated with the
+  // credentials and adds it to the set of Options.
+  // If no UnifiedCredentialsOption is set, GoogleDefaultCredentials are used.
+  auto ud_options = google::cloud::AddUniverseDomainOption(std::move(options));
+
+  if (!ud_options.ok()) throw std::move(ud_options).status();
+  auto ud_client = google::cloud::golden_v1::GoldenKitchenSinkClient(
+      google::cloud::golden_v1::MakeGoldenKitchenSinkConnection(*ud_options));
+  //! [set-client-universe-domain]
+}
+
 //! [custom-idempotency-policy]
 class CustomIdempotencyPolicy
    : public google::cloud::golden_v1::GoldenKitchenSinkConnectionIdempotencyPolicy {
@@ -130,6 +150,9 @@ void AutoRun(std::vector<std::string> const& argv) {
 
   std::cout << "\nRunning WithServiceAccount() example" << std::endl;
   WithServiceAccount({keyfile});
+
+  std::cout << "\nRunning SetClientUniverseDomain() example" << std::endl;
+  SetClientUniverseDomain({});
 }
 
 }  // namespace
@@ -139,6 +162,7 @@ int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
       {"set-client-endpoint", SetClientEndpoint},
       {"set-retry-policy", SetRetryPolicy},
       {"with-service-account", WithServiceAccount},
+      {"set-client-universe-domain", SetClientUniverseDomain},
       {"auto", AutoRun},
   });
   return example.Run(argc, argv);

generator/integration_tests/golden/v1/samples/golden_rest_only_client_samples.cc

@@ -23,6 +23,7 @@
 #include "google/cloud/credentials.h"
 #include "google/cloud/internal/getenv.h"
 #include "google/cloud/testing_util/example_driver.h"
+#include "google/cloud/universe_domain.h"
 #include <fstream>
 #include <iostream>
 #include <string>
@@ -53,6 +54,25 @@ void SetClientEndpoint(std::vector<std::string> const& argv) {
   //! [set-client-endpoint]
 }
 
+void SetClientUniverseDomain(std::vector<std::string> const& argv) {
+  if (!argv.empty()) {
+    throw google::cloud::testing_util::Usage{"set-client-universe-domain"};
+  }
+  //! [set-client-universe-domain]
+  google::cloud::Options options;
+
+  // AddUniverseDomainOption interrogates the UnifiedCredentialsOption, if set,
+  // in the provided Options for the Universe Domain associated with the
+  // credentials and adds it to the set of Options.
+  // If no UnifiedCredentialsOption is set, GoogleDefaultCredentials are used.
+  auto ud_options = google::cloud::AddUniverseDomainOption(std::move(options));
+
+  if (!ud_options.ok()) throw std::move(ud_options).status();
+  auto ud_client = google::cloud::golden_v1::GoldenRestOnlyClient(
+      google::cloud::golden_v1::MakeGoldenRestOnlyConnectionRest(*ud_options));
+  //! [set-client-universe-domain]
+}
+
 //! [custom-idempotency-policy]
 class CustomIdempotencyPolicy
    : public google::cloud::golden_v1::GoldenRestOnlyConnectionIdempotencyPolicy {
@@ -136,6 +156,9 @@ void AutoRun(std::vector<std::string> const& argv) {
 
   std::cout << "\nRunning WithServiceAccount() example" << std::endl;
   WithServiceAccount({keyfile});
+
+  std::cout << "\nRunning SetClientUniverseDomain() example" << std::endl;
+  SetClientUniverseDomain({});
 }
 
 }  // namespace
@@ -145,6 +168,7 @@ int main(int argc, char* argv[]) {  // NOLINT(bugprone-exception-escape)
       {"set-client-endpoint", SetClientEndpoint},
       {"set-retry-policy", SetRetryPolicy},
       {"with-service-account", WithServiceAccount},
+      {"set-client-universe-domain", SetClientUniverseDomain},
       {"auto", AutoRun},
   });
   return example.Run(argc, argv);