gengo

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.

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

func ExtractCommentTags(marker string, lines []string) map[string][]string

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

func GoBoilerplate(headerFile, buildTag, generatedBy string) ([]byte, error)

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