diff --git a/.dockerignore b/.dockerignore index 67cb2311af..1fefa15a3b 100644 --- a/.dockerignore +++ b/.dockerignore @@ -2,10 +2,6 @@ .git .gitignore -# Docker scaffolding -Dockerfile -.dockerignore - # Python scaffolding *.py[cod] *.egg diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 71a201f1b9..0000000000 --- a/Dockerfile +++ /dev/null @@ -1,20 +0,0 @@ -FROM python:3.13-slim - -# Install system packages. -RUN apt-get update \ - && apt-get install -y --no-install-recommends \ - pandoc \ - && rm -rf /var/lib/apt/lists/* - -# Add protoc and our common protos. -COPY --from=gcr.io/gapic-images/api-common-protos:latest /usr/local/bin/protoc /usr/local/bin/protoc -COPY --from=gcr.io/gapic-images/api-common-protos:latest /protos/ /protos/ - -# Add our code to the Docker image. -ADD . /usr/src/gapic-generator-python/ - -# Install the tool within the image. -RUN pip install /usr/src/gapic-generator-python - -# Define the generator as an entry point. -ENTRYPOINT ["/usr/src/gapic-generator-python/docker-entrypoint.sh"] diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh deleted file mode 100755 index 944ab9297c..0000000000 --- a/docker-entrypoint.sh +++ /dev/null @@ -1,50 +0,0 @@ -#!/bin/bash -# Copyright 2019 Google LLC -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -PLUGIN_OPTIONS="" - -# Parse out options. -while [ -n "$1" ]; do - case "$1" in - -- ) - shift - break - ;; - * ) - # If this switch begins with "--python-gapic-" or "--gapic-", then it is - # meant for us. - if [[ $1 == --python-gapic-* ]]; then - PLUGIN_OPTIONS="$PLUGIN_OPTIONS,$1=$2" - shift 2 - elif [[ $1 == --gapic-* ]]; then - PLUGIN_OPTIONS="$PLUGIN_OPTIONS,$1=$2" - shift 2 - elif [[ $1 == --samples* ]]; then - # --samples is a special option that all generators should recognize. - PLUGIN_OPTIONS="$PLUGIN_OPTIONS,$1=$2" - shift 2 - else - # Ignore anything we do not recognize. - shift - fi - ;; - esac -done - -protoc --proto_path=/protos/ --proto_path=/in/ \ - --experimental_allow_proto3_optional \ - --python_gapic_out=/out/ \ - --python_gapic_opt=${PLUGIN_OPTIONS:1} \ - `find /in/ -name *.proto` diff --git a/docs/getting-started/_verifying.rst b/docs/getting-started/_verifying.rst index 3b25c4537e..325090ed1a 100644 --- a/docs/getting-started/_verifying.rst +++ b/docs/getting-started/_verifying.rst @@ -1,8 +1,8 @@ Verifying the Library --------------------- -Once you have compiled a client library, whether using a Docker image, -local installation or bazel, it is time for the fun part: actually running it! +Once you have compiled a client library, whether using a local installation +or bazel, it is time for the fun part: actually running it! Create a virtual environment for the library: diff --git a/docs/getting-started/docker-shortcut.rst b/docs/getting-started/docker-shortcut.rst deleted file mode 100644 index 88f3ef8096..0000000000 --- a/docs/getting-started/docker-shortcut.rst +++ /dev/null @@ -1,28 +0,0 @@ -:orphan: - -.. _docker-shortcut: - -Docker Shortcut Script ----------------------- - -Because code generation requires two mounts from the host machine into -the Docker image, and because the paths are somewhat pedantic, you may -find this shortcut script to be handy: - -.. literalinclude:: ../../gapic.sh - :language: shell - -Place it somewhere on your system, marked executable. - -Once available, it can be invoked using: - -.. code-block:: shell - - # This is assumed to be from the "proto root" directory. - $ gapic.sh --image gcr.io/gapic-images/gapic-generator-python \ - --in path/to/src/protos/ - --out dest/ - - -It will work not only with the Python code generator, but all of our code -generators that implement this Docker interface. diff --git a/docs/getting-started/docker.rst b/docs/getting-started/docker.rst deleted file mode 100644 index e7600974c4..0000000000 --- a/docs/getting-started/docker.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. _getting-started/docker: - -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: :ref:`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. - -.. _Docker: https://docker.com/ - - -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. - -.. _installation instructions: https://docs.docker.com/install/ - -Pull the Docker Image -~~~~~~~~~~~~~~~~~~~~~ - -Once Docker is installed, simply pull the Docker image for this tool: - -.. parsed-literal:: - - $ docker pull gcr.io/gapic-images/gapic-generator-python:\ |version|\ - - -Usage ------ - -.. include:: _usage_intro.rst - -Example -~~~~~~~ - -.. include:: _example.rst - - -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 :ref:`shortcut script` - 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. - -Docker requires the output directory to pre-exist; create a directory where -you want the generated code to go: - -.. code-block:: sh - - $ mkdir dest/ - -Perform the actual code generation step with ``docker run``: - -.. code-block:: shell - - # This is assumed to be run from the `googleapis` project root. - $ docker run \ - --mount type=bind,source=$(pwd)/google/cloud/vision/v1/,destination=/in/google/cloud/vision/v1/,readonly \ - --mount type=bind,source=$(pwd)/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. - -.. include:: _samplegen.rst - -.. code-block:: shell - - # Multiple sample paths or directories can be passed simultaneously by duplicating - # the 'samples' option. - # If no 'samples' option is passed, the generator does not generate a manifest. - $ docker run \ - --mount type=bind,source=$(pwd)/path/to/proto/dir,destination=/in/path/to/proto,readonly \ - --mount type=bind,source=$(pwd)/dest/,destination=/out/ \ - --rm \ - --user $UID \ - gcr.io/gapic-images/gapic-generator-python \ - --samples path/to/sample/config.yaml \ - --samples path/to/sample/dir/ - - -.. include:: _verifying.rst diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index 4d48936139..6f288f6bb5 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -5,29 +5,13 @@ This code generator is implemented as a plugin to ``protoc``, the compiler for `protocol buffers`_, and will run in any environment that Python 3.7+ and protocol buffers do. -Because dependency management and such can be a significant undertaking, we -offer a Docker image and interface which requires you only to have Docker -installed and provide the protos for your API. Alternatively, the generator is -also invocable via bazel rules. +It is recommended to install the tool locally and run it through ``protoc``. -It is also possible to install the tool locally and run it through ``protoc``, -and this approach is fully supported. - -.. note:: - - The Docker approach is recommended for users new to this ecosystem, or - those which do not have a robust Python environment available. If you want - to experiment with generating client libraries but do not want to make - changes to the generator itself, try the Docker image first. - - The bazel approach is recommended for established pipelines. It is more - lightweight than the Docker image but may take some more effort to set up. .. _protocol buffers: https://developers.google.com/protocol-buffers/ .. toctree:: :maxdepth: 4 - docker local bazel diff --git a/docs/getting-started/local.rst b/docs/getting-started/local.rst index db474e3a2d..e86ba51797 100644 --- a/docs/getting-started/local.rst +++ b/docs/getting-started/local.rst @@ -3,11 +3,7 @@ Local Installation ================== -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, it is -probably easier to get started using Docker: :ref:`getting-started/docker` - -However, this tool offers first-class support for local execution using +This tool offers first-class support for local execution using ``protoc``. It is still reasonably easy, but initial setup will take a bit longer. diff --git a/docs/templates.rst b/docs/templates.rst index 6cba349413..09807ad9c7 100644 --- a/docs/templates.rst +++ b/docs/templates.rst @@ -130,33 +130,5 @@ provided by this library, use the special `DEFAULT` string: --python_gapic_opt="python-gapic-templates=/path/to/templates" --python_gapic_opt="python-gapic-templates=DEFAULT" -Building with Docker -~~~~~~~~~~~~~~~~~~~~ - -When building with Docker, you instead provide the ``--python-gapic-templates`` -argument after the ``docker run`` command: - -.. code-block:: shell - - $ docker run \ - --mount type=bind,source=google/cloud/vision/v1/,destination=/in/google/cloud/vision/v1/,readonly \ - --mount type=bind,source=dest/,destination=/out/ \ - --mount type=bind,source=/path/to/templates,destination=/templates/,readonly \ - --rm \ - --user $UID \ - gcr.io/gapic-images/gapic-generator-python \ - --python-gapic-templates /templates/ \ - --python-gapic-templates DEFAULT - -As before, to provide more than one location for templates, specify the -argument more than once. - -.. warning:: - - If you are using custom templates with Docker, be sure to also mount - the directory with the templates into the Docker image; otherwise - the generator will not be able to read that directory. When specifying - the ``--python-gapic-templates`` argument, it is the path *inside* - the Docker image that matters! .. _Jinja: http://jinja.pocoo.org/docs/2.10/ diff --git a/gapic.sh b/gapic.sh deleted file mode 100755 index 17f5c563a3..0000000000 --- a/gapic.sh +++ /dev/null @@ -1,105 +0,0 @@ -#!/bin/bash -# Copyright 2018 Google LLC -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -CMD="$0" - -# Set variables used by this script. -# All of these are set in options below, and all but $PATH are required. -IMAGE= -IN= -OUT= -PLUGIN_OPTIONS= -PROTO_PATH=`pwd` - -# Print help and exit. -function show_help { - echo "Usage: $CMD --image IMAGE --in IN_DIR --out OUT_DIR [--path PATH_DIR]" - echo "" - echo "Required arguments:" - echo " --image The Docker image to use. The script will attempt to pull" - echo " it if it is not present." - echo " -i, --in A directory containing the protos describing the API" - echo " to be generated." - echo " -o, --out Destination directory for the completed client library." - echo "" - echo "Optional arguments:" - echo " -p, --path The base import path for the protos. Assumed to be the" - echo " current working directory if unspecified." - echo " -h, --help This help information." - exit 0 -} - -# Parse out options. -while true; do - case "$1" in - -h | --help ) show_help ;; - --image ) IMAGE="$2"; shift 2 ;; - -i | --in ) IN="$2"; shift 2 ;; - -o | --out ) OUT="$2"; shift 2 ;; - -p | --path ) PROTO_PATH=$2; shift 2 ;; - --* ) PLUGIN_OPTIONS="$PLUGIN_OPTIONS $1 $2"; shift 2 ;; - -- ) shift; break; ;; - * ) break ;; - esac -done - -# Ensure that all required options are set. -if [ -z "$IMAGE" ] || [ -z "$IN" ] || [ -z "$OUT" ]; then - >&2 echo "Required argument missing." - >&2 echo "The --image, --in, and --out arguments are all required." - >&2 echo "Run $CMD --help for more information." - exit 64 -fi - -# Ensure that the input directory exists (and is a directory). -if ! [ -d "${PROTO_PATH}/$IN" ]; then - >&2 echo "Directory does not exist: ${PROTO_PATH}/$IN" - exit 2 -fi - -# Ensure Docker is running and seems healthy. -# This is mostly a check to bubble useful errors quickly. -if ! docker ps > /dev/null; then - exit $? -fi - -# If the output directory does not exist, create it. -if ! mkdir -p $OUT ; then - exit $? -fi - -# If the output directory is not empty, warn (but continue). -if [ "$(ls -A $OUT )"]; then - >&2 echo "Warning: Output directory is not empty." -fi - -# Convert IN and OUT to absolute paths for Docker -CWD=`pwd` -cd ${PROTO_PATH}/$IN -ABS_IN=`pwd` -cd $CWD -cd $OUT -ABS_OUT=`pwd` -cd $CWD - -# Generate the client library. -docker run \ - --mount type=bind,source=${ABS_IN},destination=/in/${IN},readonly \ - --mount type=bind,source=${ABS_OUT},destination=/out \ - --rm \ - --user $UID \ - $IMAGE \ - $PLUGIN_OPTIONS -exit $?