Skip to content

Commit a650bf0

Browse files
scotthartscotthart
authored
doc(iam): add quickstart files (#6794)
1 parent 69205cb commit a650bf0

File tree

13 files changed

+570
-5
lines changed

13 files changed

+570
-5
lines changed

‎ci/cloudbuild/builds/checkers.sh

+1
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ time {
8383
declare -A -r GENERATOR_MAP=(
8484
["ci/generate-markdown/generate-readme.sh"]="README.md"
8585
["ci/generate-markdown/generate-bigtable-readme.sh"]="google/cloud/bigtable/README.md"
86+
["ci/generate-markdown/generate-iam-readme.sh"]="google/cloud/iam/README.md"
8687
["ci/generate-markdown/generate-pubsub-readme.sh"]="google/cloud/pubsub/README.md"
8788
["ci/generate-markdown/generate-spanner-readme.sh"]="google/cloud/spanner/README.md"
8889
["ci/generate-markdown/generate-storage-readme.sh"]="google/cloud/storage/README.md"

‎ci/etc/quickstart-config.sh

+5
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ source module ci/etc/integration-tests-config.sh
2323

2424
function quickstart::libraries() {
2525
echo "bigtable"
26+
echo "iam"
2627
echo "spanner"
2728
echo "storage"
2829
echo "pubsub"
@@ -37,6 +38,10 @@ function quickstart::arguments() {
3738
echo "quickstart"
3839
return 0
3940
;;
41+
"iam")
42+
echo "${GOOGLE_CLOUD_PROJECT}"
43+
return 0
44+
;;
4045
"spanner")
4146
echo "${GOOGLE_CLOUD_PROJECT}"
4247
echo "${GOOGLE_CLOUD_CPP_SPANNER_TEST_INSTANCE_ID}"

‎ci/generate-markdown/generate-iam-readme.sh

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
#!/usr/bin/env bash
2+
#
3+
# Copyright 2021 Google LLC
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -eu
18+
19+
BINDIR=$(dirname "$0")
20+
readonly BINDIR
21+
22+
cat <<_EOF_
23+
# Google Cloud IAM C++ Client Library
24+
25+
<!-- This file is automatically generated by ci/generate-markdown/$(basename "$0") -->
26+
27+
_EOF_
28+
29+
cat <<'_EOF_'
30+
This directory contains an idiomatic C++ client library for interacting with
31+
[Cloud IAM](https://cloud.google.com/iam/).
32+
33+
Please note that the Google Cloud C++ client libraries do **not** follow
34+
[Semantic Versioning](https://semver.org/).
35+
36+
## Supported Platforms
37+
38+
* Windows, macOS, Linux
39+
* C++11 (and higher) compilers (we test with GCC \>= 5.4, Clang >= 3.8, and MSVC \>= 2019)
40+
* Environments with or without exceptions
41+
* Bazel and CMake builds
42+
43+
## Documentation
44+
45+
* Official documentation about the [Cloud IAM][cloud-iam-docs] service
46+
* [Reference doxygen documentation][doxygen-link] for each release of this client library
47+
* Detailed header comments in our [public `.h`][source-link] files
48+
49+
[doxygen-link]: https://googleapis.dev/cpp/google-cloud-iam/latest/
50+
[cloud-iam-docs]: https://cloud.google.com/iam/docs/
51+
[source-link]: https://github.com/googleapis/google-cloud-cpp/tree/main/google/cloud/iam
52+
53+
## Quickstart
54+
55+
The [quickstart/](quickstart/README.md) directory contains a minimal environment
56+
to get started using this client library in a larger project. The following
57+
"Hello World" program is used in this quickstart, and should give you a taste of
58+
this library.
59+
60+
```cc
61+
_EOF_
62+
63+
# Dumps the contents of quickstart.cc starting at the first #include, so we
64+
# skip the license header comment.
65+
sed -n -e '/END iam_quickstart/,$d' -e '/^#/,$p' "${BINDIR}/../../google/cloud/iam/quickstart/quickstart.cc"
66+
67+
cat <<'_EOF_'
68+
```
69+
70+
* Packaging maintainers or developers that prefer to install the library in a
71+
fixed directory (such as `/usr/local` or `/opt`) should consult the
72+
[packaging guide](/doc/packaging.md).
73+
* Developers wanting to use the libraries as part of a larger CMake or Bazel
74+
project should consult the [quickstart guides](#quickstart) for the library
75+
or libraries they want to use.
76+
* Developers wanting to compile the library just to run some of the examples or
77+
tests should read the current document.
78+
* Contributors and developers to `google-cloud-cpp` should consult the guide to
79+
[setup a development workstation][howto-setup-dev-workstation].
80+
81+
[howto-setup-dev-workstation]: /doc/contributor/howto-guide-setup-development-workstation.md
82+
83+
## Installation
84+
85+
Please consult the [packaging guide](../../../doc/packaging.md) for detailed
86+
instructions to install the Google Cloud C++ client libraries.
87+
If your project uses [CMake](https://cmake.org) or [Bazel](https://bazel.build)
88+
check the [quickstart](quickstart/README.md) example for instructions to use
89+
this library in your project.
90+
91+
## Contributing changes
92+
93+
See [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) for details on how to
94+
contribute to this project, including how to build and test your changes
95+
as well as how to properly format your code.
96+
97+
## Licensing
98+
99+
Apache 2.0; see [`LICENSE`](../../../LICENSE) for details.
100+
101+
_EOF_

‎ci/kokoro/windows/build-quickstart-bazel.ps1

+1
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,7 @@ $quickstart_args=@{
111111
"bigtable"=@("${env:GOOGLE_CLOUD_PROJECT}", "${env:GOOGLE_CLOUD_CPP_BIGTABLE_TEST_INSTANCE_ID}", "quickstart")
112112
"spanner"=@("${env:GOOGLE_CLOUD_PROJECT}", "${env:GOOGLE_CLOUD_CPP_SPANNER_TEST_INSTANCE_ID}", "quickstart-db")
113113
"pubsub"=@("${env:GOOGLE_CLOUD_PROJECT}", "${env:GOOGLE_CLOUD_CPP_PUBSUB_TEST_QUICKSTART_TOPIC}")
114+
"iam"=@("${env:GOOGLE_CLOUD_PROJECT}")
114115
}
115116

116117
ForEach($library in ("bigtable", "storage", "spanner", "pubsub")) {

‎ci/kokoro/windows/build-quickstart-cmake.ps1

+1
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ $quickstart_args=@{
7070
"bigtable"=@("${env:GOOGLE_CLOUD_PROJECT}", "${env:GOOGLE_CLOUD_CPP_BIGTABLE_TEST_INSTANCE_ID}", "quickstart")
7171
"spanner"=@("${env:GOOGLE_CLOUD_PROJECT}", "${env:GOOGLE_CLOUD_CPP_SPANNER_TEST_INSTANCE_ID}", "quickstart-db")
7272
"pubsub"=@("${env:GOOGLE_CLOUD_PROJECT}", "${env:GOOGLE_CLOUD_CPP_PUBSUB_TEST_QUICKSTART_TOPIC}")
73+
"iam"=@("${env:GOOGLE_CLOUD_PROJECT}")
7374
}
7475

7576
ForEach($library in ("bigtable", "storage", "spanner", "pubsub")) {

‎google/cloud/iam/BUILD

+2
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,13 @@ cc_library(
2323
srcs = google_cloud_cpp_iam_srcs,
2424
hdrs = google_cloud_cpp_iam_hdrs,
2525
visibility = ["//:__pkg__"],
26+
# Do not sort: grpc++ must come last
2627
deps = [
2728
"//google/cloud:google_cloud_cpp_common",
2829
"//google/cloud:google_cloud_cpp_grpc_utils",
2930
"@com_google_googleapis//google/iam/admin/v1:admin_cc_grpc",
3031
"@com_google_googleapis//google/iam/credentials/v1:credentials_cc_grpc",
32+
"@com_github_grpc_grpc//:grpc++",
3133
],
3234
)
3335

‎google/cloud/iam/README.md

+95-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,100 @@
11
# Google Cloud IAM C++ Client Library
22

3-
:construction:
3+
<!-- This file is automatically generated by ci/generate-markdown/generate-iam-readme.sh -->
44

55
This directory contains an idiomatic C++ client library for interacting with
6-
[Cloud Identity and Access Management (IAM)](https://cloud.google.com/iam/),
7-
a service for fine-grained access control and visibility for centrally
8-
managing cloud resources.
6+
[Cloud IAM](https://cloud.google.com/iam/).
7+
8+
Please note that the Google Cloud C++ client libraries do **not** follow
9+
[Semantic Versioning](https://semver.org/).
10+
11+
## Supported Platforms
12+
13+
* Windows, macOS, Linux
14+
* C++11 (and higher) compilers (we test with GCC \>= 5.4, Clang >= 3.8, and MSVC \>= 2019)
15+
* Environments with or without exceptions
16+
* Bazel and CMake builds
17+
18+
## Documentation
19+
20+
* Official documentation about the [Cloud IAM][cloud-iam-docs] service
21+
* [Reference doxygen documentation][doxygen-link] for each release of this client library
22+
* Detailed header comments in our [public `.h`][source-link] files
23+
24+
[doxygen-link]: https://googleapis.dev/cpp/google-cloud-iam/latest/
25+
[cloud-iam-docs]: https://cloud.google.com/iam/docs/
26+
[source-link]: https://github.com/googleapis/google-cloud-cpp/tree/main/google/cloud/iam
27+
28+
## Quickstart
29+
30+
The [quickstart/](quickstart/README.md) directory contains a minimal environment
31+
to get started using this client library in a larger project. The following
32+
"Hello World" program is used in this quickstart, and should give you a taste of
33+
this library.
34+
35+
```cc
36+
#include "google/cloud/iam/iam_client.h"
37+
#include <iostream>
38+
#include <stdexcept>
39+
40+
int main(int argc, char* argv[]) try {
41+
if (argc != 2) {
42+
std::cerr << "Usage: " << argv[0] << " <project-id>\n";
43+
return 1;
44+
}
45+
46+
std::string const project_id = argv[1];
47+
48+
// Create a namespace alias to make the code easier to read.
49+
namespace iam = google::cloud::iam;
50+
iam::IAMClient client(iam::MakeIAMConnection());
51+
std::cout << "Service Accounts for project: " << project_id << "\n";
52+
int count = 0;
53+
for (auto const& service_account :
54+
client.ListServiceAccounts("projects/" + project_id)) {
55+
if (!service_account) {
56+
throw std::runtime_error(service_account.status().message());
57+
}
58+
std::cout << service_account->name() << "\n";
59+
++count;
60+
}
61+
62+
if (count == 0) std::cout << "No Service Accounts found.\n";
63+
return 0;
64+
} catch (std::exception const& ex) {
65+
std::cerr << "Standard exception raised: " << ex.what() << "\n";
66+
return 1;
67+
}
68+
```
69+
70+
* Packaging maintainers or developers that prefer to install the library in a
71+
fixed directory (such as `/usr/local` or `/opt`) should consult the
72+
[packaging guide](/doc/packaging.md).
73+
* Developers wanting to use the libraries as part of a larger CMake or Bazel
74+
project should consult the [quickstart guides](#quickstart) for the library
75+
or libraries they want to use.
76+
* Developers wanting to compile the library just to run some of the examples or
77+
tests should read the current document.
78+
* Contributors and developers to `google-cloud-cpp` should consult the guide to
79+
[setup a development workstation][howto-setup-dev-workstation].
80+
81+
[howto-setup-dev-workstation]: /doc/contributor/howto-guide-setup-development-workstation.md
82+
83+
## Installation
84+
85+
Please consult the [packaging guide](../../../doc/packaging.md) for detailed
86+
instructions to install the Google Cloud C++ client libraries.
87+
If your project uses [CMake](https://cmake.org) or [Bazel](https://bazel.build)
88+
check the [quickstart](quickstart/README.md) example for instructions to use
89+
this library in your project.
90+
91+
## Contributing changes
92+
93+
See [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) for details on how to
94+
contribute to this project, including how to build and test your changes
95+
as well as how to properly format your code.
96+
97+
## Licensing
98+
99+
Apache 2.0; see [`LICENSE`](../../../LICENSE) for details.
9100
10-
This library is **experimental**. Its APIS are subject to change without notice.

‎google/cloud/iam/quickstart/BUILD

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Copyright 2021 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
package(default_visibility = ["//visibility:public"])
16+
17+
licenses(["notice"]) # Apache 2.0
18+
19+
cc_binary(
20+
name = "quickstart",
21+
srcs = [
22+
"quickstart.cc",
23+
],
24+
deps = [
25+
"@com_github_googleapis_google_cloud_cpp//:experimental-iam",
26+
],
27+
)

‎google/cloud/iam/quickstart/CMakeLists.txt

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Copyright 2021 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
4+
# use this file except in compliance with the License. You may obtain a copy of
5+
# the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11+
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12+
# License for the specific language governing permissions and limitations under
13+
# the License.
14+
15+
# A minimal CMakeList.txt showing how to use the Cloud Bigtable C++ client
16+
# library in CMake-based projects.
17+
18+
cmake_minimum_required(VERSION 3.5)
19+
project(google-cloud-cpp-iam-quickstart CXX C)
20+
21+
set(CMAKE_CXX_STANDARD 11)
22+
set(CMAKE_CXX_STANDARD_REQUIRED ON)
23+
24+
find_package(google_cloud_cpp_iam REQUIRED)
25+
26+
# MSVC requires some additional code to select the correct runtime library
27+
if (VCPKG_TARGET_TRIPLET MATCHES "-static$")
28+
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
29+
else ()
30+
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
31+
endif ()
32+
33+
# Once the iam_client package is found, define new targets.
34+
add_executable(quickstart quickstart.cc)
35+
target_link_libraries(quickstart google-cloud-cpp::experimental-iam)

‎google/cloud/iam/quickstart/Makefile

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Copyright 2021 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
# This is a minimal Makefile to show how to use the Cloud Pub/Sub C++ client for
16+
# developers that use make(1) as their build system.
17+
18+
# The CXX, CXXFLAGS and CXXLD variables are hard-coded. These values work for
19+
# our tests, but applications would typically make them configurable parameters.
20+
CXX=g++
21+
CXXFLAGS=-std=c++11
22+
CXXLD=$(CXX)
23+
BIN=.
24+
25+
all: $(BIN)/quickstart
26+
27+
# Configuration variables to compile and link against the Cloud Spanner C++
28+
# client library.
29+
IAM_DEPS := google_cloud_cpp_iam
30+
IAM_CXXFLAGS := $(shell pkg-config $(IAM_DEPS) --cflags)
31+
IAM_CXXLDFLAGS := $(shell pkg-config $(IAM_DEPS) --libs-only-L)
32+
IAM_LIBS := $(shell pkg-config $(IAM_DEPS) --libs-only-l)
33+
34+
# A target using the Cloud Pubsub C++ client library.
35+
$(BIN)/quickstart: quickstart.cc
36+
$(CXXLD) $(CXXFLAGS) $(IAM_CXXFLAGS) $(IAM_CXXLDFLAGS) -o $@ $^ $(IAM_LIBS)

0 commit comments

Comments
 (0)