• Stars
    star
    538
  • Rank 82,513 (Top 2 %)
  • Language
    C++
  • License
    Apache License 2.0
  • Created almost 7 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

C++ Client Libraries for Google Cloud Services

Google Cloud Platform C++ Client Libraries

GCB CI status Kokoro CI status Kokoro CI status Codecov Coverage status
GCB CI status Kokoro CI status Kokoro CI status

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

Please check the CHANGELOG for important announcements and upcoming changes.

Quickstart

Each library (see below) 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 sense 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.
  auto client = gcs::Client();

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

  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;
}

GA Libraries

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.
Expand to see the full list of GA libraries

Building and Installing

This is a quickstart guide for developers wanting to compile the libraries and run the examples included with the libraries.

  • 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 quickstart guides for the library or libraries they want to use.
  • Developers wanting to compile the library just to run some examples or tests should read the current document.
  • Contributors and developers to google-cloud-cpp should consult the guide to set up a development workstation.

Building with Bazel

This library requires Bazel >= 5.4. From the top-level directory, run the usual commands.

bazel build //...

Building with CMake

This library requires CMake >= 3.10. If you are planning to install the libraries please consult the packaging guide, these instructions will NOT produce artifacts that you can put in /usr/local, or share with your colleagues.

From the top-level directory of google-cloud-cpp run these commands:

git -C $HOME clone https://github.com/microsoft/vcpkg.git
env VCPKG_ROOT=$HOME/vcpkg $HOME/vcpkg/bootstrap-vcpkg.sh
cmake -S . -B cmake-out/ -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build cmake-out -- -j $(nproc)

The binary artifacts, such as examples, will be placed in cmake-out/.

Support

  • This project follows Google's Foundational C++ Support Policy, which is summarized in the Foundational C++ Support Matrix.
    • Language Version (>= C++14).
    • Operating Systems: Windows, macOS, and Linux.
    • Build Systems: Bazel (>= 5.4), CMake (>= 3.10).
    • Compilers: GCC (>= 7.3), Clang (>= 6.0), MSVC (>= 2019), Apple Clang (>= 12).
  • 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.

Public API and API Breaking Changes

This project follows Google's OSS Library Breaking Change Policy.

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:

Previous versions of the library will remain available on the GitHub Releases page. In many cases, you will be able to use an older version even if a newer version has changes that you are unable (or do not have time) to adopt.

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

C++ Symbols and Files

  • 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.
  • Any symbol with experimental in its name is not part of the public API.
  • You should avoid naming our inline namespaces (even avoid spelling the preprocessor names like GOOGLE_CLOUD_CPP_NS) and instead rely on them being a transparent versioning mechanism that you almost certainly don't care about. If you do spell out specific inline namespace names, your code will be tightly coupled with that specific version and will likely break when upgrading to a new version of our library.

Beyond the C++ API

Applications developers interact with a C++ library through more than just the C++ symbols and headers. They also need to reference the name of the library in their build scripts. Depending on the build system they use this may be a CMake target, a Bazel rule, a pkg-config module, or just the name of some object in the file system.

As with the C++ API, we try to avoid breaking changes to these interface points. Sometimes such changes yield benefits to our customers, in the form of bug fixes, increased consistency across services, or easier to understand names. 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.

Experimental Libraries

From time to time we add libraries to google-cloud-cpp to validate new designs, expose experimental (or otherwise not generally available) GCP features, or simply because a library is not yet complete. Such libraries will have experimental in their CMake target and Bazel rule names. The README file for these libraries will also document that they are experimental. Such libraries are subject to change, including removal, without notice. This includes, but it is not limited to, all their symbols, pre-processor macros, files, targets, rules, and installed artifacts.

Bazel rules

Only the rules exported at the top-level directory are intended for customer use, e.g.,//:spanner. Experimental rules have experimental in their name, e.g. //:experimental-logging. As previously stated, experimental rules are subject to change or removal without notice.

CMake targets and packages

