README
¶
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.
Documentation
¶
Overview ¶
Package gengo is a code-generation framework.
Index ¶
- Constants
- func Execute(nameSystems namer.NameSystems, defaultSystem string, ...) error
- func ExtractCommentTags(marker string, lines []string) map[string][]string
- func ExtractSingleBoolCommentTag(marker string, key string, defaultVal bool, lines []string) (bool, error)
- func GoBoilerplate(headerFile, buildTag, generatedBy string) ([]byte, error)
Constants ¶
const StdBuildTag = "ignore_autogenerated"
StdBuildTag is a suggested build-tag which tools can use both as an argument to GoBoilerplate and to Execute.
const StdGeneratedBy = "// Code generated by GENERATOR_NAME. DO NOT EDIT."
StdGeneratedBy is a suggested "generated by" line which tools can use as an argument to GoBoilerplate.
Variables ¶
This section is empty.
Functions ¶
func Execute ¶
func Execute(nameSystems namer.NameSystems, defaultSystem string, getTargets func(*generator.Context) []generator.Target, buildTag string, patterns []string) error
Execute implements most of a tool's main loop.
func ExtractCommentTags ¶
ExtractCommentTags parses comments for lines of the form:
'marker' + "key=value".
Values are optional; "" is the default. A tag can be specified more than one time and all values are returned. If the resulting map has an entry for a key, the value (a slice) is guaranteed to have at least 1 element.
Example: if you pass "+" for 'marker', and the following lines are in the comments:
+foo=value1 +bar +foo=value2 +baz="qux"
Then this function will return:
map[string][]string{"foo":{"value1, "value2"}, "bar": {""}, "baz": {"qux"}}
func ExtractSingleBoolCommentTag ¶
func ExtractSingleBoolCommentTag(marker string, key string, defaultVal bool, lines []string) (bool, error)
ExtractSingleBoolCommentTag parses comments for lines of the form:
'marker' + "key=value1"
If the tag is not found, the default value is returned. Values are asserted to be boolean ("true" or "false"), and any other value will cause an error to be returned. If the key has multiple values, the first one will be used.
func GoBoilerplate ¶
GoBoilerplate returns the Go file header: - an optional build tag (negative, set it to ignore generated code) - an optional boilerplate file - an optional "generated by" comment
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
kilroy
kilroy is a trivial gengo/v2 program which adds a tag-method to types.
|
kilroy is a trivial gengo/v2 program which adds a tag-method to types. |
|
pointuh
pointuh is a trivial gengo/v2 program which consider its inputs, and emits to new packages the same types, except for structs, where all fields are pointers.
|
pointuh is a trivial gengo/v2 program which consider its inputs, and emits to new packages the same types, except for structs, where all fields are pointers. |
|
tracer
tracer is a trivial gengo/v2 program which prints the various hooks as they are called.
|
tracer is a trivial gengo/v2 program which prints the various hooks as they are called. |
|
Package generator defines an interface for code generators to implement.
|
Package generator defines an interface for code generators to implement. |
|
Package namer has support for making different type naming systems.
|
Package namer has support for making different type naming systems. |
|
Package parser provides code to parse go files, type-check them, extract the types.
|
Package parser provides code to parse go files, type-check them, extract the types. |
|
Package types contains go type information, packaged in a way that makes auto-generation convenient, whether by template or straight go functions.
|
Package types contains go type information, packaged in a way that makes auto-generation convenient, whether by template or straight go functions. |