| 1 |
[![GoDoc Widget]][GoDoc] [![GoReport]][GoReportStatus] |
| 2 |
|
| 3 |
[GoDoc]: https://godoc.org/k8s.io/gengo |
| 4 |
[GoDoc Widget]: https://godoc.org/k8s.io/gengo?status.svg |
| 5 |
[GoReport]: https://goreportcard.com/badge/github.com/kubernetes/gengo |
| 6 |
[GoReportStatus]: https://goreportcard.com/report/github.com/kubernetes/gengo |
| 7 |
|
| 8 |
# Gengo: a framework for building simple code generators |
| 9 |
|
| 10 |
This repo is used by Kubernetes to build some codegen tooling. It is not |
| 11 |
intended to be general-purpose and makes some assumptions that may not hold |
| 12 |
outside of Kubernetes. |
| 13 |
|
| 14 |
In the past this repo was partially supported for external use (outside of the |
| 15 |
Kubernetes project overall), but that is no longer true. We may change the API |
| 16 |
in incompatible ways, without warning. |
| 17 |
|
| 18 |
If you are not building something that is part of Kubernetes, DO NOT DEPEND ON |
| 19 |
THIS REPO. |
| 20 |
|
| 21 |
## New usage within Kubernetes |
| 22 |
|
| 23 |
Gengo is a very opinionated framework. It is primarily aimed at generating Go |
| 24 |
code derived from types defined in other Go code, but it is possible to use it |
| 25 |
for other things (e.g. proto files). Net new tools should consider using |
| 26 |
`golang.org/x/tools/go/packages` directly. Gengo can serve as an example of |
| 27 |
how to do that. |
| 28 |
|
| 29 |
If you still decide you want to use gengo, see the |
| 30 |
[simple examples](./examples) in this repo or the more extensive tools in the |
| 31 |
Kubernetes [code-generator](https://github.com/kubernetes/code-generator/) |
| 32 |
repo. |
| 33 |
|
| 34 |
## Overview |
| 35 |
|
| 36 |
Gengo is used to build tools (generally a tool is a binary). Each tool |
| 37 |
describes some number of `Targets`. A target is a single output package, which |
| 38 |
may be the same as the inputs (if the tool generates code alongside the inputs) |
| 39 |
or different. Each `Target` describes some number of `Generators`. A |
| 40 |
generator is responsible for emitting a single file into the target directory. |
| 41 |
|
| 42 |
Gengo helps the tool to load and process input packages, e.g. extracting type |
| 43 |
information and associating comments. Each target will be offered every known |
| 44 |
type, and can filter that down to the set of types it cares about. Each |
| 45 |
generator will be offered the result of the target's filtering, and can filter |
| 46 |
the set of types further. Finally, the generator will be called to emit code |
| 47 |
for all of the remaining types. |
| 48 |
|
| 49 |
The `tracer` example in this repo can be used to examine all of the hooks. |
| 50 |
|
| 51 |
## Contributing |
| 52 |
|
| 53 |
Please see [CONTRIBUTING.md](../CONTRIBUTING.md) for instructions on how to contribute. |