-
Notifications
You must be signed in to change notification settings - Fork 18.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #16493 from cpuguy83/doc_plugin_rpcgen
Add README for pluginrpc-gen
- Loading branch information
Showing
2 changed files
with
69 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters