@@ -24,164 +24,68 @@ using the C++ client library.
2424 - [Configure a service account][authentication-quickstart],
2525 - or [login with your personal account][gcloud-quickstart]
2626
27- ### Downloading and Compiling the C++ Client Library
27+ ### Setting up your repo
2828
29- The source code for the Cloud Spanner C++ Client Library can be found on
30- [GitHub][github-link]. Download or clone this repository as usual:
29+ In order to use the Cloud Spanner C++ client library from your own code, you'll
30+ need to teach your build system how to fetch and compile the Cloud C++ client
31+ library. The Cloud Spanner C++ client library natively supports the
32+ [Bazel](https://bazel.build/) and [CMake](https://cmake.org/) build systems.
33+ We've created a minimal, "Hello world", [quickstart repo][quickstart-link] that
34+ includes detailed instructions on how to compile the library for use in your
35+ application. You can fetch the source from [GitHub][github-link] as normal:
3136
32- ```
37+ @code{.sh}
3338git clone https://github.com/googleapis/google-cloud-cpp-spanner.git
34- ```
35-
36- The top-level [README][github-readme] file in this repository includes detailed
37- instructions on how to compile the library. The examples used in this guide
38- should be automatically compiled when you follow said instructions.
39-
40- ### Configuring authentication for the C++ Client Library
41-
42- Like all Google Cloud Platform (GCP) services, Cloud Spanner requires that your
43- application authenticates with the service before accessing any data.
44- If you are not familiar with GCP authentication please take this opportunity to
45- review the [Authentication Overview][authentication-quickstart]. This library
46- uses the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to
47- find the credentials file. For example:
48-
49- | Shell | Command |
50- | :----------------- | ---------------------------------------------- |
51- | Bash/zsh/ksh/etc. | `export GOOGLE_APPLICATION_CREDENTIALS=[PATH]` |
52- | sh | `GOOGLE_APPLICATION_CREDENTIALS=[PATH];` `export GOOGLE_APPLICATION_CREDENTIALS` |
53- | csh/tsch | `setenv GOOGLE_APPLICATION_CREDENTIALS [PATH]` |
54- | Windows Powershell | `$env:GOOGLE_APPLICATION_CREDENTIALS=[PATH]` |
55- | Windows cmd.exe | `set GOOGLE_APPLICATION_CREDENTIALS=[PATH]` |
56-
57- Setting this environment variable is the recommended way to configure the
58- authentication preferences, though if the environment variable is not set, the
59- library searches for a credentials file in the same location as the [Cloud
60- SDK](https://cloud.google.com/sdk/).
61-
62- ### Create a database
63-
64- This is a short example that creates a Cloud Spanner database and two tables.
65- This example assumes you have configured the authentication using
66- `GOOGLE_APPLICATION_CREDENTIALS` and has created a Cloud Spanner instance:
67-
68- @snippet samples.cc quickstart
69-
70- This quickstart creates a database with two tables: `Singers` and `Albums`. You
71- must provide the project id and instance in the command-line when you run the
72- quickstart program. Assuming you followed the build instructions referenced
73- above this would be:
74-
75- @code
76- ./cmake-out/google/cloud/spanner/samples/samples [PROJECT_ID] [INSTANCE_ID]
77- @endcode
78-
79- ### Using the library in your own projects
80-
81- Our continuous integration builds compile and test the code using both
82- [Bazel](https://bazel.build/), and [CMake](https://cmake.org/). Integrating the
83- Cloud Spanner C++ client library should work with either.
84-
85- #### Integrating with CMake
86-
87- Compile and install the library using the usual `CMake` commands. Once the
88- library is installed, you can use it in your `CMakeLists.txt` file like any
89- other package:
90-
91- ```
92- cmake_minimum_required(VERSION 3.5)
93- find_package(spanner_client REQUIRED)
94-
95- add_executable(my_program my_program.cc)
96- target_link_libraries(my_program spanner_client)
97- ```
98-
99- #### Integrating with Bazel
100-
101- As we do not currently have releases of `google-cloud-cpp-spanner` you need to
102- select the SHA-1 of the
103- [commit](https://github.com/googleapis/google-cloud-cpp-spanner/commits/master)
104- you want to use.
105-
106- In your [WORKSPACE][workspace-definition-link] file add a dependency to download
107- and install the library, for example:
108-
109- @code {.py}
110- # Add the necessary Starlark functions to fetch google-cloud-cpp-spanner.
111- load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
112-
113- # Change the version and SHA256 hash as needed.
114- http_archive(
115- name = "com_github_googleapis_google_cloud_cpp_spanner",
116- sha256 = "a833d3c1a6d127132e961350829babac521b62b4c837b88d7c219b400e98fed1",
117- strip_prefix = "google-cloud-cpp-spanner-0.8.0",
118- url = "https://github.com/googleapis/google-cloud-cpp-spanner/archive/v0.8.0.tar.gz",
119- )
39+ cd google-cloud-cpp-spanner/quickstart
12040@endcode
12141
122- Then load the dependencies of the library:
123-
124- ```{.py}
125- load("@com_github_googleapis_google_cloud_cpp_spanner//bazel:google_cloud_cpp_spanner_deps.bzl", "google_cloud_cpp_spanner_deps")
42+ @par Example: Hello World
12643
127- google_cloud_cpp_spanner_deps()
44+ The following shows the code that you'll run in the `quickstart/` directory,
45+ which should give you a taste of the Cloud Spanner C++ client library API.
12846
129- # Configure @com_google_googleapis to only compile C++ and gRPC:
130- load("@com_google_googleapis//:repository_rules.bzl", "switched_rules_by_language")
47+ @include quickstart.cc
13148
132- switched_rules_by_language(
133- name = "com_google_googleapis_imports",
134- cc = True,
135- grpc = True,
136- )
49+ ## API Notes
13750
138- # You have to manually call the corresponding function for google-cloud-cpp and
139- # gRPC: https://github.com/bazelbuild/bazel/issues/1550
140- load("@com_github_googleapis_google_cloud_cpp_common//bazel:google_cloud_cpp_deps.bzl", "google_cloud_cpp_deps")
51+ The following are general notes about using the library.
14152
142- google_cloud_cpp_deps()
53+ ### Environment Variables
14354
144- load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")
55+ There are several environment variables that can be set to configure certain
56+ behaviors in the library.
14557
146- grpc_deps()
58+ - `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` turns on logging in the library, basically
59+ the library always "logs" but the logging infrastructure has no backend to
60+ actually print anything until the application sets a backend or they set this
61+ environment variable.
14762
148- load("@com_github_grpc_grpc//bazel:grpc_extra_deps.bzl", "grpc_extra_deps")
63+ - `GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc` turns on tracing for most gRPC
64+ calls, the library injects an additional Stub decorator that prints each gRPC
65+ request and response.
14966
150- grpc_extra_deps()
151- ```
67+ - `GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc-streams` turns on tracing for streaming
68+ gRPC calls, such as `Client::Read()`, `Client::ExecutEQuery()`, and
69+ `Client::ProfileQuery()`. This can produce a lot of output, so use with
70+ caution!
15271
153- You can now use the library as a dependency in your BUILD files, for example:
72+ - `GOOGLE_CLOUD_CPP_SPANNER_DEFAULT_ENDPOINT=...` changes the default endpoint
73+ (spanner.googleapis.com) for the library.
15474
155- ```{.py}
156- cc_binary(
157- name = "my_program",
158- srcs = [
159- "my_program.cc",
160- ],
161- deps = [
162- "@com_github_googleapis_google_cloud_cpp_spanner//google/cloud/spanner:spanner_client",
163- ],
164- )
165- ```
75+ - `GOOGLE_CLOUD_PROJECT=...` is used in examples and integration tests to
76+ configure the GCP project.
16677
167- #### Integrating with Make
78+ - `GOOGLE_CLOUD_CPP_SPANNER_INSTANCE=...` is used in examples and integration
79+ tests to, well, configure the spanner instance.
16880
169- Installing the client library with CMake also creates `pkg-config` support files
170- for application developers that prefer to use `Make` as their build system. Once
171- the library is installed, you can use it in your `Makefile` like any other
172- `pkg-config` module:
81+ - `GOOGLE_CLOUD_CPP_SPANNER_IAM_TEST_SA=...` is used in examples and
82+ integration tests to set the service account for testing IAM operations.
17383
174- ```
175- # Configuration variables to compile and link against the Cloud Spanner C++
176- # client library.
177- SPANNER_CXXFLAGS := $(shell pkg-config spanner_client --cflags)
178- SPANNER_CXXLDFLAGS := $(shell pkg-config spanner_client --libs-only-L)
179- SPANNER_LIBS := $(shell pkg-config spanner_client --libs-only-l)
84+ - `SPANNER_EMULATOR_HOST=host:port` tells the library to connect to the
85+ specified emulator rather than the default endpoint.
18086
181- # A target using the Cloud Spanner C++ client library.
182- my_program: my_program.cc
183- $(CXX) $(CXXFLAGS) $(SPANNER_CXXFLAGS) $(SPANNER_CXXLDFLAGS) -o $@ $^ $(SPANNER_LIBS)
184- ```
87+ - `SPANNER_OPTIMIZER_VERSION=n` sets the default query optimizer version to use
88+ in `Client::ExecuteQuery()` calls.
18589
18690### Error Handling
18791
@@ -193,7 +97,7 @@ long running operations return `future<StatusOr<T>>`, and the methods on
19397`Client` that read from a database return a `RowStream`, which iterates a
19498stream of `StatusOr<T>`.
19599
196- #### Error Handling Example
100+ @par Example
197101
198102Applications should check if the `StatusOr<T>` contains a value before using
199103it, much like how you might check that a pointer is not null before
@@ -243,21 +147,13 @@ period between retries.
243147
244148* @ref spanner-mocking
245149
246- [sql-overview-link]: https://cloud.google.com/spanner/docs/query-syntax
247-
248- [spanner-quickstart]: https://cloud.google.com/spanner/docs/tutorials 'Spanner Tutorials'
249150[resource-link]: https://console.cloud.google.com/cloud-resource-manager 'Console Resource Manager'
250151[billing-link]: https://cloud.google.com/billing/docs/how-to/modify-project 'How to: Modify Project'
251152[concepts-link]: https://cloud.google.com/storage/docs/concepts 'GCS Concepts'
252153[authentication-quickstart]: https://cloud.google.com/docs/authentication/getting-started 'Authentication Getting Started'
253154[gcloud-quickstart]: https://cloud.google.com/sdk/docs/quickstarts
254-
255155[github-link]: https://github.com/googleapis/google-cloud-cpp-spanner 'GitHub Repository'
256- [github-readme]: https://github.com/googleapis/google-cloud-cpp-spanner/blob/master/README%2Emd
257-
258- [workspace-definition-link]: https://docs.bazel.build/versions/master/build-ref.html#packages_targets
259- [status-or-header]: https://github.com/googleapis/google-cloud-cpp/blob/master/google/cloud/status_or.h
260-
261-
156+ [quickstart-link]: https://github.com/googleapis/google-cloud-cpp-spanner/blob/master/quickstart
157+ [status-or-header]: https://github.com/googleapis/google-cloud-cpp-common/blob/master/google/cloud/status_or.h
262158
263159*/
0 commit comments