feat(generator): more stable googleapis proto links

We want to minimize the number of changes when we change the commit SHA for googleapis/googleapis. With this change we use a Doxygen custom command in the header files. The CMake file defines this command to include the embedded SHA. The arguments to the command *should* be more stable, but will change when proto definitions are moved in their `.proto` file.
googleapis · Nov 16, 2021 · dcf2be3 · dcf2be3
1 parent 30bc940
commit dcf2be3
Show file tree

Hide file tree

Showing 32 changed files with 469 additions and 508 deletions.
diff --git a/ci/cloudbuild/builds/generate-libraries.sh b/ci/cloudbuild/builds/generate-libraries.sh
@@ -21,14 +21,10 @@ source module ci/cloudbuild/builds/lib/bazel.sh
 source module ci/cloudbuild/builds/lib/git.sh
 
 bazel_output_base="$(bazel info output_base)"
-googleapis_hash=$(bazel query \
-  'kind(http_archive, //external:com_google_googleapis)' --output=build |
-  sed -n 's/^.*strip_prefix = "googleapis-\(\S*\)"\,.*$/\1/p')
 
 io::log_h2 "Running generator"
 bazel run --action_env=GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes \
   //generator:google-cloud-cpp-codegen -- \
-  --googleapis_commit_hash="${googleapis_hash}" \
   --protobuf_proto_path="${bazel_output_base}"/external/com_google_protobuf/src \
   --googleapis_proto_path="${bazel_output_base}"/external/com_google_googleapis \
   --output_path="${PROJECT_ROOT}" \

diff --git a/cmake/GoogleapisConfig.cmake b/cmake/GoogleapisConfig.cmake
@@ -0,0 +1,30 @@
+# ~~~
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ~~~
+
+# Give application developers a hook to configure the version and hash
+# downloaded from GitHub.
+set(GOOGLE_CLOUD_CPP_GOOGLEAPIS_COMMIT_SHA
+    "53432afb877cb3c1920f73e6621daa8c24f86522"
+    CACHE STRING "Configure the commit SHA (or tag) for the googleapis protos.")
+mark_as_advanced(GOOGLE_CLOUD_CPP_GOOGLEAPIS_SHA)
+set(GOOGLE_CLOUD_CPP_GOOGLEAPIS_SHA256
+    "485631b0f2f54e344096263980f1ce8f357c72403da080a552df317eeda1ea7b"
+    CACHE STRING "Configure the SHA256 checksum of the googleapis tarball.")
+mark_as_advanced(GOOGLE_CLOUD_CPP_GOOGLEAPIS_SHA256)
+
+set(DOXYGEN_ALIASES
+    "googleapis_link{2}=\"[\\1](https://github.com/googleapis/googleapis/blob/${GOOGLE_CLOUD_CPP_GOOGLEAPIS_COMMIT_SHA}/\\2)\""
+)
diff --git a/external/googleapis/CMakeLists.txt b/external/googleapis/CMakeLists.txt
@@ -14,13 +14,11 @@
 # limitations under the License.
 # ~~~
 
-# Give application developers a hook to configure the version and hash
-# downloaded from GitHub.
+include(GoogleapisConfig)
+
 set(GOOGLE_CLOUD_CPP_GOOGLEAPIS_URL
-    "https://github.com/googleapis/googleapis/archive/53432afb877cb3c1920f73e6621daa8c24f86522.tar.gz"
+    "https://github.com/googleapis/googleapis/archive/${GOOGLE_CLOUD_CPP_GOOGLEAPIS_COMMIT_SHA}.tar.gz"
 )
-set(GOOGLE_CLOUD_CPP_GOOGLEAPIS_SHA256
-    "485631b0f2f54e344096263980f1ce8f357c72403da080a552df317eeda1ea7b")
 
 set(EXTERNAL_GOOGLEAPIS_SOURCE
     "${PROJECT_BINARY_DIR}/external/googleapis/src/googleapis_download")

diff --git a/generator/generator_test.cc b/generator/generator_test.cc
@@ -164,11 +164,9 @@ TEST_F(GeneratorTest, GenerateServicesSuccess) {
 
   std::string actual_error;
   Generator generator;
-  auto result = generator.Generate(
-      service_file_descriptor,
-      {"product_path=google/cloud/foo"
-       ",googleapis_commit_hash=59f97e6044a1275f83427ab7962a154c00d915b5"},
-      context_.get(), &actual_error);
+  auto result = generator.Generate(service_file_descriptor,
+                                   {"product_path=google/cloud/foo"},
+                                   context_.get(), &actual_error);
   EXPECT_TRUE(result);
   EXPECT_TRUE(actual_error.empty());
 }

diff --git a/generator/integration_tests/generator_integration_test.cc b/generator/integration_tests/generator_integration_test.cc
@@ -97,7 +97,6 @@ class GeneratorIntegrationTest : public testing::TestWithParam<std::string> {
                           "Codegen C++ Generator");
 
     product_path_ = "generator/integration_tests/golden/";