Only CMake packages starting with the google_cloud_cpp_ prefix are intended for customer use. Only targets starting with google-cloud-cpp::, are intended for customer use. Experimental targets have experimental in their name (e.g. google-cloud-cpp::experimental-logging). As previously stated, experimental targets are subject to change or removal without notice.

pkg-config modules

Only modules starting with google_cloud_cpp_ are intended for customer use.

Unsupported use cases

We try to provide stable names for the previously described mechanisms:

  • Bazel rules,
  • CMake targets loaded via find_package(),
  • pkg-config modules

It is certainly possible to use the library using other approaches. While these may work, we may accidentally break these from time to time. Examples of such, and the recommended alternatives, include:

  • CMake's FetchContent and/or git submodules: in these approaches the google-cloud-cpp library becomes a subdirectory of a larger CMake build We do not test google-cloud-cpp in these configurations, and we find them brittle as all CMake targets become visible to the larger project. This is both prone to conflicts, and makes it impossible to enforce that some targets are only for testing or are implementation details. Applications may want to consider source package managers, such as vcpkg, or CMake super builds via ExternalProject_Add() as alternatives.

  • Using library names directly: applications should not use the library names, e.g., by using -lgoogle_cloud_cpp_bigtable in build scripts. We may need to split or merge libraries over time, making such names unstable. Applications should use CMake targets, e.g., google-cloud-cpp::bigtable, or pkg-config modules, e.g., $(pkg-config google_cloud_cpp_bigtable --libs) instead.

Environment Variables

Environment variables referenced in our documentation come with the same guarantees as our public APIs. That is, we are committed to supporting their behavior unless the behavior affects experimental components, or the environment variable itself is experimental.

Telemetry Data

The library can be configured to produce telemetry data, such as logs or traces. We make no guarantees around the contents of such data. For example, we may change the format of our logs, or the names of our spans without notice.

The APIs to programmatically enable logging and tracing have the same guarantees as any other public APIs in our libraries.

Documentation and Comments

The documentation (and its links) is intended for human consumption and not third party websites, or automation (such as scripts scraping the contents). The contents and links of our documentation may change without notice.

Other Interface Points

We think this covers all interface points, if we missed something please file a GitHub issue.

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.

More Repositories

1

google-api-nodejs-client

Google's officially supported Node.js client library for accessing Google APIs. Support for authorization and authentication with OAuth 2.0, API Keys and JWT (Service Tokens) is included.
TypeScript
11,377
star
2

google-api-php-client

A PHP client library for accessing Google APIs
PHP
8,706
star
3

google-api-python-client

๐Ÿ The official Python client library for Google's discovery based APIs.
Python
6,858
star
4

googleapis

Public interface definitions of Google APIs.
Starlark
6,797
star
5

release-please

generate release PRs based on the conventionalcommits.org spec
TypeScript
4,740
star
6

google-cloud-python

Google Cloud Client Library for Python
Python
4,324
star
7

google-api-go-client

Auto-generated Google APIs for Go.
Go
3,572
star
8

google-cloud-go

Google Cloud Client Libraries for Go.
Go
3,361
star
9

google-api-ruby-client

REST client for Google APIs
Ruby
2,679
star
10

google-cloud-node

Google Cloud Client Library for Node.js
TypeScript
2,654
star
11

google-cloud-java

Google Cloud Client Library for Java
Java
1,773
star
12

google-auth-library-nodejs

๐Ÿ”‘ Google Auth Library for Node.js
TypeScript
1,549
star
13

google-http-java-client

Google HTTP Client Library for Java
Java
1,342
star
14

google-api-dotnet-client

Google APIs Client Library for .NET
C#
1,340
star
15

google-api-java-client

Google APIs Client Library for Java
Java
1,336
star
16

google-auth-library-php

Google Auth Library for PHP
PHP
1,323
star
17

google-cloud-ruby

Google Cloud Client Library for Ruby
Ruby
1,293
star
18

google-api-php-client-services

PHP
1,179
star
19

google-cloud-php

Google Cloud Client Library for PHP
PHP
1,085
star
20

