doc: document how to run samples using Bazel

README.md

@@ -31,8 +31,8 @@ in the [release notes](README.md#release-notes) below.
 [![CI status docker/check-api][docker/check-api-shield]][docker/check-api-link]
 [![CI status docker/clang-3.8][docker/clang-3.8-shield]][docker/clang-3.8-link]
 [![CI status docker/clang-tidy][docker/clang-tidy-shield]][docker/clang-tidy-link]
-[![CI status docker/cmake-super][docker/cmake-super-shield]][docker/cmake-super-link]
 [![CI status docker/cmake][docker/cmake-shield]][docker/cmake-link]
+[![CI status docker/cmake-super][docker/cmake-super-shield]][docker/cmake-super-link]
 [![CI status docker/coverage][docker/coverage-shield]][docker/coverage-link]
 [![CI status docker/cxx17][docker/cxx17-shield]][docker/cxx17-link]
 [![CI status docker/gcc-4.8][docker/gcc-4.8-shield]][docker/gcc-4.8-link]
@@ -131,13 +131,77 @@ in the [release notes](README.md#release-notes) below.
 
 ## Documentation
 
-The [reference documentation][doxygen-link] for this client library is available online.
-Please consult the [Cloud Spanner website][cloud-spanner-docs] for
-general documentation on Cloud Spanner features, APIs, other client
-libraries, etc.
+The [reference documentation][doxygen-link] for this client library is available
+online. Please consult the [Cloud Spanner website][cloud-spanner-docs] for
+general documentation on Cloud Spanner features, APIs, other client libraries,
+etc.
 
 [cloud-spanner-docs]: https://cloud.google.com/spanner/docs/
 
+## Running the Examples
+
+Install Bazel using [these instructions][bazel-install]. If needed, install the
+C++ toolchain for your platform too. Then compile the library examples using:
+
+```console
+bazel build //google/cloud/spanner/samples:samples
+```
+
+On Windows you may need to add some flags to workaround the filename length
+limits.
+
+> You must provide this option in **all** Bazel invocations shown below.
+
+```console
+mkdir C:\b
+bazel --output_user_root=C:\b build //google/cloud/spanner/samples:samples
+```
+
+On Windows and macOS gRPC [requires][grpc-roots-pem-bug] an environment variable
+to find the to manually set the root of trust for SSL. On macOS use:
+
+```console
+wget -q https://raw.githubusercontent.com/grpc/grpc/master/etc/roots.pem
+export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="$PWD/roots.pem"
+```
+
+While on Windows use:
+
+```console
+@powershell -NoProfile -ExecutionPolicy unrestricted -Command ^
+    (new-object System.Net.WebClient).Downloadfile( ^
+        'https://raw.githubusercontent.com/grpc/grpc/master/etc/roots.pem', ^
+        'roots.pem')
+set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\roots.pem
+```
+
+You will need a Google Cloud Project with billing and the spanner API enabled.
+Please consult the Spanner [quickstart guide][spanner-quickstart-link] for
+detailed instructions on how to enable billing for your project.
+Once your project is properly configured you can run the examples using
+`bazel run`, for example:
+
+```console
+bazel run //google/cloud/spanner/samples:samples -- create-instance [PROJECT ID] [SPANNER INSTANCE] "My Test Instance"
+bazel run //google/cloud/spanner/samples:samples -- create-database [PROJECT ID] [SPANNER INSTANCE] [DATABASE ID]
+```
+
+Running the command without options will list the available examples:
+
+```console
+bazel run //google/cloud/spanner/samples:samples --
+```
+
+[bazel-install]: https://docs.bazel.build/versions/master/install.html
+[spanner-quickstart-link]: https://cloud.google.com/spanner/docs/quickstart-console
+[grpc-roots-pem-bug]: https://github.com/grpc/grpc/issues/16571
+
+## Using the Library for Development
+
+If you plan to use this library in your development workflow please read the
+[installation instructions](INSTALL.md). This also cover how to integrate the
+library with CMake and Bazel workflows.
+
 ## Contributing changes
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details on how to contribute to

ci/test-readme/generate-readme.sh

@@ -72,13 +72,77 @@ cat <<'_EOF_'
 
 ## Documentation
 
-The [reference documentation][doxygen-link] for this client library is available online.
-Please consult the [Cloud Spanner website][cloud-spanner-docs] for
-general documentation on Cloud Spanner features, APIs, other client
-libraries, etc.
+The [reference documentation][doxygen-link] for this client library is available
+online. Please consult the [Cloud Spanner website][cloud-spanner-docs] for
+general documentation on Cloud Spanner features, APIs, other client libraries,
+etc.
 
 [cloud-spanner-docs]: https://cloud.google.com/spanner/docs/
 
+## Running the Examples
+
+Install Bazel using [these instructions][bazel-install]. If needed, install the
+C++ toolchain for your platform too. Then compile the library examples using:
+
+```console
+bazel build //google/cloud/spanner/samples:samples
+```
+
+On Windows you may need to add some flags to workaround the filename length
+limits.
+
+> You must provide this option in **all** Bazel invocations shown below.
+
+```console
+mkdir C:\b
+bazel --output_user_root=C:\b build //google/cloud/spanner/samples:samples
+```
+
+On Windows and macOS gRPC [requires][grpc-roots-pem-bug] an environment variable
+to find the to manually set the root of trust for SSL. On macOS use:
+
+```console
+wget -q https://raw.githubusercontent.com/grpc/grpc/master/etc/roots.pem
+export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="$PWD/roots.pem"
+```
+
+While on Windows use:
+
+```console
+@powershell -NoProfile -ExecutionPolicy unrestricted -Command ^
+    (new-object System.Net.WebClient).Downloadfile( ^
+        'https://raw.githubusercontent.com/grpc/grpc/master/etc/roots.pem', ^
+        'roots.pem')
+set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\roots.pem
+```
+
+You will need a Google Cloud Project with billing and the spanner API enabled.
+Please consult the Spanner [quickstart guide][spanner-quickstart-link] for
+detailed instructions on how to enable billing for your project.
+Once your project is properly configured you can run the examples using
+`bazel run`, for example:
+
+```console
+bazel run //google/cloud/spanner/samples:samples -- create-instance [PROJECT ID] [SPANNER INSTANCE] "My Test Instance"
+bazel run //google/cloud/spanner/samples:samples -- create-database [PROJECT ID] [SPANNER INSTANCE] [DATABASE ID]
+```
+
+Running the command without options will list the available examples:
+
+```console
+bazel run //google/cloud/spanner/samples:samples --
+```
+
+[bazel-install]: https://docs.bazel.build/versions/master/install.html
+[spanner-quickstart-link]: https://cloud.google.com/spanner/docs/quickstart-console
+[grpc-roots-pem-bug]: https://github.com/grpc/grpc/issues/16571
+
+## Using the Library for Development
+
+If you plan to use this library in your development workflow please read the
+[installation instructions](INSTALL.md). This also cover how to integrate the
+library with CMake and Bazel workflows.
+
 ## Contributing changes
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details on how to contribute to

google/cloud/spanner/samples/BUILD

@@ -22,7 +22,7 @@ load(":spanner_client_integration_samples.bzl", "spanner_client_integration_samp
 load(":spanner_client_unit_samples.bzl", "spanner_client_unit_samples")
 
 [cc_test(
-    name = "spanner_client_" + test.replace("/", "_").replace(".cc", ""),
+    name = test.replace("/", "_").replace(".cc", ""),
     timeout = "long",
     srcs = [test],
     tags = ["integration-tests"],
@@ -36,7 +36,7 @@ load(":spanner_client_unit_samples.bzl", "spanner_client_unit_samples")
 ) for test in spanner_client_integration_samples]
 
 [cc_test(
-    name = "spanner_client_" + test.replace("/", "_").replace(".cc", ""),
+    name = test.replace("/", "_").replace(".cc", ""),
     srcs = [test],
     deps = [
         "//google/cloud/spanner:spanner_client",