Browse code
Add README for pluginrpc-gen
Signed-off-by: Brian Goff <cpuguy83@gmail.com>
Brian Goff authored on 2015/09/23 04:50:48Showing 2 changed files
| 1 | 1 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,68 @@ |
| 0 |
+Plugin RPC Generator |
|
| 1 |
+==================== |
|
| 2 |
+ |
|
| 3 |
+Generates go code from a Go interface definition for proxying between the plugin |
|
| 4 |
+API and the subsystem being extended. |
|
| 5 |
+ |
|
| 6 |
+## Usage |
|
| 7 |
+ |
|
| 8 |
+Given an interface definition: |
|
| 9 |
+ |
|
| 10 |
+```go |
|
| 11 |
+type volumeDriver interface {
|
|
| 12 |
+ Create(name string, opts opts) (err error) |
|
| 13 |
+ Remove(name string) (err error) |
|
| 14 |
+ Path(name string) (mountpoint string, err error) |
|
| 15 |
+ Mount(name string) (mountpoint string, err error) |
|
| 16 |
+ Unmount(name string) (err error) |
|
| 17 |
+} |
|
| 18 |
+``` |
|
| 19 |
+ |
|
| 20 |
+**Note**: All function options and return values must be named in the definition. |
|
| 21 |
+ |
|
| 22 |
+Run the generator: |
|
| 23 |
+ |
|
| 24 |
+```bash |
|
| 25 |
+$ pluginrpc-gen --type volumeDriver --name VolumeDriver -i volumes/drivers/extpoint.go -o volumes/drivers/proxy.go |
|
| 26 |
+``` |
|
| 27 |
+ |
|
| 28 |
+Where: |
|
| 29 |
+- `--type` is the name of the interface to use |
|
| 30 |
+- `--name` is the subsystem that the plugin "Implements" |
|
| 31 |
+- `-i` is the input file containing the interface definition |
|
| 32 |
+- `-o` is the output file where the the generated code should go |
|
| 33 |
+ |
|
| 34 |
+**Note**: The generated code will use the same package name as the one defined in the input file |
|
| 35 |
+ |
|
| 36 |
+Optionally, you can skip functions on the interface that should not be |
|
| 37 |
+implemented in the generated proxy code by passing in the function name to `--skip`. |
|
| 38 |
+This flag can be specified multiple times. |
|
| 39 |
+ |
|
| 40 |
+You can also add build tags that should be prepended to the generated code by |
|
| 41 |
+supplying `--tag`. This flag can be specified multiple times. |
|
| 42 |
+ |
|
| 43 |
+## Known issues |
|
| 44 |
+ |
|
| 45 |
+The parser can currently only handle types which are not specifically a map or |
|
| 46 |
+a slice. |
|
| 47 |
+You can, however, create a type that uses a map or a slice internally, for instance: |
|
| 48 |
+ |
|
| 49 |
+```go |
|
| 50 |
+type opts map[string]string |
|
| 51 |
+``` |
|
| 52 |
+ |
|
| 53 |
+This `opts` type will work, whreas using a `map[string]string` directly will not. |
|
| 54 |
+ |
|
| 55 |
+## go-generate |
|
| 56 |
+ |
|
| 57 |
+You can also use this with go-generate, which is pretty awesome. |
|
| 58 |
+To do so, place the code at the top of the file which contains the interface |
|
| 59 |
+definition (i.e., the input file): |
|
| 60 |
+ |
|
| 61 |
+```go |
|
| 62 |
+//go:generate pluginrpc-gen -i $GOFILE -o proxy.go -type volumeDriver -name VolumeDriver |
|
| 63 |
+``` |
|
| 64 |
+ |
|
| 65 |
+Then cd to the package dir and run `go generate` |
|
| 66 |
+ |
|
| 67 |
+**Note**: the `pluginrpc-gen` binary must be within your `$PATH` |