TL;DR: See end-to-end example in go-bind-plugin-example.
go-bind-plugin is go:generate tool for building golang 1.8 plugins and generating wrappers around exported symbols (functions and variables).
go-bind-plugin generates neat API around symbols exported by a *.so plugin built with go build -buildmode=plugin in upcoming go 1.8. plugin.Plugin holds information about exported symbols as map[string]interface{}.
go-bind-plugins uses reflection to find out actual types of symbols and generates typed API wrapping plugin with additional functionalities (like dereferencing exported variables and checking SHA256 sum).
Note: Basic usage does not require plugin sources as wrapper can be generated using only *.so file.
In example if plugin exports func AddTwoInts(a, b int) int and var BuildVersion string instead of using Plugin.Lookup directly:
plug, err := plugin.Open("plugin.so")
if err != nil {
panic(err)
}
symbol, err := plug.Lookup("AddTwoInts")
if err != nil {
panic("AddTwoInts was not found in a plugin")
}
if typed, ok := symbol.(func(int, int) int); ok {
result := typed(10, 20)
} else {
panic("AddTwoInts has different type than exported by plugin")
}
symbol, err := plug.Lookup("BuildVersion")
if err != nil {
panic("BuildVersion was not found in a plugin")
}
if typed, ok := symbol.(*string); ok {
fmt.Println(*typed)
} else {
panic("BuildVersion is not a string reference")
}you can just simply do:
plug, err := pluginapi.BindPluginAPI("plugin.so") // plug is *plugin_api.PluginAPI
if err != nil {
panic(err)
}
result := plug.AddTwoInts(10, 20)
fmt.Println(plug.BuildVersion) // or fmt.Println(*plug.BuildVersion) if -dereference-vars is not usedpluginapi.BindPluginAPI() ensures that plugin exports required symbols and their types are correct.
go get -u github.com/wendigo/go-bind-plugin
go-bind-plugin -help
Usage of go-bind-plugin:
-dereference-vars
Dereference plugin variables
-format
Format generated output file with gofmt (default true)
-hide-vars
Do not export plugin variables
-interface
Generate and return interface instead of struct (turns on -hide-vars)
-output-name string
Output struct name (default "PluginAPI")
-output-package string
Output package (can be derived from output-path) (default "main")
-output-path string
Output file path (default "plugin_api.go")
-plugin-package string
Plugin package url (as accepted by go get)
-plugin-path string
Path to plugin (.so file)
-rebuild
Rebuild plugin on every run
-sha256
Write plugin's sha256 checksum to wrapper and validate it when loading it//go:generate go-bind-plugin -format -plugin-package github.com/plugin_test/plug -rebuild -sha256 -dereference-vars -output-name TestPlugin -output-path tmp/plugin.go -plugin-path tmp/plugin.so -output-package pluginapi
go-bind-plugin will do following things on invocation:
- build plugin to
tmp/plugin.so(even if plugin exists it will be rebuilded) fromgithub.com/plugin_test/plugsource (must exist in $GOPATH or vendor/) - generate wrapper struct
wrapper.TestPluginintmp/plugin.go - dereference variables in the generated wrapper
- format generated wrapper with
gofmt -s -w - write sha256 checksum to
tmp/plugin.gothat will be checked when loading plugin withpluginapi.BindTestPlugin(path string) (*TestPlugin, error)
BindPluginAPI(path string) (*PluginAPI, error) - loads plugin from path and wraps it with type PluginAPI struct:
- all functions exported by the plugin are exposed as methods on struct
PluginAPI - all variables exported by the plugin are exposed as fields on struct
PluginAPI(if-dereference-varsis used fields are not references to plugin's variables)
func (*PluginAPI) String() string - provides nice textual representation of the wrapper
When -interface is used instead of generating and returning struct interface containing all exported symbols is generated. This eases mocking and working with multiple plugins exporting the same API.
Note that -interface effectively enables -hide-vars so variables won't be exported from the plugin.
Generated code passes both go vet and golint and can be formatted using gofmt -s -w. Exported symbols names are not changed in any way so names not following go naming convention will still be reported by golint as invalid.
Wrapper info:
- Generated on: 2016-11-08 16:15:07.513150982 +0100 CET
- Command: go-bind-plugin -plugin-path ./internal/test_fixtures/generated/basic_plugin/plugin.so -plugin-package ./internal/test_fixtures/basic_plugin -output-name TestWrapper -output-path ./internal/test_fixtures/generated/basic_plugin/plugin.go -output-package main -sha256 true -format true -rebuild true
Plugin info:
- package: github.com/wendigo/go-bind-plugin/internal/test_fixtures/basic_plugin
- sha256 sum: 55aa13402686f3200f5067604c04ce8d365e7cf2095d8278b2ff52ae26df7e6d
- size: 1232572 bytes
Exported functions (3):
- ReturningInt32 func() (int32)
- ReturningStringSlice func() ([]string)
- ReturningIntArray func() ([3]int32)Using -buildmode=plugin with generated wrapper seems not to add overhead when calling methods on a wrapper (creating plugin instance and loading *.so file is constant cost).
BenchmarkCallOverhead/plugin-8 30000000 58.0 ns/op 0 B/op 0 allocs/op
BenchmarkCallOverhead/plugin-8 30000000 59.3 ns/op 0 B/op 0 allocs/op
BenchmarkCallOverhead/plugin-8 30000000 54.8 ns/op 0 B/op 0 allocs/op
BenchmarkCallOverhead/native-8 20000000 59.3 ns/op 0 B/op 0 allocs/op
BenchmarkCallOverhead/native-8 20000000 59.8 ns/op 0 B/op 0 allocs/op
BenchmarkCallOverhead/native-8 20000000 59.7 ns/op 0 B/op 0 allocs/op