This tool helps to generate and layout cloud client libraries.

This tool requires Python 3.6. Either install it from python.org or use pyenv to get 3.6.

# Install latest

python3 -m pip install --user --upgrade git+https://github.com/googleapis/synthtool.git

# Install stable
python3 -m pip install --user --upgrade gcp-synthtool

To start the process of generation, we need to clone the destination repository.

git clone [email protected]:googleapis/google-cloud-python.git
cd google-cloud-python
cd {cloud-package}

If a synth.py script is not present at the root of the package, we will need to author a synth.py script. You can grab one from another package (for instance tasks in python) or start from scratch.

We run synthtool as follows:

python -m synthtool

Once you run synthtool without errors:

• Investigate the changes it made just to be certain everything looks reasonable
• run the unit tests (nox)
• commit and push the changes to a branch and open a PR!

Node.js generation is similar to python. For an example synth.py you can look at https://github.com/googleapis/nodejs-speech/blob/master/synth.py.

• TODO. Should be similar to Python

Synthtool supports template files using jinja. As an example let's look at node.js. The templates for node can be found at /synthtool/gcp/templates/node_library/. The following is taken from a node.js synth script.

common_templates = gcp.CommonTemplates()

templates = common_templates.node_library(package_name="@google-cloud/speech")
s.copy(templates)

package_name is a keyword arg that is used by a jinja template. Jinja uses {{ package_name }} to customize the template for a specific package. You can add additionaly keyword args as necessary.

Synthtool supports generation from googleapis/googleapis-private.

gapic = gcp.GAPICGenerator()
library = gapic.node_library('speech', 'v1', private=True)

2FA is required to clone a private repo.

• Using SSH: Before running Synthtool, set the environment variable AUTOSYNTH_USE_SSH to true. The repo will be cloned using SSH.
• Using HTTPS: Generate a GitHub Personal Access Token with scope repo. Run synthtool. When GitHub prompts for your GitHub password, provide the access token instead.

synthtool > Cloning googleapis-private.
Username for 'https://github.com': busunkim96
Password for 'https://[email protected]':

Synthtool uses the latest version of the Artman Docker image. You can change this by setting the environment variable SYNTHTOOL_ARTMAN_VERSION to the desired version tag.

export SYNTHTOOL_ARTMAN_VERSION=0.16.2

Synthtool supports generation from a local copy of googleapis. Specify the path togoogleapis in the environment variable SYNTHTOOL_GOOGLEAPIS.

export SYNTHTOOL_GOOGLEAPIS=path/to/local/googleapis

Synthtool will run Artman which will create generated code that can be found at ~/.cache/synthtool/googleapis<-private>/artman_genfiles. This is useful for figuring out what it is you need to copy for your specific library.