diff --git a/docs/plugins/debugging.md b/docs/plugins/debugging.md index 1da3464b0e1..5df2e9b0ccf 100644 --- a/docs/plugins/debugging.md +++ b/docs/plugins/debugging.md @@ -8,7 +8,7 @@ The [plugin package - Warnings](https://pkg.go.dev/plugin#hdr-Warnings) section > Runtime crashes are likely to occur unless all parts of the program (the application and all its plugins) are compiled using exactly the same version of the toolchain, the same build tags, and the same values of certain flags and environment variables. -We provide a [Plugin Compiler](#) docker image, which should be used to build plugins compatible with the official gateway releases and their architectures. It provides the cross compilation toolchain, Go version used to build the release, and ensure compatible flags are used when compiling plugins, like `-trimpath`, `CC`, `CGO_ENABLED`, `GOOS`, `GOARCH`. +We provide a Plugin Compiler docker image, which should be used to build plugins compatible with the official gateway releases and their architectures. It provides the cross compilation toolchain, Go version used to build the release, and ensure compatible flags are used when compiling plugins, like `-trimpath`, `CC`, `CGO_ENABLED`, `GOOS`, `GOARCH`. The plugin compiler also works around known Go issues. @@ -17,6 +17,8 @@ The plugin compiler also works around known Go issues. The argument plugin_id ensures the same plugin can be rebuilt. The plugin compiler does this by replacing the plugin go.mod module path. +Continue with [Go Plugin Compiler](https://tyk.io/docs/product-stack/tyk-gateway/advanced-configurations/plugins/golang/go-plugin-compiler/). + ### Examples When working with Go plugins, it's easy to miss the restriction that the plugin at the very least requires to be built with the same Go version, and the same flags, notably `-trimpath`, which is part of the Gateway official release. diff --git a/docs/plugins/development.md b/docs/plugins/development.md index dbef0259d09..29bd566dbdf 100644 --- a/docs/plugins/development.md +++ b/docs/plugins/development.md @@ -5,8 +5,6 @@ For effectively developing go plugins, absorb the following: - [The official plugin package documentation - Warnings](https://pkg.go.dev/plugin) - [Tutorial: Getting started with multi-module workspaces](https://go.dev/doc/tutorial/workspaces) - - ## Setting up your environment To develop plugins, you'll need: @@ -15,12 +13,16 @@ To develop plugins, you'll need: - Git to check out gateway source code - A folder with plugins to build -Set up a workspace, which is going to look like: +Set up a workspace, which, at the end, is going to look like: -- `/tyk` - the checkout +- `/tyk-release-5.3.6` - the checkout - `/plugins` - the plugins +- `/go.work` - the go workspace file +- `/go.work.sum` - workspace package checksums + +Using the workspace ensures build compatibility, matching plugin restrictions. -A sample [Taskfile.yml](Taskfile.yml) is provided here. +A sample [tests/Taskfile.yml](Taskfile.yml) is provided here to automatically set up, build, and load the plugin with gateway. ``` task: Available tasks for this project: @@ -48,7 +50,7 @@ The plugin workspace can be very simple. Generally you would: 1. create a .go file with code for your plugin 2. create a go.mod for the plugin 3. ensure the correct go version is in use -4. use the exact commit hash from the plugin +4. add gateway dependency with `go get`, using the commit hash For implementation examples, see [CustomGoPlugin.go](https://github.com/TykTechnologies/custom-go-plugin/blob/master/go/src/CustomGoPlugin.go). We'll be using this as the source for our plugin as shown: @@ -66,6 +68,8 @@ The following snippets provide you with a way to: - `go mod edit -json go.mod | jq -r .Go` - get the go version from the gateway go.mod file - `git rev-parse HEAD` - get the commit hash so the exact commit can be used with `go get` +This should be used to ensure the matching between gateway and the plugin. The commit is used to `go get` the dependency in later steps. + The internal `workspace:plugins` step ensures a few things: 1. create a plugin, create go.mod,