xtp-bindgen

XTP Bindgen is an open source framework to generate PDK bindings for
Extism plug-ins. It's used by the
XTP Platform, but can be used outside of the platform
to define any Extism compatible plug-in system.

> Note: This repository hosts the core schema parser and validation code, and is
> not meant for typical day-to-day use. Instead, you should use the
> xtp CLI) to generate
> bindings from an
> XTP Schema.

Quickstart

$3

See installation instructions
here.

$3

``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, or a full
> "kitchen sink" example on
> the docs page.

$3

`
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.

How Does It Work?

Extism has a very simple bytes-in / bytes-out interface.
The host and the guest must agree on the interface used (exports functions,
imports functions, and types). The purpose of this project is to create a
canonical document and set of tools for defining this interface and generating
bindings. That document is the
XTP Schema. This is an
IDL of our creation. It is similar to OpenAPI, but
is focused on defining plug-in interfaces, not HTTP interfaces.

Once you define your interface as a schema, you can use one of the bindgens to
generate code. We have some official bindgens available for writing PDKs, but
more will be availble soon for a variety of purposes. There may also be
community bindgens you can use.

- TypeScript
- Go
- Python
- Rust
- C#
- Zig
- C++

How Do I Use A Bindgen?

You can use the XTP CLI to generate
plug-ins.

> _Note_: You don't need to authenticate to XTP to use the plugin generator

Use the plugin init command to generate a plugin:

`
xtp plugin init \
--schema myschema.yaml \
--template @dylibso/xtp-typescript-bindgen \
--path ./myplugin \
--feature none
`

You can point to a bindgen template on github or directly to a bindgen bundle.

How Do I Write A Bindgen?

> We recommended that you use any of the existing bindgens as a starting point
> for writing your own bindgen.

A bindgen is simply a zip file with the following attributes:

- plugin.wasm an extism plugin to generate the code
- config.yaml a config file for the generator
- template a template folder of files and templates that the generator will
recursively process

For reference, Here is what is inside the typescript bindgen:

`
$ tree bundle
bundle
├── config.yaml
├── plugin.wasm
└── template
├── esbuild.js
├── package.json.ejs
├── src
│   ├── index.d.ts.ejs
│   ├── index.ts.ejs
│   ├── main.ts.ejs
│   └── pdk.ts.ejs
├── tsconfig.json
└── xtp.toml.ejs
``

The XTP CLI will download and unpack this template, it will load the plugin, and
it will recursively walk through the template and pass each file through the
plugin to be rendered. Our official bindgens currently use typescript and EJS to
render the projects, but these are not mandatory. It can be any Extism plug-in.