Debian Codegraph @

v2/README.md

raw
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.