From e4230560a0fca53c2b96b9b76f002f5d27cee40d Mon Sep 17 00:00:00 2001 From: Morgan Bauer Date: Wed, 28 Jun 2017 15:03:43 -0700 Subject: Create code-generation subsection - move protobufs and codecgen into new subsection - subsection details on code generation in the build - details on lister-gen code generator --- contributors/devel/api_changes.md | 40 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/contributors/devel/api_changes.md b/contributors/devel/api_changes.md index 63aa0fae..cc626a6d 100755 --- a/contributors/devel/api_changes.md +++ b/contributors/devel/api_changes.md @@ -462,8 +462,26 @@ generator to create it from scratch. Unsurprisingly, adding manually written conversion also requires you to add tests to `pkg/api//conversion_test.go`. +## Generate Code -## Generate protobuf objects +When any `types.go` change is made, the generated code must be updated +by running the generators. There are many small generators that +run. They have some dependencies on each other so they must be run in +a certain order. + +Approximately: + - `defaulter-gen` + - `deepcopy-gen` + - `conversion-gen` + - `client-gen` + - `lister-gen` which depends upon the output of `client-gen`. + - `informer-gen` which depends upon the output of `lister-gen` and `client-gen`. + - `codecgen` for fast json serialization with a codec. + +Many of the generators are based on +[`gengo`](https://github.com/kubernetes/gengo) and share common flags. + +### Generate protobuf objects For any core API object, we also need to generate the Protobuf IDL and marshallers. That generation is done with @@ -479,7 +497,25 @@ use our own equivalents for JSON serialization. The `pkg/api/serialization_test. will verify that your protobuf serialization preserves all fields - be sure to run it several times to ensure there are no incompletely calculated fields. -## Edit json (un)marshaling code +### Generate Clientset + +See [this document](generating-clientset.md) specific to generating client sets. + +### Generate Listers + +`lister-gen` is a tool to generate listers for a client. It requires a +client generated by `client-gen`. + +`lister-gen` requires the `// +genclient=true` annotation on each +exported type in both the unversioned base `types.go` as well as each +specifically versioned `types.go`. + +`lister-gen` requires the `// +groupName=` annotation on the `doc.go` in +both the unversioned base directory as well as in each specifically +versioned directory. The annotation does not have to have any specific +content, but it does have to exist. + +### Edit json (un)marshaling code We are auto-generating code for marshaling and unmarshaling json representation of api objects - this is to improve the overall system performance. -- cgit v1.2.3 From beed052f1afdcf836a3f1f1c160960fc172ae579 Mon Sep 17 00:00:00 2001 From: Morgan Bauer Date: Thu, 29 Jun 2017 11:42:27 -0700 Subject: more generator informatin - openapi-gen as part of the build - some gengo flags - informer-gen --- contributors/devel/api_changes.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/contributors/devel/api_changes.md b/contributors/devel/api_changes.md index cc626a6d..17b41a18 100755 --- a/contributors/devel/api_changes.md +++ b/contributors/devel/api_changes.md @@ -476,10 +476,21 @@ Approximately: - `client-gen` - `lister-gen` which depends upon the output of `client-gen`. - `informer-gen` which depends upon the output of `lister-gen` and `client-gen`. + - `openapi-gen` - `codecgen` for fast json serialization with a codec. + Many of the generators are based on -[`gengo`](https://github.com/kubernetes/gengo) and share common flags. +[`gengo`](https://github.com/kubernetes/gengo) and share common +flags. The `--verify-only` flag will check the existing files on disk +and fail if they are not what would have been generated. + +The generators that create go code have a `--go-header-file` flag +which should be a file that contains the header that should be +included. This header is the copyright that should be present at the +top of the generated file and should be checked with the +[`repo-infra/verify/verify-boilerplane.sh`](https://github.com/kubernetes/repo-infra/blob/master/verify/verify-boilerplate.sh) +script at a later stage of the build. ### Generate protobuf objects @@ -515,6 +526,11 @@ both the unversioned base directory as well as in each specifically versioned directory. The annotation does not have to have any specific content, but it does have to exist. +### Generate Informers + +`informer-gen` generates the very useful Informers which watch API +resources for changes. It requires a client generated by `client-gen`. + ### Edit json (un)marshaling code We are auto-generating code for marshaling and unmarshaling json representation -- cgit v1.2.3