54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
[![GoDoc Widget]][GoDoc] [![GoReport]][GoReportStatus]
|
|
|
|
[GoDoc]: https://godoc.org/k8s.io/gengo
|
|
[GoDoc Widget]: https://godoc.org/k8s.io/gengo?status.svg
|
|
[GoReport]: https://goreportcard.com/badge/github.com/kubernetes/gengo
|
|
[GoReportStatus]: https://goreportcard.com/report/github.com/kubernetes/gengo
|
|
|
|
# Gengo: a framework for building simple code generators
|
|
|
|
This repo is used by Kubernetes to build some codegen tooling. It is not
|
|
intended to be general-purpose and makes some assumptions that may not hold
|
|
outside of Kubernetes.
|
|
|
|
In the past this repo was partially supported for external use (outside of the
|
|
Kubernetes project overall), but that is no longer true. We may change the API
|
|
in incompatible ways, without warning.
|
|
|
|
If you are not building something that is part of Kubernetes, DO NOT DEPEND ON
|
|
THIS REPO.
|
|
|
|
## New usage within Kubernetes
|
|
|
|
Gengo is a very opinionated framework. It is primarily aimed at generating Go
|
|
code derived from types defined in other Go code, but it is possible to use it
|
|
for other things (e.g. proto files). Net new tools should consider using
|
|
`golang.org/x/tools/go/packages` directly. Gengo can serve as an example of
|
|
how to do that.
|
|
|
|
If you still decide you want to use gengo, see the
|
|
[simple examples](./examples) in this repo or the more extensive tools in the
|
|
Kubernetes [code-generator](https://github.com/kubernetes/code-generator/)
|
|
repo.
|
|
|
|
## Overview
|
|
|
|
Gengo is used to build tools (generally a tool is a binary). Each tool
|
|
describes some number of `Targets`. A target is a single output package, which
|
|
may be the same as the inputs (if the tool generates code alongside the inputs)
|
|
or different. Each `Target` describes some number of `Generators`. A
|
|
generator is responsible for emitting a single file into the target directory.
|
|
|
|
Gengo helps the tool to load and process input packages, e.g. extracting type
|
|
information and associating comments. Each target will be offered every known
|
|
type, and can filter that down to the set of types it cares about. Each
|
|
generator will be offered the result of the target's filtering, and can filter
|
|
the set of types further. Finally, the generator will be called to emit code
|
|
for all of the remaining types.
|
|
|
|
The `tracer` example in this repo can be used to examine all of the hooks.
|
|
|
|
## Contributing
|
|
|
|
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.
|