Skip to content

Latest commit

 

History

History
116 lines (76 loc) · 3.4 KB

docker.rst

File metadata and controls

116 lines (76 loc) · 3.4 KB
Raw

Docker Image

If you are just getting started with code generation for protobuf-based APIs, or if you do not have a robust Python environment already available, we recommend using our Docker image to build client libraries.

However, this tool offers first-class support for local execution using protoc: getting-started/local. It is still reasonably easy, but initial setup will take a bit longer.

Note

If you are interested in contributing, using a local installation is recommended.

Installing

Docker

In order to use a Docker image, you must have Docker installed. Docker is a container management service, and is available on Linux, Mac, and Windows (although most of these instructions will be biased toward Linux and Mac).

Install Docker according to their installation instructions.

Note

This image requires Docker 17.05 or later.

Pull the Docker Image

Once Docker is installed, simply pull the Docker image for this tool:

$ docker pull gcr.io/gapic-images/gapic-generator-python:

Usage

Example

Compiling an API

Note

If you are running code generation repeatedly, executing the long docker run command may be cumbersome. While you should ensure you understand this section, a shortcut script<docker-shortcut> is available to make iterative work easier.

Compile the API into a client library by invoking the Docker image.

It is worth noting that the image must interact with the host machine (your local machine) for two things: reading in the protos you wish to compile, and writing the output. This means that when you run the image, two mount points are required in order for anything useful to happen.

In particular, the input protos are expected to be mounted into /in/, and the desired output location is expected to be mounted into /out/. The output directory must also be writable.

Note

The /in/ and /out/ directories inside the image are hard-coded; they can not be altered where they appear in the command below.

Perform that step with docker run:

# This is assumed to be run from the `googleapis` project root.
$ docker run \
  --mount type=bind,source=google/cloud/vision/v1/,destination=/in/google/cloud/vision/v1/,readonly \
  --mount type=bind,source=dest/,destination=/out/ \
  --rm \
  --user $UID \
  gcr.io/gapic-images/gapic-generator-python

Warning

protoc is very picky about paths, and the exact construction here matters a lot. The source is google/cloud/vision/v1/, and then the destination is that full directory path after the /in/ root; therefore: /in/google/cloud/vision/v1/.

This matters because of how proto imports are resolved. The import statement imports a file, relative to a base directory or set of base directories, called the proto_path. This is assumed (and hard-coded) to /in/ in the Docker image, and so any directory structure present in the imports of the proto files must be preserved beneath this for compilation to succeed.