gen/README.md · gogol · git.iko.soy

on develop help sign in

gogol/gen/README.md

52 lines 1.9 kB history raw

1# gogol-gen

3For pull requests which affect generated output, please _do not include_ the

4actual regenerated service code, only commit the updates to the generator,

5config and annex connection.

7This ensures the Continuous Integration process is the single source of truth

8for generated code changes, and keeps pull requests readable and focused on

9actual generator code/logic changes.

11## Generating

13The configuration for the generation step of each individual service endpoint lives

14under `./annex`. The naming matches the Google Discovery Service naming of endpoints,

15which are vendored under `./model`.

17Rather than actually crawling the Discovery Service, the [Google API Go Client](https://www.github.com/google/google-api-go-client)

18is vendored under `./vendor`, and the JSON service definitions are copied to `./model`

19to ensure reproducibility of the generation steps and the abilitry to diff across versions.

21### Example: Cloud Dataproc

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

25Since the Cloud Dataproc API is called `dataproc-api.json` in the Google Discovery API,

26you would create the configuration `./annex/dataproc.json` with the following contents:

28```

30 "library": "dataproc",

31 "canonicalName": "Dataproc"

33```

35Then, the `Makefile` is used:

37```

38make clean

39make

40```

42This will build the `./bin/gogol-gen` binary, and will generate a Haskell library

43for each API that has matching `./annex/*.json` configuration.

45For the above example, the result would be a `../gogol-dataproc` directory at the

46top-level of the project containing the generated API client.

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

49service models.

51> Individual clients/SDKs can be generated by passing a specific `MODELS` environment

52variable to the `make` command, for example: `MODELS=model/admin/directory/v1/admin-api.json make`