Merge pull request #16493 from cpuguy83/doc_plugin_rpcgen

Add README for pluginrpc-gen

plugins/pluginrpc-gen/README.md

@@ -0,0 +1,68 @@
+Plugin RPC Generator
+====================
+
+Generates go code from a Go interface definition for proxying between the plugin
+API and the subsystem being extended.
+
+## Usage
+
+Given an interface definition:
+
+```go
+type volumeDriver interface {
+	Create(name string, opts opts) (err error)
+	Remove(name string) (err error)
+	Path(name string) (mountpoint string, err error)
+	Mount(name string) (mountpoint string, err error)
+	Unmount(name string) (err error)
+}
+```
+
+**Note**: All function options and return values must be named in the definition.
+
+Run the generator:
+
+```bash
+$ pluginrpc-gen --type volumeDriver --name VolumeDriver -i volumes/drivers/extpoint.go -o volumes/drivers/proxy.go
+```
+
+Where:
+- `--type` is the name of the interface to use
+- `--name` is the subsystem that the plugin "Implements"
+- `-i` is the input file containing the interface definition
+- `-o` is the output file where the the generated code should go
+
+**Note**: The generated code will use the same package name as the one defined in the input file
+
+Optionally, you can skip functions on the interface that should not be
+implemented in the generated proxy code by passing in the function name to `--skip`.
+This flag can be specified multiple times.
+
+You can also add build tags that should be prepended to the generated code by
+supplying `--tag`. This flag can be specified multiple times.
+
+## Known issues
+
+The parser can currently only handle types which are not specifically a map or
+a slice.  
+You can, however, create a type that uses a map or a slice internally, for instance:
+
+```go
+type opts map[string]string
+```
+
+This `opts` type will work, whreas using a `map[string]string` directly will not.
+
+## go-generate
+
+You can also use this with go-generate, which is pretty awesome.  
+To do so, place the code at the top of the file which contains the interface
+definition (i.e., the input file):
+
+```go
+//go:generate pluginrpc-gen -i $GOFILE -o proxy.go -type volumeDriver -name VolumeDriver
+```
+
+Then cd to the package dir and run `go generate`
+
+**Note**: the `pluginrpc-gen` binary must be within your `$PATH`