From 7beeee35f1be229c25b154ecf816a5bb09157778 Mon Sep 17 00:00:00 2001 From: Steve Manuel Date: Tue, 19 Nov 2024 22:48:00 -0800 Subject: [PATCH] feat: add overview on generating bindings (#789) Primarily adds the Generating Bindings section, but also updates the PDK and SDK list to include more languages. --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++---- example-schema.yaml | 28 ++++++++++++++++++ 2 files changed, 94 insertions(+), 6 deletions(-) create mode 100644 example-schema.yaml diff --git a/README.md b/README.md index 7c41e96..b7ac763 100644 --- a/README.md +++ b/README.md @@ -61,11 +61,11 @@ started: # Compile WebAssembly to run in Extism Hosts -Extism Hosts (running the SDK) must execute WebAssembly code that has a [PDK, or Plug-in Development Kit](https://extism.org/docs/concepts/pdk), -library compiled in to the `.wasm` binary. PDKs make it easy for plug-in / -extension code authors to read input from the host and return data back, read -provided configuration, set/get variables, make outbound HTTP calls if allowed, -and more. +Extism Hosts (running the SDK) must execute WebAssembly code that has a +[PDK, or Plug-in Development Kit](https://extism.org/docs/concepts/pdk), library +compiled in to the `.wasm` binary. PDKs make it easy for plug-in / extension +code authors to read input from the host and return data back, read provided +configuration, set/get variables, make outbound HTTP calls if allowed, and more. Pick a PDK to import into your Wasm program, and refer to the documentation to get started: @@ -74,13 +74,73 @@ get started: | ------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- | | Rust PDK | Rust PDK | https://github.com/extism/rust-pdk | [Crates.io](https://crates.io/crates/extism-pdk) | | JS PDK | JS PDK | https://github.com/extism/js-pdk | N/A | +| Python PDK | Python PDK | https://github.com/extism/python-pdk | N/A | | Go PDK | Go PDK | https://github.com/extism/go-pdk | [Go mod](https://pkg.go.dev/github.com/extism/go-pdk) | | Haskell PDK | Haskell PDK | https://github.com/extism/haskell-pdk | [Hackage](https://hackage.haskell.org/package/extism-pdk) | | AssemblyScript PDK | AssemblyScript PDK | https://github.com/extism/assemblyscript-pdk | [NPM](https://www.npmjs.com/package/@extism/as-pdk) | -| .NET PDK | .NET PDK | https://github.com/extism/dotnet-pdk
(supports C# & F#!) | https://www.nuget.org/packages/Extism.Pdk | +| .NET PDK | .NET PDK | https://github.com/extism/dotnet-pdk
(supports C# & F#!) | [Nuget](https://www.nuget.org/packages/Extism.Pdk) | | C PDK | C PDK | https://github.com/extism/c-pdk | N/A | +| C++ PDK | C++ PDK | https://github.com/extism/cpp-pdk | N/A | | Zig PDK | Zig PDK | https://github.com/extism/zig-pdk | N/A | +# Generating Bindings + +It's often very useful to define a schema to describe the function signatures +and types you want to use between Extism SDK and PDK languages. + +[XTP Bindgen](https://github.com/dylibso/xtp-bindgen) is an open source +framework to generate PDK bindings for Extism plug-ins. It's used by the +[XTP Platform](https://www.getxtp.com/), but can be used outside of the platform +to define any Extism compatible plug-in system. + +## 1. Install the `xtp` CLI. + +See installation instructions +[here](https://docs.xtp.dylibso.com/docs/cli#installation). + +## 2. Create a schema using our OpenAPI-inspired IDL: + +```yaml +version: v1-draft +exports: + CountVowels: + input: + type: string + contentType: text/plain; charset=utf-8 + output: + $ref: "#/components/schemas/VowelReport" + contentType: application/json +# components.schemas defined in example-schema.yaml... +``` + +> See an example in [example-schema.yaml](./example-schema.yaml), or a full +> "kitchen sink" example on +> [the docs page](https://docs.xtp.dylibso.com/docs/concepts/xtp-schema/). + +## 3. Generate bindings to use from your plugins: + +``` +xtp plugin init --schema-file ./example-schema.yaml + > 1. TypeScript + 2. Go + 3. Rust + 4. Python + 5. C# + 6. Zig + 7. C++ + 8. GitHub Template + 9. Local Template +``` + +This will create an entire boilerplate plugin project for you to get started +with. Implement the empty function(s), and run `xtp plugin build` to compile +your plugin. + +> For more information about XTP Bindgen, see the +> [dylibso/xtp-bindgen](https://github.com/dylibso/xtp-bindgen) repository and +> the official +> [XTP Schema documentation](https://docs.xtp.dylibso.com/docs/concepts/xtp-schema). + # Support ## Discord diff --git a/example-schema.yaml b/example-schema.yaml new file mode 100644 index 0000000..f921e5f --- /dev/null +++ b/example-schema.yaml @@ -0,0 +1,28 @@ +# yaml-language-server: $schema=https://xtp.dylibso.com/assets/wasm/schema.json +# Learn more at https://docs.xtp.dylibso.com/docs/concepts/xtp-schema +version: v1-draft +exports: + CountVowels: + input: + type: string + contentType: text/plain; charset=utf-8 + output: + $ref: "#/components/schemas/VowelReport" + contentType: application/json +components: + schemas: + VowelReport: + description: The result of counting vowels on the Vowels input. + properties: + count: + type: integer + format: int32 + description: The count of vowels for input string. + total: + type: integer + format: int32 + description: The cumulative amount of vowels counted, if this keeps state across multiple function calls. + nullable: true + vowels: + type: string + description: The set of vowels used to get the count, e.g. "aAeEiIoOuU" \ No newline at end of file