Skip to content

Latest commit

 

History

History
136 lines (108 loc) · 4.64 KB

README.md

File metadata and controls

136 lines (108 loc) · 4.64 KB
Raw

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

1. Install the xtp CLI.

See installation instructions here.

2. Create a schema using our OpenAPI-inspired IDL:

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

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.

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.