# gogol-gen

For pull requests which affect generated output, please _do not include_ the
actual regenerated service code, only commit the updates to the generator,
config and annex connection.

This ensures the Continuous Integration process is the single source of truth
for generated code changes, and keeps pull requests readable and focused on
actual generator code/logic changes.

## Generating

The configuration for the generation step of each individual service endpoint lives
under `./annex`. The naming matches the Google Discovery Service naming of endpoints,
which are vendored under `./model`.

Rather than actually crawling the Discovery Service, the [Google API Go Client](https://www.github.com/google/google-api-go-client)
is vendored under `./vendor`, and the JSON service definitions are copied to `./model`
to ensure reproducibility of the generation steps and the abilitry to diff across versions.

### Example: Cloud Dataproc

To add a new endpoint, first create the related JSON configuration in the `./annex` directory.

Since the Cloud Dataproc API is called `dataproc-api.json` in the Google Discovery API,
you would create the configuration `./annex/dataproc.json` with the following contents:

```
{
 "library": "dataproc",
 "canonicalName": "Dataproc"
}
```

Then, the `Makefile` is used:

```
make clean
make
```

This will build the `./bin/gogol-gen` binary, and will generate a Haskell library
for each API that has matching `./annex/*.json` configuration.

For the above example, the result would be a `../gogol-dataproc` directory at the
top-level of the project containing the generated API client.

> `make full-clean` can be used to cause a complete re-download of all (including new)
service models.

> Individual clients/SDKs can be generated by passing a specific `MODELS` environment
variable to the `make` command, for example: `MODELS=model/admin/directory/v1/admin-api.json make`