elixir-google-api

Elixir client libraries for accessing Google APIs.
Elixir
1,011
star
21

google-cloud-dotnet

Google Cloud Client Libraries for .NET
C#
929
star
22

nodejs-storage

Node.js client for Google Cloud Storage: unified object storage for developers and enterprises, from live data serving to data analytics/ML to data archiving.
TypeScript
828
star
23

oauth2client

This is a Python library for accessing resources protected by OAuth 2.0.
Python
795
star
24

nodejs-dialogflow

Node.js client for Dialogflow: Design and integrate a conversational user interface into your applications and devices.
JavaScript
793
star
25

google-auth-library-python

Google Auth Python Library
Python
744
star
26

python-bigquery

Python
739
star
27

gaxios

An HTTP request client that provides an axios like interface over top of node-fetch. Super lightweight. Supports proxies and all sorts of other stuff.
TypeScript
692
star
28

nodejs-speech

This repository is deprecated. All of its content and history has been moved to googleapis/google-cloud-node.
684
star
29

python-aiplatform

A Python SDK for Vertex AI, a fully managed, end-to-end platform for data science and machine learning.
Python
626
star
30

repo-automation-bots

A collection of bots, based on probot, for performing common maintenance tasks across the open-source repos managed by Google on GitHub.
TypeScript
613
star
31

nodejs-firestore

Node.js client for Google Cloud Firestore: a NoSQL document database built for automatic scaling, high performance, and ease of application development.
JavaScript
612
star
32

google-oauth-java-client

Google OAuth Client Library for Java
Java
606
star
33

api-linter

A linter for APIs defined in protocol buffers.
Go
575
star
34

go-genproto

Generated code for Google Cloud client libraries.
Go
558
star
35

nodejs-pubsub

Node.js client for Google Cloud Pub/Sub: Ingest event streams from anywhere, at any scale, for simple, reliable, real-time stream analytics.
TypeScript
519
star
36

nodejs-translate

Node.js client for Google Cloud Translate: Dynamically translate text between thousands of language pairs.
JavaScript
514
star
37

nodejs-vision

Node.js client for Google Cloud Vision: Derive insight from images.
TypeScript
497
star
38

google-api-java-client-services

Generated Java code for Google APIs
497
star
39

python-bigquery-pandas

Google BigQuery connector for pandas
Python
447
star
40

python-bigquery-sqlalchemy

SQLAlchemy dialect for BigQuery
Python
426
star
41

nodejs-bigquery

Node.js client for Google Cloud BigQuery: A fast, economical and fully-managed enterprise data warehouse for large-scale data analytics.
TypeScript
420
star
42

google-auth-library-ruby

Google Auth Library for Ruby
Ruby
417
star
43

google-auth-library-java

Open source Auth client library for Java
Java
400
star
44

python-dialogflow

This library has moved to https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-dialogflow
397
star
45

python-pubsub

Python
390
star
46

signet

Signet is an OAuth 1.0 / OAuth 2.0 implementation.
Ruby
364
star
47

nodejs-text-to-speech

Node.js client for Google Cloud Text-to-Speech
JavaScript
355
star
48

python-speech

This library has moved to https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-speech
355
star
49

python-storage

Python
339
star
50

google-cloud-php-storage

PHP
322
star
51

google-cloud-php-core

PHP
319
star
52

gapic-generator

Tools for generating API client libraries from API Service Configuration descriptions.
Java
304
star
53

cloud-trace-nodejs

Node.js agent for Cloud Trace: automatically gather latency data about your application
TypeScript
272
star
54

gapic-generator-go

Generate Go API client libraries from Protocol Buffers.
Go
252
star
55

gax-php

Google API Extensions for PHP
PHP
232
star
56

api-common-protos

A standard library for use in specifying protocol buffer APIs.
Starlark
221
star
57

python-firestore

Python
214
star
58

google-cloud-datastore

Low-level, Protobuf-based Java and Python client libraries for Cloud Datastore. Check out google-cloud-java and google-cloud-python first!
Python
213
star
59

