kubernetes/vendor/k8s.io/gengo/v2

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 in this repo or the more extensive tools in the 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 for instructions on how to contribute.