-    googleapis_commit_hash_ = "59f97e6044a1275f83427ab7962a154c00d915b5";
     copyright_year_ = CurrentCopyrightYear();
     omit_rpc1_ = "Omitted1";
     omit_rpc2_ = "GoldenKitchenSink.Omitted2";
@@ -114,8 +113,6 @@ class GeneratorIntegrationTest : public testing::TestWithParam<std::string> {
     args.emplace_back("--proto_path=" + code_path);
     args.emplace_back("--cpp_codegen_out=" + output_path_);
     args.emplace_back("--cpp_codegen_opt=product_path=" + product_path_);
-    args.emplace_back("--cpp_codegen_opt=googleapis_commit_hash=" +
-                      googleapis_commit_hash_);
     args.emplace_back("--cpp_codegen_opt=copyright_year=" + copyright_year_);
     args.emplace_back("--cpp_codegen_opt=omit_rpc=" + omit_rpc1_);
     args.emplace_back("--cpp_codegen_opt=omit_rpc=" + omit_rpc2_);
@@ -143,7 +140,6 @@ class GeneratorIntegrationTest : public testing::TestWithParam<std::string> {
   std::string product_path_;
   std::string output_path_;
   std::string golden_path_;
-  std::string googleapis_commit_hash_;
   std::string copyright_year_;
   std::string omit_rpc1_;
   std::string omit_rpc2_;

diff --git a/generator/integration_tests/golden/golden_kitchen_sink_client.h b/generator/integration_tests/golden/golden_kitchen_sink_client.h
@@ -91,7 +91,7 @@ class GoldenKitchenSinkClient {
    *  Must be set to a value less than or equal to 3600 (1 hour). If a value is
    *  not specified, the token's lifetime will be set to a default value of one
    *  hour.
-   * @return [google::test::admin::database::v1::GenerateAccessTokenResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L872)
+   * @return @googleapis_link{google::test::admin::database::v1::GenerateAccessTokenResponse,generator/integration_tests/test.proto#L872}
    */
   StatusOr<google::test::admin::database::v1::GenerateAccessTokenResponse>
   GenerateAccessToken(std::string const& name, std::vector<std::string> const& delegates, std::vector<std::string> const& scope, google::protobuf::Duration const& lifetime);
@@ -116,7 +116,7 @@ class GoldenKitchenSinkClient {
    *  grants access to.
    * @param include_email  Include the service account email in the token. If set to `true`, the
    *  token will contain `email` and `email_verified` claims.
-   * @return [google::test::admin::database::v1::GenerateIdTokenResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L914)
+   * @return @googleapis_link{google::test::admin::database::v1::GenerateIdTokenResponse,generator/integration_tests/test.proto#L914}
    */
   StatusOr<google::test::admin::database::v1::GenerateIdTokenResponse>
   GenerateIdToken(std::string const& name, std::vector<std::string> const& delegates, std::string const& audience, bool include_email);
@@ -147,7 +147,7 @@ class GoldenKitchenSinkClient {
    *  entries in `entries`. If a log entry already has a label with the same key
    *  as a label in this parameter, then the log entry's label is not changed.
    *  See [LogEntry][google.logging.v2.LogEntry]. Test delimiter$
-   * @return [google::test::admin::database::v1::WriteLogEntriesResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L953)
+   * @return @googleapis_link{google::test::admin::database::v1::WriteLogEntriesResponse,generator/integration_tests/test.proto#L953}
    */
   StatusOr<google::test::admin::database::v1::WriteLogEntriesResponse>
   WriteLogEntries(std::string const& log_name, std::map<std::string, std::string> const& labels);
@@ -180,7 +180,7 @@ class GoldenKitchenSinkClient {
    *      "organization/[ORGANIZATION_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]/views/[VIEW_ID]"
    *      "billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]/views/[VIEW_ID]"
    *      "folders/[FOLDER_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]/views/[VIEW_ID]"
-   * @return [google::test::admin::database::v1::TailLogEntriesResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L1214)
+   * @return @googleapis_link{google::test::admin::database::v1::TailLogEntriesResponse,generator/integration_tests/test.proto#L1214}
    */
   StreamRange<google::test::admin::database::v1::TailLogEntriesResponse>
   TailLogEntries(std::vector<std::string> const& resource_names);
@@ -196,25 +196,25 @@ class GoldenKitchenSinkClient {
    * @param key_types  Filters the types of keys the user wants to include in the list
    *  response. Duplicate key types are not allowed. If no key type
    *  is provided, all keys are returned.
-   * @return [google::test::admin::database::v1::ListServiceAccountKeysResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L1286)
+   * @return @googleapis_link{google::test::admin::database::v1::ListServiceAccountKeysResponse,generator/integration_tests/test.proto#L1286}
    */
   StatusOr<google::test::admin::database::v1::ListServiceAccountKeysResponse>
   ListServiceAccountKeys(std::string const& name, std::vector<google::test::admin::database::v1::ListServiceAccountKeysRequest::KeyType> const& key_types);
 
   /**
    * Generates an OAuth 2.0 access token for a service account.
    *
-   * @param request [google::test::admin::database::v1::GenerateAccessTokenRequest](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L835)
-   * @return [google::test::admin::database::v1::GenerateAccessTokenResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L872)
+   * @param request @googleapis_link{google::test::admin::database::v1::GenerateAccessTokenRequest,generator/integration_tests/test.proto#L835}
+   * @return @googleapis_link{google::test::admin::database::v1::GenerateAccessTokenResponse,generator/integration_tests/test.proto#L872}
    */
   StatusOr<google::test::admin::database::v1::GenerateAccessTokenResponse>
   GenerateAccessToken(google::test::admin::database::v1::GenerateAccessTokenRequest const& request);
 
   /**
    * Generates an OpenID Connect ID token for a service account.
    *
-   * @param request [google::test::admin::database::v1::GenerateIdTokenRequest](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L881)
-   * @return [google::test::admin::database::v1::GenerateIdTokenResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L914)
+   * @param request @googleapis_link{google::test::admin::database::v1::GenerateIdTokenRequest,generator/integration_tests/test.proto#L881}
+   * @return @googleapis_link{google::test::admin::database::v1::GenerateIdTokenResponse,generator/integration_tests/test.proto#L914}
    */
   StatusOr<google::test::admin::database::v1::GenerateIdTokenResponse>
   GenerateIdToken(google::test::admin::database::v1::GenerateIdTokenRequest const& request);
@@ -228,8 +228,8 @@ class GoldenKitchenSinkClient {
    * different resources (projects, organizations, billing accounts or
    * folders)
    *
-   * @param request [google::test::admin::database::v1::WriteLogEntriesRequest](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L920)
-   * @return [google::test::admin::database::v1::WriteLogEntriesResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L953)
+   * @param request @googleapis_link{google::test::admin::database::v1::WriteLogEntriesRequest,generator/integration_tests/test.proto#L920}
+   * @return @googleapis_link{google::test::admin::database::v1::WriteLogEntriesResponse,generator/integration_tests/test.proto#L953}
    */
   StatusOr<google::test::admin::database::v1::WriteLogEntriesResponse>
   WriteLogEntries(google::test::admin::database::v1::WriteLogEntriesRequest const& request);
@@ -238,7 +238,7 @@ class GoldenKitchenSinkClient {
    * Lists the logs in projects, organizations, folders, or billing accounts.
    * Only logs that have entries are listed.
    *
-   * @param request [google::test::admin::database::v1::ListLogsRequest](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L956)
+   * @param request @googleapis_link{google::test::admin::database::v1::ListLogsRequest,generator/integration_tests/test.proto#L956}
    * @return std::string
    */
   StreamRange<std::string>
@@ -248,17 +248,17 @@ class GoldenKitchenSinkClient {
    * Streaming read of log entries as they are ingested. Until the stream is
    * terminated, it will continue reading logs.
    *
-   * @param request [google::test::admin::database::v1::TailLogEntriesRequest](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L1182)
-   * @return [google::test::admin::database::v1::TailLogEntriesResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L1214)
+   * @param request @googleapis_link{google::test::admin::database::v1::TailLogEntriesRequest,generator/integration_tests/test.proto#L1182}
+   * @return @googleapis_link{google::test::admin::database::v1::TailLogEntriesResponse,generator/integration_tests/test.proto#L1214}
    */
   StreamRange<google::test::admin::database::v1::TailLogEntriesResponse>
   TailLogEntries(google::test::admin::database::v1::TailLogEntriesRequest const& request);
 
   /**
    * Lists every [ServiceAccountKey][google.iam.admin.v1.ServiceAccountKey] for a service account.
    *
-   * @param request [google::test::admin::database::v1::ListServiceAccountKeysRequest](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L1254)
-   * @return [google::test::admin::database::v1::ListServiceAccountKeysResponse](https://github.com/googleapis/googleapis/blob/59f97e6044a1275f83427ab7962a154c00d915b5/generator/integration_tests/test.proto#L1286)
+   * @param request @googleapis_link{google::test::admin::database::v1::ListServiceAccountKeysRequest,generator/integration_tests/test.proto#L1254}
+   * @return @googleapis_link{google::test::admin::database::v1::ListServiceAccountKeysResponse,generator/integration_tests/test.proto#L1286}
    */
   StatusOr<google::test::admin::database::v1::ListServiceAccountKeysResponse>
   ListServiceAccountKeys(google::test::admin::database::v1::ListServiceAccountKeysRequest const& request);