Skip to content

Latest commit

 

History

History
115 lines (83 loc) · 4.96 KB

compile-time-configuration.md

File metadata and controls

115 lines (83 loc) · 4.96 KB
Raw

Compile time configuration for google-cloud-cpp

The google-cloud-cpp libraries have a number of compile-time configuration options. This document describes these options and provides some motivation to use them (or not).

The bulk of this document is about CMake-based builds. Bazel-based builds also have a small number of options and are also described here.

CMake Options

We expect that most application developers using CMake will compile and install google-cloud-cpp and then use it as an external dependency. Some application developers may use google-cloud-cpp via FetchContent() or some other kind of super build. In the latter case you should note how this project configures testing and features.

As usual, application developers can use ccmake, or run cmake -L to discover all options in the project.

Enabling and disabling features

The GOOGLE_CLOUD_CPP_ENABLE CMake option configures what features are enabled at compile time.

Most features correspond to a single library. For example, enabling the kms compiles and installs the google-cloud-cpp::kms library.

Some features represent groups of libraries. For example, __ga_libraries__ requests all the GA libraries, and __experimental_libraries__ represent the libraries that are not yet GA.

A few features enable experimental functionality. We do not expect that customers will need to use these. If you have specific questions please start a GitHub Discussion. With that said:

  • generator enables an internal-only tool to generate new libraries.
  • experimental-storage_grpc enables the GCS+gRPC plugin. Contact your account team if you want to use this feature or are interested in the GA timeline.
  • experimental-http-transcoding enables support for HTTP/1.1 transport (as opposed to gRPC over HTTP/2) in some libraries.
  • opentelemetry enables support for OpenTelemetry.

Override Protobuf compiler and gRPC's plugin

google-cloud-cpp uses the protobuf compiler and gRPC's plugin to generate code from the Protobuf API definitions. By default it finds these tools using the targets exported by find_package(Protobuf CONFIG) and find_package(gRPC CONFIG). These defaults do not work when cross-compiling, as the packages will point to the tools for the target environment, and they may not run in the host environment, where the build is running.

You can override these tools using -DProtobuf_PROTOC_EXECUTABLE=/path/... and -DGOOGLE_CLOUD_CPP_GRPC_PLUGIN_EXECUTABLE=/other-path/....

Disabling C++ Exceptions

google-cloud-cpp does not throw exceptions to signal errors. Though in some cases the application may call a function to throw an exception on errors. Some applications require their libraries to be compiled without exception support. Use -DGOOGLE_CLOUD_CPP_ENABLE_CXX_EXCEPTIONS=OFF if that is the case.

Checking OpenSSL version on macOS

A common mistake on macOS is to use the system's OpenSSL with google-cloud-cpp. This configuration is not supported, and the build stops to provide a better error message. If this error message is not applicable to your environment use -DGOOGLE_CLOUD_CPP_ENABLE_MACOS_OPENSSL_CHECK=OFF.

Enabling tests and examples

The tests are enabled via -DBUILD_TESTING=ON. You can disable the examples using -DGOOGLE_CLOUD_CPP_ENABLE_EXAMPLES=OFF. This may speed up your build times.

Bazel Options

We expect that application developers using Bazel will include google-cloud-cpp as an external dependency.

The C++ Standard

The default Bazel toolchain forces C++11 on Linux and macOS. google-cloud-cpp requires C++14, so you will need to update the C++ standard version. You must either:

  • Provide your own C++ toolchain configuration for Bazel. Consult the Bazel documentation if you want to attempt this approach.
  • Add --cxxopt=-std=c++14 and --host_cxxopt=-std=c++14 (or higher) in your Bazel command-line.
  • Add the same options in your Bazel .bazelrc file.

The --host_cxxopt may be unfamiliar. This is required to support Protobuf and gRPC, which compile code generators for the "host" environment, and generate libraries for the "target" environment.

Enabling OpenTelemetry

OpenTelemetry is disabled by default. Add --//:enable_opentelemetry to your Bazel command-line parameters to enable OpenTelemetry features, such as instrumentation to collect distributed traces.

See the OpenTelemetry quickstart for more details.

Workarounds

gRPC circa 1.58.1 fails to build with Bazel and Clang >= 16 (see grpc#34482). Add the --features=-layering_check option to your Bazel command-line or add build: --features=-layering_check to your .bazelrc file.