nodejs-datastore

Node.js client for Google Cloud Datastore: a highly-scalable NoSQL database for your web and mobile applications.
TypeScript
196
star
60

google-cloud-php-translate

PHP
194
star
61

python-bigquery-dataframes

BigQuery DataFrames
Python
186
star
62

google-cloud-rust

Rust
183
star
63

gapic-showcase

An API that demonstrates Generated API Client (GAPIC) features and common API patterns used by Google.
Go
174
star
64

github-repo-automation

A set of tools to automate multiple GitHub repository management.
TypeScript
174
star
65

google-cloud-php-firestore

PHP
170
star
66

cloud-debug-nodejs

Node.js agent for Google Cloud Debugger: investigate your codeโ€™s behavior in production
TypeScript
169
star
67

java-bigtable-hbase

Java libraries and HBase client extensions for accessing Google Cloud Bigtable
Java
165
star
68

gax-java

This library has moved to https://github.com/googleapis/sdk-platform-java/tree/main/gax-java.
162
star
69

python-vision

This library has moved to https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-vision
160
star
70

google-auth-library-python-oauthlib

Python
160
star
71

nodejs-logging

Node.js client for Stackdriver Logging: Store, search, analyze, monitor, and alert on log data and events from Google Cloud Platform and Amazon Web Services (AWS).
TypeScript
156
star
72

nodejs-tasks

Node.js client for Google Cloud Tasks: A fully managed service that allows you to manage the execution, dispatch and delivery of a large number of distributed tasks.
TypeScript
144
star
73

python-ndb

Python
144
star
74

google-cloudevents

Types for CloudEvents issued by Google
JavaScript
142
star
75

common-protos-php

PHP protocol buffer classes generated from https://github.com/googleapis/api-common-protos
PHP
132
star
76

artman

Artifact Manager, a build and packaging tool for Google API client libraries.
Python
132
star
77

proto-plus-python

Beautiful, idiomatic protocol buffers in Python
Python
132
star
78

googleapis.github.io

The GitHub pages site for the googleapis organization.
HTML
131
star
79

nodejs-language

Node.js client for Google Cloud Natural Language: Derive insights from unstructured text using Google machine learning.
JavaScript
131
star
80

java-pubsub

Java
126
star
81

python-analytics-data

Python
125
star
82

gapic-generator-python

Generate Python API client libraries from Protocol Buffers.
Python
122
star
83

google-auth-library-swift

Auth client library for Swift command-line tools and cloud services. Supports OAuth1, OAuth2, and Google Application Default Credentials.
Swift
122
star
84

python-api-core

Python
118
star
85

nodejs-compute

Node.js client for Google Compute Engine: Scalable, High-Performance Virtual Machines
JavaScript
115
star
86

python-texttospeech

Python
111
star
87

nodejs-spanner

Node.js client for Google Cloud Spanner: the worldโ€™s first fully managed relational database service to offer both strong consistency and horizontal scalability.
TypeScript
111
star
88

java-bigquery

Java
109
star
89

node-gtoken

๐Ÿ”‘ Google Auth Service Account Tokens for Node.js
TypeScript
108
star
90

python-translate

This library has moved to https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-translate
108
star
91

java-storage

Java
104
star
92

go-sql-spanner

Google Cloud Spanner driver for Go's database/sql package.
Go
104
star
93

google-cloud-php-vision

PHP
103
star
94

gax-nodejs

Google API Extensions for Node.js
TypeScript
100
star
95

java-firestore

Java
100
star
96

nodejs-logging-winston

Node.js client integration between Stackdriver Logging and Winston.
TypeScript
100
star
97

python-logging

Python
99
star
98

nodejs-bigtable

Node.js client for Google Cloud Bigtable: Google's NoSQL Big Data database service.
TypeScript
91
star
99

nodejs-secret-manager

A cloud-hosted service that provides a secure and convenient tool for storing API keys, passwords, certificates, and other sensitive data.
JavaScript
89
star
100

synthtool

Python
87
star