This directory contains small examples showing how to use the GCS C++ client library in your own project. These instructions assume that you have some experience as a C++ developer and that you have a working C++ toolchain (compiler, linker, etc.) installed on your platform.
- Packaging maintainers or developers who prefer to install the library in a
fixed directory (such as
/usr/local
or/opt
) should consult the packaging guide. - Developers who prefer using a package manager such as vcpkg, or Conda, should follow the instructions for their package manager.
- Developers wanting to use the libraries as part of a larger CMake or Bazel project should consult the current document. Note that there are similar documents for each library in their corresponding directories.
- Developers wanting to compile the library just to run some examples or tests should consult the building and installing section of the top-level README file.
- Contributors and developers to
google-cloud-cpp
should consult the guide to set up a development workstation.
To run the quickstart examples you will need a working Google Cloud Platform (GCP) project and an existing bucket. The GCS quickstarts cover the necessary steps in detail. Make a note of the GCP project id and the bucket name as you will need them below.
Like most Google Cloud Platform services, GCS requires that
your application authenticates with the service before accessing any data. If
you are not familiar with GCP authentication please take this opportunity to
review the Authentication Overview. This library
uses the GOOGLE_APPLICATION_CREDENTIALS
environment variable to find the
credentials file. For example:
Shell | Command |
---|---|
Bash/zsh/ksh/etc. | export GOOGLE_APPLICATION_CREDENTIALS=[PATH] |
sh | GOOGLE_APPLICATION_CREDENTIALS=[PATH]; export GOOGLE_APPLICATION_CREDENTIALS |
csh/tsch | setenv GOOGLE_APPLICATION_CREDENTIALS [PATH] |
Windows Powershell | $env:GOOGLE_APPLICATION_CREDENTIALS=[PATH] |
Windows cmd.exe | set GOOGLE_APPLICATION_CREDENTIALS=[PATH] |
Setting this environment variable is the recommended way to configure the authentication preferences, though if the environment variable is not set, the library searches for a credentials file in the same location as the Cloud SDK. For more information about Application Default Credentials, see https://cloud.google.com/docs/authentication/production
-
Install Bazel using the instructions from the
bazel.build
website. -
Compile this example using Bazel:
cd $HOME/google-cloud-cpp/google/cloud/storage/quickstart bazel build ...
Note that Bazel automatically downloads and compiles all dependencies of the project. As it is often the case with C++ libraries, compiling these dependencies may take several minutes.
-
Run the example, change the placeholder to appropriate values:
bazel run :quickstart -- [BUCKET NAME]
Please use the plain bucket name. Do not include any
gs://
prefix, and keep in mind the bucket naming restrictions. For example, bucket names cannot include forward slashes (/
) or uppercase letters.
-
Install CMake. The package managers for most Linux distributions include a package for CMake. Likewise, you can install CMake on Windows using a package manager such as chocolatey, and on macOS using homebrew. You can also obtain the software directly from the cmake.org site.
-
Install the dependencies with your favorite tools. As an example, if you use vcpkg:
cd $HOME/vcpkg ./vcpkg install google-cloud-cpp[core,storage]
Note that, as it is often the case with C++ libraries, compiling these dependencies may take several minutes.
-
Configure CMake, if necessary, configure the directory where you installed the dependencies:
cd $HOME/gooogle-cloud-cpp/google/cloud/storage/quickstart cmake -H. -B.build -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake cmake --build .build
-
Run the example, changing the placeholder(s) to appropriate values:
.build/quickstart [BUCKET NAME]
Please use the plain bucket name. Do not include any
gs://
prefix, and keep in mind the bucket naming restrictions. For example, bucket names cannot include forward slashes (/
) or uppercase letters.
The Google Cloud Storage client library includes an experimental plugin to use gRPC as the transport to access GCS. For the most part, only applications with very large workloads (several Tbits/s of upload and/or download bandwidth) benefit from GCS+gRPC. Furthermore, this GCS feature is not generally available in GCP, please talk to your sales rep if you have an interest in using this feature.
To enable the GCS+gRPC plugin you need to (a) link your application
with an additional library, and (b) use a different function to initialize the
google::cloud::storage::Client
object. Both changes are illustrated in the
quickstart_grpc
program included in this directory.
The GCS+gRPC plugin is disabled in CMake builds, this minimized the impact in
build times and dependency management for customers not wanting to use the
feature. To enable the feature add -DGOOGLE_CLOUD_CPP_STORAGE_ENABLE_GRPC=ON
to your CMake configuration step. Using the previous example:
cd $HOME/gooogle-cloud-cpp/google/cloud/storage/quickstart
cmake -H. -B.build -DGOOGLE_CLOUD_CPP_STORAGE_ENABLE_GRPC=ON \
-DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build .build --target quickstart_grpc
Then run the additional program:
.build/quickstart_grpc [BUCKET NAME]
Run the example, change the placeholder to appropriate values:
bazel run :quickstart_grpc -- [BUCKET NAME]
gRPC requires an environment variable to configure the trust store for SSL certificates, you can download and configure this using:
curl -Lo roots.pem https://pki.google.com/roots.pem
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="$PWD/roots.pem"
To workaround a bug in Bazel, gRPC requires this flag on
macOS builds, you can add the option manually or include it in your .bazelrc
file:
bazel build --copt=-DGRPC_BAZEL_BUILD ...
Bazel tends to create very long file names and paths. You may need to use a
short directory to store the build output, such as c:\b
, and instruct Bazel
to use it via:
bazel --output_user_root=c:\b build ...
gRPC requires an environment variable to configure the trust store for SSL certificates, you can download and configure this using:
@powershell -NoProfile -ExecutionPolicy unrestricted -Command ^
(new-object System.Net.WebClient).Downloadfile( ^
'https://pki.google.com/roots.pem', 'roots.pem')
set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\roots.pem