Google Cloud Platform C++ Client Libraries

This repository contains idiomatic C++ client libraries for the following Google Cloud Platform services.

See each library's README.md file for more information about:

Where to find the documentation for the library and the service.
How to get started using the library.
How to incorporate the library into your build system.
The library's support status if not Generally Available (GA); unless noted in a library's README.md, these libraries are all GA and supported by Google.

Install

On most platforms, with all dependencies installed, the following commands will compile and install all the libraries:

cmake -H. -Bcmake-out
cmake --build cmake-out
sudo cmake --build cmake-out --target install

You can find detailed instructions on how to install and/or compile all the dependencies for several platforms in the packaging guide.

For application developers who prefer to build from source, the quickstart guides for each library (see above) include instructions on how to incorporate the library into their CMake-based or Bazel-based builds.

Quickstart

Each library (linked above) contains a directory named quickstart/ that's intended to help you get up and running in a matter of minutes. This quickstart/ directory contains a minimal "Hello World" program demonstrating how to use the library, along with minimal build files for common build systems, such as CMake and Bazel.

As an example, the following code snippet, taken from Google Cloud Storage, should give you a taste of what it's like to use one of these C++ libraries.

#include "google/cloud/storage/client.h"
#include <iostream>

int main(int argc, char* argv[]) {
  if (argc != 2) {
    std::cerr << "Missing bucket name.\n";
    std::cerr << "Usage: quickstart <bucket-name>\n";
    return 1;
  }
  std::string const bucket_name = argv[1];

  // Create aliases to make the code easier to read.
  namespace gcs = google::cloud::storage;

  // Create a client to communicate with Google Cloud Storage. This client
  // uses the default configuration for authentication and project id.
  google::cloud::StatusOr<gcs::Client> client =
      gcs::Client::CreateDefaultClient();
  if (!client) {
    std::cerr << "Failed to create Storage Client, status=" << client.status()
              << "\n";
    return 1;
  }

  auto writer = client->WriteObject(bucket_name, "quickstart.txt");
  writer << "Hello World!";
  writer.Close();
  if (writer.metadata()) {
    std::cout << "Successfully created object: " << *writer.metadata() << "\n";
  } else {
    std::cerr << "Error creating object: " << writer.metadata().status()
              << "\n";
    return 1;
  }

  auto reader = client->ReadObject(bucket_name, "quickstart.txt");
  if (!reader) {
    std::cerr << "Error reading object: " << reader.status() << "\n";
    return 1;
  }

  std::string contents{std::istreambuf_iterator<char>{reader}, {}};
  std::cout << contents << "\n";

  return 0;
}

Support

This project supports Windows, macOS, Linux
This project supports C++11 (and higher) compilers (we test with GCC >= 5.4, Clang >= 3.8, and MSVC >= 2019)
This project supports Bazel and CMake builds. See the Quickstart examples
This project uses dependencies described in doc/packaging.md
This project works with or without exceptions enabled
This project cuts monthly releases with detailed release notes

API Breaking Changes

In general, we avoid making backwards incompatible changes to our C++ APIs (see below for the definition of "API"). Sometimes such changes yield benefits to our customers, in the form of better performance, easier-to-understand APIs, and/or more consistent APIs across services. When these benefits warrant it, we will announce these changes prominently in our CHANGELOG.md file and in the affected release's notes. Nevertheless, though we take commercially reasonable efforts to prevent this, it is possible that backwards incompatible changes go undetected and, therefore, undocumented. We apologize if this is the case and welcome feedback or bug reports to rectify the problem.

By "API" we mean the C++ API exposed by public header files in this repo. We are not talking about the gRPC or REST APIs exposed by Google Cloud servers. We are also talking only about API stability -- the ABI is subject to change without notice. You should not assume that binary artifacts (e.g. static libraries, shared objects, dynamically loaded libraries, object files) created with one version of the library are usable with newer/older versions of the library. The ABI may, and does, change on "minor revisions", and even patch releases.

We request that our customers adhere to the following guidelines to avoid accidentally depending on parts of the library we do not consider to be part of the public API and therefore may change (including removal) without notice:

You should only include headers matching the google/cloud/${library}/*.h, google/cloud/${library}/mock/*.h or google/cloud/*.h patterns.
You should NOT directly include headers in any subdirectories, such as google/cloud/${library}/internal.
The files included from our public headers are not part of our public API. Depending on indirect includes may break your build in the future, as we may change a header "foo.h" to stop including "bar.h" if "foo.h" no longer needs the symbols in "bar.h". To avoid having your code broken, you should directly include the public headers that define all the symbols you use (this is sometimes known as include-what-you-use).
Any file or symbol that lives within a directory or namespace containing "internal", "impl", "test", "detail", "benchmark", "sample", or "example", is explicitly not part of our public API.
Any file or symbol with "Impl" or "impl" in its name is not part of our public API.

Previous versions of the library will remain available on the GitHub Releases page.

Note that this document has no bearing on the Google Cloud Platform deprecation policy described at https://cloud.google.com/terms.

Contact us

If you have questions or comments, or want to file bugs or request feature, please do so using GitHub's normal Issues mechanism: Contact Us

Contributing changes

See CONTRIBUTING.md for details on how to contribute to this project, including how to build and test your changes as well as how to properly format your code.

Licensing

Apache 2.0; see LICENSE for details.

Dimon4eg / google-cloud-cpp