Skip to content
Google Cloud Client Library for C++
Branch: master
Clone or download
Latest commit 5f21dc4 Apr 24, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Include Google Cloud Storage as a component [skip ci]. (#634) Jun 3, 2018
bazel Adds spanner_tool for easy experimenting (#2477) Apr 15, 2019
ci
cmake Support compiling spanner_tool with CMake. (#2486) Apr 16, 2019
doc Purge some newly-introduced trailing whitespace. (#2479) Apr 12, 2019
google/cloud Remove AsyncFutureFromCallback. (#2531) Apr 24, 2019
.clang-format Initial classes to make http requests. (#507) May 15, 2018
.clang-tidy Enable bugprone-* clang-tidy checks. (#1627) Dec 14, 2018
.cmake-format.py Simplified external project. (#1231) Oct 9, 2018
.codecov.yml Improve coverage of all examples. (#1045) Aug 31, 2018
.dockerignore Standardize documentation on "cmake-out" for cmake's binary output. (#… Apr 9, 2019
.editorconfig Added EditorConfig support. [skip ci] (#78) Dec 7, 2017
.gitignore Standardize documentation on "cmake-out" for cmake's binary output. (#… Apr 9, 2019
.travis.yml
BUILD Support Bazel-based builds. (#452) Apr 26, 2018
CMakeLists.txt Remove pkg config references from the documentation. (#2327) Mar 25, 2019
CODE_OF_CONDUCT.md Adopt the Contributor Covenant 1.2.0 code of conduct. (#2) Nov 24, 2017
CONTRIBUTING.md
INSTALL.md Standardize documentation on "cmake-out" for cmake's binary output. (#… Apr 9, 2019
LICENSE Initial commit. Nov 24, 2017
README.md Fix chocolately link. (#2521) Apr 18, 2019
WORKSPACE Replace GoogleCloudPlatform -> googleapis. (#1891) Jan 29, 2019

README.md

Google Cloud Platform C++ Client Libraries

C++ Idiomatic Clients for Google Cloud Platform services.

Core Results: Kokoro CI status Kokoro CI status Kokoro CI status Codecov Coverage status

Test Install Instructions: Kokoro install centos status Kokoro install debian status Kokoro install fedora status Kokoro install opensuse status Kokoro install opensuse-leap status Kokoro install ubuntu status Kokoro install ubuntu-xenial status Kokoro install ubuntu-trusty status

Special Builds: Kokoro CI status Kokoro CI status Kokoro CI status Kokoro CI status Kokoro CI status Kokoro CI status Kokoro CI status Kokoro CI status Travis CI status Kokoro CI status

This library supports the following Google Cloud Platform services with clients at the GA quality level:

This library supports the following Google Cloud Platform services with clients at the Beta quality level:

Table of Contents

Requirements

Compiler

The Google Cloud C++ libraries are tested with the following compilers:

Compiler Minimum Version
GCC 4.8
Clang 3.8
MSVC++ 14.1
Apple Clang 8.1

Build Tools

The Google Cloud C++ Client Libraries can be built with CMake or Bazel. The minimal versions of these tools we test with are:

Tool Minimum Version
CMake 3.5
Bazel 0.24.0

Libraries

The libraries also depend on gRPC, libcurl, and the dependencies of those libraries. The Google Cloud C++ Client libraries are tested with the following versions of these dependencies:

Library Minimum version
gRPC v1.16.x
libcurl 7.47.0

Tests

Integration tests at times use the Google Cloud SDK. The integration tests run against the latest version of the SDK on each commit and PR.

Install Dependencies

CentOS (7)

Kokoro install centos status

The development tools distributed with CentOS (notably CMake) are too old to build google-cloud-cpp. In these instructions, we use cmake3 obtained from Software Collections.

rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum install -y centos-release-scl
sudo yum-config-manager --enable rhel-server-rhscl-7-rpms
sudo yum makecache && \
sudo yum install -y automake cmake3 curl-devel gcc gcc-c++ git libtool make \
        openssl-devel pkgconfig tar wget which zlib-devel
ln -sf /usr/bin/cmake3 /usr/bin/cmake && ln -sf /usr/bin/ctest3 /usr/bin/ctest

Debian (Stretch)

Kokoro install debian status

On Debian Stretch, libcurl links against openssl-1.0.2, and one must link against the same version or risk an inconsistent configuration of the library. This is especially important for multi-threaded applications, as openssl-1.0.2 requires explicitly setting locking callbacks. Therefore, to use libcurl one must link against openssl-1.0.2. To do so, we need to install libssl1.0-dev. Note that this removes libssl-dev if you have it installed already, and would prevent you from compiling against openssl-1.1.0.

sudo apt update && \
sudo apt install -y build-essential cmake git gcc g++ cmake \
        libc-ares-dev libc-ares2 libcurl4-openssl-dev libssl1.0-dev make \
        pkg-config tar wget zlib1g-dev

Fedora (29)

Kokoro install fedora status

sudo dnf makecache && \
sudo dnf install -y cmake gcc-c++ git make openssl-devel pkgconfig zlib-devel

OpenSUSE (Tumbleweed)

Kokoro install opensuse status

sudo zypper refresh && \
sudo zypper install --allow-downgrade -y cmake gcc gcc-c++ git gzip \
        libcurl-devel libopenssl-devel make tar wget

OpenSUSE (Leap)

Kokoro install opensuse-leap status

sudo zypper refresh && \
sudo zypper install --allow-downgrade -y cmake gcc gcc-c++ git gzip \
        libcurl-devel libopenssl-devel make tar wget

Ubuntu (18.04 - Bionic Beaver)

Kokoro install ubuntu status

sudo apt update && \
sudo apt install -y build-essential cmake git gcc g++ cmake \
        libc-ares-dev libc-ares2 libcurl4-openssl-dev libssl-dev make \
        pkg-config tar wget zlib1g-dev

Ubuntu (16.04 - Xenial Xerus)

Kokoro install ubuntu-xenial status

sudo apt update && \
sudo apt install -y build-essential cmake git gcc g++ cmake \
        libcurl4-openssl-dev libssl-dev make \
        pkg-config tar wget zlib1g-dev

Ubuntu (14.04 - Trusty Tahr)

Kokoro install ubuntu-trusty status

We use the ubuntu-toolchain-r PPA to get a modern version of CMake:

sudo apt update && sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
sudo apt update && \
sudo apt install -y cmake3 git gcc g++ make pkg-config tar wget zlib1g-dev

Ubuntu:14.04 ships with a very old version of OpenSSL, this version is not supported by gRPC. We need to compile and install OpenSSL-1.0.2 from source.

cd $HOME/Downloads
wget -q https://www.openssl.org/source/openssl-1.0.2n.tar.gz
tar xf openssl-1.0.2n.tar.gz
cd $HOME/Downloads/openssl-1.0.2n
./config --shared
make -j $(nproc)
sudo make install

Note that by default OpenSSL installs itself in /usr/local/ssl. Installing on a more conventional location, such as /usr/local or /usr, can break many programs in your system. OpenSSL 1.0.2 is actually incompatible with with OpenSSL 1.0.0 which is the version expected by the programs already installed by Ubuntu 14.04.

In any case, as the library installs itself in this non-standard location, we also need to configure CMake and other build program to find this version of OpenSSL:

export OPENSSL_ROOT_DIR=/usr/local/ssl
export PKG_CONFIG_PATH=/usr/local/ssl/lib/pkgconfig

macOS (using brew)

brew install curl cmake libressl c-ares

Windows (using vcpkg)

If you are already using vcpkg, a package manager from Microsoft, you can download and compile google-cloud-cpp in a single step:

.\vcpkg.exe install google-cloud-cpp:x64-windows-static

This command will also print out instructions on how to use the library from your MSBuild or CMake-based projects. We try to keep the version of google-cloud-cpp included with vcpkg up-to-date, our practice is to submit a PR to update the version in vcpkg after each release of google-cloud-cpp.

See below for instructions to compile the code yourself.

Build

To build all available libraries and run the tests, run the following commands after cloning this repo:

Linux

# Add -DBUILD_TESTING=OFF to disable tests
cmake -H. -Bcmake-out

# Adjust the number of threads used by modifying parameter for `-j 4`
cmake --build cmake-out -- -j 4

# Verify build by running tests
(cd cmake-out && ctest --output-on-failure)

You will find compiled binaries in cmake-out/ respective to their source paths.

macOS

export OPENSSL_ROOT_DIR=/usr/local/opt/libressl
# Add -DBUILD_TESTING=OFF to disable tests
cmake -H. -Bcmake-out

# Adjust the number of threads used by modifying parameter for `-j 4`
cmake --build cmake-out -- -j 4

# Verify build by running tests
(cd cmake-out && ctest --output-on-failure)

You will find compiled binaries in cmake-out/ respective to their source paths.

Windows

If you prefer to manually compile on Windows the following instructions should work, though there is a lot more variability on this platform. We welcome suggestions to make this an easier process.

We will assume that you have installed CMake, Ninja, and "Microsoft Visual Studio 2017". If you have not, install Chocolatey using this command as the administrator:

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -Command ^
 "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

Then you can easily install the necessary development tools.

choco install -y cmake cmake.portable ninja visualstudio2017community
choco install -y visualstudio2017-workload-nativedesktop
choco install -y microsoft-build-tools
choco install -y git

Then clone and compile vcpkg:

set SOURCE="%cd%"
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

Use vcpkg to download and install google-cloud-cpp's dependencies:

.\vcpkg.exe install openssl:x64-windows-static ^
    grpc:x64-windows-static ^
    curl:x64-windows-static ^
    gtest:x64-windows-static ^
    crc32c:x64-windows-static
.\vcpkg.exe integrate install

Now clone google-cloud-cpp:

cd ..
git clone https://github.com/googleapis/google-cloud-cpp.git
cd google-cloud-cpp

Load the environment variables needed to use Microsoft Visual Studio:

call "c:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"

Use CMake to create the build files:

cmake -H. -Bcmake-out -GNinja ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DCMAKE_TOOLCHAIN_FILE="%SOURCE%\vcpkg\scripts\buildsystems\vcpkg.cmake" ^
    -DVCPKG_TARGET_TRIPLET=x64-windows-static ^
    -DCMAKE_C_COMPILER=cl.exe ^
    -DCMAKE_CXX_COMPILER=cl.exe ^
    -DGOOGLE_CLOUD_CPP_DEPENDENCY_PROVIDER=package ^
    -DCMAKE_MAKE_PROGRAM=ninja

And compile the code:

cmake --build cmake-out

Finally, verify the unit tests pass:

cd cmake-out
ctest --output-on-failure

You will find compiled binaries in cmake-out\ respective to their source directories.

Install

By default google-cloud-cpp downloads and compiles all its dependencies. The default configuration disables the install target, because the version of the dependencies downloaded by google-cloud-cpp may conflict with the versions already installed in your system, or with the versions you want to use for development.

To install google-cloud-cpp you must first install all its dependencies. Then you must configure google-cloud-cpp to find these dependencies, and install it.

Installing the dependencies themselves may be as simple as using the package manager for your platform, or may require manually downloading, compiling, and installing said dependencies. The INSTALL.md file describes how to successfully install google-cloud-cpp on several platforms.

Alternatively, if you prefer to use google-cloud-cpp as a submodule, you can use the CMake command add_subdirectory() to include google-cloud-cpp directly in your CMake project.

Versioning

Please note that the Google Cloud C++ client libraries do not follow Semantic Versioning.

GA: Libraries defined at a GA quality level are expected to be stable and any backwards-incompatible changes will be noted in the documentation. Major changes to the API will signaled by changing major version number (e.g. 1.x.y -> 2.0.0).

Beta: Libraries defined at a Beta quality level are expected to be mostly stable and we're working towards their release candidate. We will address issues and requests with a higher priority.

Alpha: Libraries defined at an Alpha quality level are still a work-in-progress and are more likely to get backwards-incompatible updates. Additionally, it's possible for Alpha libraries to get deprecated and deleted before ever being promoted to Beta or GA.

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.

You can’t perform that action at this time.