Extism

https://extism.org/docs
Admin
Extism is a universal plug-in system that enables users to add custom logic to applications across...
Tokens:20,567
Snippets:288
Trust Score:8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Go Dependency

Source: https://extism.org/docs/quickstart/host-quickstart

Install the Extism Go SDK using go get.

```bash
go get github.com/extism/go-sdk
```

--------------------------------

### Install C# Packages

Source: https://extism.org/docs/quickstart/host-quickstart

Installs the required native runtime and SDK NuGet packages.

```bash
dotnet add package Extism.runtime.all  
```

```bash
dotnet add package Extism.Sdk  
```

--------------------------------

### Install Extism Runtime

Source: https://extism.org/docs/quickstart/host-quickstart

Installs the required native Extism runtime using the CLI.

```bash
sudo extism lib install  
  
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz  
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib  
#=> Copying extism.h to /usr/local/include/extism.h  
```

--------------------------------

### Install Python Package

Source: https://extism.org/docs/quickstart/host-quickstart

Installs the Extism Python SDK using pip or poetry.

```bash
# using pip  
$ pip install extism  
  
# using poetry  
$ poetry add extism=^1.0.0  
```

--------------------------------

### Build and install the C++ SDK

Source: https://extism.org/docs/quickstart/host-quickstart

Standard CMake commands to configure, build, and install the library.

```bash
cmake -B build  
cmake --build build -j  
sudo cmake --install build
```

--------------------------------

### Install xtp CLI

Source: https://extism.org/docs/concepts/testing

Command to install the xtp test runner CLI on Unix-like systems.

```bash
curl https://static.dylibso.com/cli/install.sh | sudo sh  
```

--------------------------------

### Install Extism Runtime

Source: https://extism.org/docs/quickstart/host-quickstart

Use the Extism CLI to install the required shared object library.

```bash
sudo extism lib install  
  
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz  
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib  
#=> Copying extism.h to /usr/local/include/extism.h
```

--------------------------------

### Compile and run C example

Source: https://extism.org/docs/quickstart/host-quickstart

Commands to compile the C source and execute the resulting binary.

```bash
gcc -g -o example main.c -lextism  
./example  
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}  
```

--------------------------------

### Install PHP dependency

Source: https://extism.org/docs/quickstart/host-quickstart

Installs the Extism PHP library via Composer.

```bash
composer require extism/extism  
```

--------------------------------

### Install Extism CLI

Source: https://extism.org/docs/install

Use these commands to install the Extism CLI to the default location or a specific directory.

```bash
curl -s https://get.extism.org/cli | sh
```

```bash
curl -s https://get.extism.org/cli | sh -s -- -o $HOME/.local/bin
```

```bash
curl -s https://get.extism.org/cli | sh -s -- -h
```

--------------------------------

### Install WASI Workload

Source: https://extism.org/docs/quickstart/plugin-quickstart

Install the experimental WASI workload required for .NET plugin development.

```bash
dotnet workload install wasi-experimental  
```

--------------------------------

### Install JavaScript/TypeScript Dependencies

Source: https://extism.org/docs/quickstart/plugin-quickstart

Install the Extism JS compiler and generate a new plugin project.

```bash
curl -O https://raw.githubusercontent.com/extism/js-pdk/main/install.sh  
sh install.sh
```

```bash
extism-js  
error: The following required arguments were not provided:  
    <input-js>  
  
USAGE:  
    extism-js <input-js> -i <interface-file> -o <output>  
  
For more information try --help
```

```bash
extism gen plugin -l JavaScript -o plugin  
cd plugin  
npm install
```

```bash
extism gen plugin -l TypeScript -o plugin  
cd plugin  
npm install
```

--------------------------------

### Install dependencies for Extism C++ SDK

Source: https://extism.org/docs/quickstart/host-quickstart

Commands to install cmake and jsoncpp on Debian and macOS systems.

```bash
# on Debian  
sudo apt install cmake jsoncpp  
  
# on macOS  
brew install cmake jsoncpp
```

--------------------------------

### Install Extism in Containers

Source: https://extism.org/docs/install

Commands for installing the Extism runtime within Docker build stages.

```dockerfile
RUN curl -s https://get.extism.org/cli | sh -s -- -y
RUN extism lib install
ENV LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
```

```dockerfile
ENV LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
COPY --from=build /usr/local/include/extism.h /usr/local/include/extism.h
COPY --from=build /usr/local/lib/libextism.so /usr/local/lib/libextism.so
COPY --from=build /usr/local/lib/libextism.a /usr/local/lib/libextism.a
COPY --from=build /usr/local/lib/pkgconfig/extism.pc /usr/local/lib/pkgconfig/extism.pc
COPY --from=build /usr/local/lib/pkgconfig/extism-static.pc /usr/local/lib/pkgconfig/extism-static.pc
```

--------------------------------

### Install Ruby Gem

Source: https://extism.org/docs/quickstart/host-quickstart

Adds the Extism gem to a project via Gemfile or direct installation.

```ruby
gem 'extism', '~> 1.0'  
```

```bash
gem install extism  
```

--------------------------------

### Install Rust Dependency

Source: https://extism.org/docs/quickstart/host-quickstart

Add the Extism crate to your Cargo.toml file.

```toml
[dependencies]
extism = "1.0.0"
```

--------------------------------

### Example test output

Source: https://extism.org/docs/concepts/testing

Displays the expected console output after running the plugin tests.

```text
🧪 Testing plugin.wasm  
  
PASS ...... initial call to 'run' returns the correct value  
  
1/1 tests passed (completed in 17µs)  
  
📦 Group: multiple kv read/write calls produce correct state  
  
PASS ...... repeat call to 'run' returns the correct value: value  
PASS ...... repeat call to 'run' returns the correct value: valuevalue  
PASS ...... repeat call to 'run' returns the correct value: valuevaluevalue  
PASS ...... repeat call to 'run' returns the correct value: valuevaluevaluevalue  
PASS ...... repeat call to 'run' returns the correct value: valuevaluevaluevaluevalue  
PASS ...... repeat call to 'run' returns the correct value: valuevaluevaluevaluevaluevalue  
PASS ...... repeat call to 'run' returns the correct value: valuevaluevaluevaluevaluevaluevalue  
PASS ...... repeat call to 'run' returns the correct value: valuevaluevaluevaluevaluevaluevaluevalue  
PASS ...... repeat call to 'run' returns the correct value: valuevaluevaluevaluevaluevaluevaluevaluevalue  
PASS ...... repeat call to 'run' returns the correct value: valuevaluevaluevaluevaluevaluevaluevaluevaluevalue  
  
10/10 tests passed (completed in 845µs)  
  
all tests completed in 862µs
```

--------------------------------

### Manifest Schema Structure

Source: https://extism.org/docs/concepts/manifest

Provides a comprehensive example of the manifest structure, including WASM loading methods, memory limits, allowed hosts, and filesystem mappings.

```python
{
    # The "wasm" key describes the wasm code needed to build the plugin.  
    # There are a few ways to load wasm code:  
    "wasm": [  
        # you can point to a file:  
        {  
            # a file path for a plugin on disk  
            "path": "./code/myplugin.wasm",  
            # an optional name  
            "name": "main",  
            # the optional sha256 hash in hex form (it's optional, but recommended)  
            "hash": "15c66d72f683e0225c774134b42ba6e04275a7a56b0a522af538d029650f15a8",  
        },  
        # or, you can pass raw binary data for the code already in memory:  
        {  
            # the base64-encoded raw bytes of the wasm module  
            "data": open("../wasm/code.wasm", 'rb').read(),  
            # an optional name  
            "name": "main",  
            # the optional sha256 hash in hex form (it's optional, but recommended)  
            "hash": "15c66d72f683e0225c774134b42ba6e04275a7a56b0a522af538d029650f15a8",  
        },  
        # or, you can load a remote resource with a URL:  
        {  
            # a URL to some wasm code  
            "url": "https://example.com/mycode.wasm",  
            # optional headers you may need to get the data, e.g. auth headers  
            "headers": {  
                "X-API-KEY": "34b42ba6e04275",  
                "User-Agent": "extism",  
            },  
            # optional HTTP method to use, (default: GET)  
            "method": "GET",  
            # an optional name  
            "name": "main",  
            # the optional sha256 hash in hex form (it's optional, but recommended)  
            "hash": "15c66d72f683e0225c774134b42ba6e04275a7a56b0a522af538d029650f15a8",  
        },  
    ]  
  
    # Describes the limits on the memory the plugin may be allocated.  
    "memory": {  
        # The max amount of pages the plugin can allocate  
        # One page is 64Kib. e.g. 16 pages would require 1MiB.  
        "max_pages": 4,  
  
        # The max size of an Extism HTTP response in bytes  
        "max_http_response_bytes": 4096,  
  
        # The max size of all Extism vars in bytes  
        "max_var_bytes": 4096  
    },  
  
    # An optional set of hosts this plugin can communicate with.  
    # This only has an effect if the plugin makes HTTP requests.  
    # Note: if left empty then no hosts are allowed and if `null` then all hosts are allowed.  
    "allowed_hosts": [  
        "example.com",  
        "extism.org",  
    ],  
  
    # An optional set of mappings between the host's filesystem and the paths a plugin can access.  
    # This only has an effect if the plugin is provided with WASI capabilities.   
    # Note: if left empty or `null`, then no file access is granted.  
    "allowed_paths": {  
        "/path/on/disk": "plugin/path",  
        "another/path": "/",  
    },  
  
    # The "config" key is a free-form map that can be passed to the plugin.  
    # A plugin author must know the arbitrary data this map may contain, so your own documentation should include some information about the "config" passed in.  
    "config": {  
        "mykey": "myvalue"  
    }  
}
```

--------------------------------

### Generate AssemblyScript Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Initialize and install dependencies for an AssemblyScript plugin.

```bash
extism gen plugin -l AssemblyScript -o plugin  
cd plugin  
npm install  
```

--------------------------------

### Install JavaScript Dependency

Source: https://extism.org/docs/quickstart/host-quickstart

Add the Extism package to your project using npm.

```bash
npm install @extism/extism --save
```

--------------------------------

### Install Elixir Dependency

Source: https://extism.org/docs/quickstart/host-quickstart

Add the Extism dependency to your mix.exs file.

```elixir
def deps do  
  [  
    {:extism, "1.0.0"}  
  ]  
end  
```

--------------------------------

### Execute Haskell Example

Source: https://extism.org/docs/quickstart/host-quickstart

Run the compiled Haskell executable using cabal.

```bash
cabal exec example
```

--------------------------------

### Get version

Source: https://extism.org/docs/concepts/runtime-apis

Returns the current Extism version string.

```c
const char *extism_version(void);
```

--------------------------------

### Check libextism version

Source: https://extism.org/docs/install

Retrieves the currently installed version of the libextism library.

```bash
extism lib check  
v0.5.0
```

--------------------------------

### Get output data

Source: https://extism.org/docs/concepts/runtime-apis

Retrieves the output data buffer from the plugin.

```c
const uint8_t *extism_plugin_output_data(ExtismPlugin *plugin);
```

--------------------------------

### Manage Extism Runtime Library

Source: https://extism.org/docs/install

Commands to install, update, or configure the location of the Extism shared library.

```bash
sudo extism lib install
```

```bash
sudo -E env "PATH=$PATH" extism lib install
```

```bash
sudo extism lib install --version git
```

```bash
extism lib install --prefix ~/.local
```

--------------------------------

### Get plugin error

Source: https://extism.org/docs/concepts/runtime-apis

Retrieves the error string associated with a plugin instance.

```c
const char *extism_plugin_error(ExtismPlugin *plugin);
```

--------------------------------

### Get host context

Source: https://extism.org/docs/concepts/runtime-apis

Retrieves the host context pointer passed during the plugin call.

```c
void *extism_current_plugin_host_context(ExtismCurrentPlugin *plugin);
```

--------------------------------

### Get memory block length

Source: https://extism.org/docs/concepts/runtime-apis

Retrieves the size of an allocated memory block.

```c
ExtismSize extism_current_plugin_memory_length(ExtismCurrentPlugin *plugin, ExtismSize n);  
```

--------------------------------

### Get plugin cancellation handle

Source: https://extism.org/docs/concepts/runtime-apis

Retrieves a handle used for cancelling a running plugin.

```c
const ExtismCancelHandle *extism_plugin_cancel_handle(const ExtismPlugin *plugin);  
```

--------------------------------

### Remove Legacy Extism CLI

Source: https://extism.org/docs/install

Remove previous versions of the CLI installed via Python.

```bash
pip3 uninstall extism_cli --break-system-packages
which extism # shouldn't print anything, if it does, delete it
```

--------------------------------

### Get output length

Source: https://extism.org/docs/concepts/runtime-apis

Returns the length of the data produced by the plugin's last execution.

```c
ExtismSize extism_plugin_output_length(ExtismPlugin *plugin);
```

--------------------------------

### Initialize a Plugin with a Manifest

Source: https://extism.org/docs/concepts/manifest

Demonstrates creating a plugin instance by providing a manifest dictionary containing WASM binary data and memory constraints.

```python
wasm = open("../wasm/code.wasm", 'rb').read()  
wasm_hash = hashlib.sha256(wasm).hexdigest()  
manifest = {  
    "wasm": [  
        {  
            "data": wasm,  
            "hash": wasm_hash  
        }  
    ],  
    "memory": {  
        "max_pages": 5  
    }  
}  
  
plugin = context.plugin(manifest)  
```

--------------------------------

### Get current plugin memory

Source: https://extism.org/docs/concepts/runtime-apis

Returns a pointer to the memory space of the currently executing plugin.

```c
uint8_t *extism_current_plugin_memory(ExtismCurrentPlugin *plugin);
```

--------------------------------

### Load Go Plugin

Source: https://extism.org/docs/quickstart/host-quickstart

Configure and initialize a plugin using the Extism Go SDK.

```go
package main

import (
    "context"
    "fmt"
    "github.com/extism/go-sdk"
    "os"
)

func main() {
    manifest := extism.Manifest{
        Wasm: []extism.Wasm{
            extism.WasmUrl{
                Url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm",
            },
        },
    }

    ctx := context.Background()
    config := extism.PluginConfig{}
    plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{})

    if err != nil {
        fmt.Printf("Failed to initialize plugin: %v\n", err)
        os.Exit(1)
    }
}
```

--------------------------------

### Build Extism with feature flags

Source: https://extism.org/docs/concepts/configuration

Instructions for cloning the repository and building the runtime with specific features enabled.

```bash
git clone git@github.com:extism/extism.git  
cd extism  
cargo build --release --features http,register-http,register-filesystem,nn  
  
# once complete, a libextism.so or libextism.dylib should be in the target/release/ directory.  
```

--------------------------------

### Generate Plugin PDK Starters

Source: https://extism.org/docs/install

Initialize a new plugin project using the CLI generator.

```bash
extism generate plugin -o new-plugin
Select a PDK language to use for your plugin:    
                                                  
> 1. Rust                                        
  2. JavaScript                                  
  3. Go                                          
  4. Zig                                         
  5. C#                                          
  6. F#                                          
  7. C                                           
  8. Haskell                                     
  9. AssemblyScript
```

--------------------------------

### Run the C++ application

Source: https://extism.org/docs/quickstart/host-quickstart

Execute the compiled binary to see the plug-in output.

```bash
./build/getting-started  
{"count":3,"total":3,"vowels":"aeiouAEIOU"}
```

--------------------------------

### View CLI Help

Source: https://extism.org/docs/install

Display available commands and flags for the Extism CLI.

```bash
Usage:  
  extism [command]  
  
Available Commands:  
  call        Call a plugin function  
  completion  Generate the autocompletion script for the specified shell  
  help        Help about any command  
  lib         Manage libextism  
  
Flags:  
      --github-token string   Github access token, can also be set using the $GITHUB_TOKEN env variable  
  -h, --help                  help for extism  
  -q, --quiet                 Enable additional logging  
  -v, --verbose               Enable additional logging  
      --version               version for extism  
  
Use "extism [command] --help" for more information about a command.
```

--------------------------------

### Load a Plugin in C

Source: https://extism.org/docs/quickstart/host-quickstart

Initializes a plugin using a JSON manifest string.

```c
#include <extism.h>  
#include <stdio.h>  
#include <stdlib.h>  
#include <string.h>  
#include <unistd.h>  
  
int main(void) {  
  const char *manifest = "{\"wasm\": [{\"url\": "  
                         "\"https://github.com/extism/plugins/releases/latest/"  
                         "download/count_vowels.wasm\"}]}";  
  
  char *errmsg = NULL;  
  ExtismPlugin *plugin = extism_plugin_new(  
      (const uint8_t *)manifest, strlen(manifest), NULL, 0, true, &errmsg);  
  if (plugin == NULL) {  
    fprintf(stderr, "ERROR: %s\n", errmsg);  
    extism_plugin_new_error_free(errmsg);  
    exit(1);  
  }  
  
  // ...  
}  
```

--------------------------------

### Run .NET project

Source: https://extism.org/docs/quickstart/host-quickstart

Executes the .NET application and displays the expected JSON output.

```bash
dotnet run  
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}  
```

--------------------------------

### Run Go Program

Source: https://extism.org/docs/quickstart/host-quickstart

Execute the Go program to verify plugin output.

```bash
$ go run main.go
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
```

--------------------------------

### Load and Run Extism Plugin in PowerShell

Source: https://extism.org/docs/quickstart/host-quickstart

Demonstrates loading a WASM plugin, initializing it with WASI support, and executing a function. Ensure the Extism SDK assembly is loaded before execution.

```powershell
# First, load the Extism SDK assembly  
[System.String]$LibDir = $PSScriptRoot  
[System.String]$Extism = "$LibDir/Extism.Sdk.dll"  
Add-Type -Path $Extism  
  
function Run-ExtismVowelCount {  
    param (  
        [string]$InputText = "Hello, World!"  
    )  
  
    # Option 1: Load from URL (commented out but available)  
    $manifest = [Extism.Sdk.Manifest]::new(  
        [Extism.Sdk.UrlWasmSource]::new(  
            "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"  
        )  
    )  
  
    # Option 2: Load from a local file  
    # [System.String]$wasmFileName = "$PSScriptRoot/count_vowels.wasm"  
    # [System.Array]$wasmFileBytes = Get-Content -Path $wasmFileName -AsByteStream -Raw  
    # $wasmSource = [Extism.Sdk.ByteArrayWasmSource]::new($wasmFileBytes, "count_vowels.wasm")  
    # $manifest = [Extism.Sdk.Manifest]::new($wasmSource)  
      
    # Set up plugin initialization options  
    $options = [Extism.Sdk.PluginIntializationOptions]::new()  
    $options.WithWasi = $true  
      
    # Create empty host functions array (not needed for this example)  
    $hostFunctions = [Extism.Sdk.HostFunction[]]::new(0)  
      
    # Initialize the plugin  
    $plugin = [Extism.Sdk.Plugin]::new($manifest, $hostFunctions, $options)  
      
    try {  
        # Call the plugin function  
        $output = $plugin.Call("count_vowels", $InputText)  
        return $output  
    }  
    catch {  
        Write-Error "Failed to execute plugin: $_"  
    }  
    finally {  
        # Clean up resources  
        if ($plugin -ne $null) {  
            $plugin.Dispose()  
        }  
    }  
}  
  
# Call our function with a sample text  
$result = Run-ExtismVowelCount -InputText "Hello, World!"  
Write-Host $result  
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}  
  
# You can also parse the JSON output for programmatic use  
$vowelData = $result | ConvertFrom-Json  
Write-Host "Found $($vowelData.count) vowels in the text!"  
Write-Host "Total vowels counted so far: $($vowelData.total)"  
Write-Host "Characters considered vowels: $($vowelData.vowels)"  
  
# Try with different text  
$result2 = Run-ExtismVowelCount -InputText "The quick brown fox jumps over the lazy dog"  
$vowelData2 = $result2 | ConvertFrom-Json  
Write-Host "Found $($vowelData2.count) vowels in the second text!"  
# => Found 11 vowels in the second text!
```

--------------------------------

### Load a Plugin in Java

Source: https://extism.org/docs/quickstart/host-quickstart

Initializes a plugin using a URL-based manifest.

```java
import org.extism.sdk.manifest.Manifest;  
import org.extism.sdk.wasm.UrlWasmSource;  
import org.extism.sdk.Plugin;  
  
public static void main(String[] args) {  
    var url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm";  
    var manifest = new Manifest(List.of(UrlWasmSource.fromUrl(url)));  
    var plugin = new Plugin(manifest, false, null);  
}  
```

--------------------------------

### Load and Call Plugin in Python

Source: https://extism.org/docs/quickstart/host-quickstart

Initializes a plugin from a manifest and executes an exported function.

```python
import extism  
  
url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"  
manifest = {"wasm": [{"url": url}]}  
plugin = extism.Plugin(manifest)  
```

```python
wasm_vowel_count = plugin.call(  
    "count_vowels",  
    "hello world"  
)  
print(wasm_vowel_count)  
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}  
```

--------------------------------

### Initialize Extism Plugin in Zig

Source: https://extism.org/docs/quickstart/host-quickstart

Import the Extism library and initialize a plugin using a Wasm manifest URL.

```zig
// First require the library  
const extism = @import("extism");  
const std = @import("std");  
  
const wasm_url = extism.manifest.WasmUrl{ .url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm" };  
const manifest = .{ .wasm = &[_]extism.manifest.Wasm{.{ .wasm_url= wasm_url }} };  
  
var gpa = std.heap.GeneralPurposeAllocator(.{}){};  
defer std.debug.assert(gpa.deinit() == .ok);  
const allocator = gpa.allocator();  
  
var plugin = try extism.Plugin.initFromManifest(  
    allocator,  
    manifest,  
    &[_]extism.Function{},  
    false,    
);  
  
defer plugin.deinit();
```

--------------------------------

### Compile .NET Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Build the .NET project to generate the WASM binary.

```bash
dotnet build  
```

--------------------------------

### Load a plug-in in PHP

Source: https://extism.org/docs/quickstart/host-quickstart

Initializes a new Extism plugin using a URL-based WASM source.

```php
<?php  
use Extism\Plugin;  
use Extism\Manifest;  
use Extism\UrlWasmSource;  
  
require_once __DIR__ . '/vendor/autoload.php';  
  
$wasm = new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm");  
$manifest = new Manifest($wasm);  
  
$plugin = new Plugin($manifest, true);  
```

--------------------------------

### Implement a test plugin in Go

Source: https://extism.org/docs/concepts/testing

Uses the xtp-test-go library to define test cases that call plugin functions and assert expected outputs.

```go
package main  
  
import (  
    "fmt"  
    "strings"  
  
    // import the test harness library  
    xtptest "github.com/dylibso/xtp-test-go"  
)  
  
//go:export test  
func test() int32 {  
    // call the `run` function in the `kvplugin` project, & verify the output  
    output := xtptest.CallString("run", nil)  
    xtptest.AssertEq("initial call to 'run' returns the correct value", output, "value")  
  
    // call the `run` function in the `kvplugin` project 10 times, & verify the output each time  
    xtptest.Group("multiple kv read/write calls produce correct state", func() {  
        for i := 0; i < 10; i++ {  
            output := xtptest.CallString("run", nil)  
            expected := strings.Repeat("value", i+1)  
            msg := fmt.Sprintf("repeat call to 'run' returns the correct value: %s", expected)  
            xtptest.AssertEq(msg, output, expected)  
        }  
    })  
  
    return 0  
}  
  
func main() {}
```

--------------------------------

### Load and Call Plugin in Ruby

Source: https://extism.org/docs/quickstart/host-quickstart

Initializes a plugin from a URL and executes an exported function.

```ruby
require 'extism'  
  
url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"  
manifest = Extism::Manifest.from_url(url)  
plugin = Extism::Plugin.new(manifest)  
```

```ruby
plugin.call("count_vowels", "Hello, World!")  
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}  
```

--------------------------------

### Load a Plug-in in OCaml

Source: https://extism.org/docs/quickstart/host-quickstart

Initialize a plugin from a remote WASM URL using the Extism manifest.

```ocaml
open Extism  
  
let wasm = Manifest.Wasm.url "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"  
let manifest = Manifest.create [wasm]  
let plugin = Plugin.of_manifest_exn manifest  
```

--------------------------------

### Load an Extism plug-in

Source: https://extism.org/docs/quickstart/host-quickstart

Initialize a plugin instance using a manifest pointing to a remote WASM file.

```cpp
#include <extism.hpp>  
  
int main(void) {  
  const auto manifest =  
      extism::Manifest::wasmURL("https://github.com/extism/plugins/releases/"  
                                "latest/download/count_vowels.wasm");  
  extism::Plugin plugin(manifest, true);  
}
```

--------------------------------

### Generate Go Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Scaffold a new Go plugin project using the Extism CLI.

```bash
extism gen plugin -l Go -o plugin
```

--------------------------------

### Compile and Run JavaScript Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Build the JavaScript plugin and execute it with WASI support.

```bash
npm run build
```

```bash
extism call ./dist/plugin.wasm greet --input "Benjamin" --wasi  
# => Hello, Benjamin
```

--------------------------------

### Compile Go Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Build the Go plugin using the project's makefile.

```bash
make
```

--------------------------------

### Create host function

Source: https://extism.org/docs/concepts/runtime-apis

Initializes a new host function with specified inputs, outputs, and user data.

```c
ExtismFunction *extism_function_new(const char *name,  
                                    const ExtismValType *inputs,  
                                    ExtismSize n_inputs,  
                                    const ExtismValType *outputs,  
                                    ExtismSize n_outputs,  
                                    ExtismFunctionType func,  
                                    void *user_data,  
                                    void (*free_user_data)(void *_));  
```

--------------------------------

### Load Plugin in C#

Source: https://extism.org/docs/quickstart/host-quickstart

Initializes a plugin with a URL source and WASI support enabled.

```csharp
using System;  
  
using Extism.Sdk;  
  
var manifest = new Manifest(new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"));  
using var plugin = new Plugin(manifest, new HostFunction[] { }, withWasi: true);  
```

--------------------------------

### Load Extism Plugin in Haskell

Source: https://extism.org/docs/quickstart/host-quickstart

Initialize a plugin by creating a manifest from a WASM URL.

```haskell
module Main where  
import Extism  
  
main = do  
  let wasm = wasmURL "GET" "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"  
  plugin <- unwrap <$> newPlugin (manifest [wasm]) [] True
```

--------------------------------

### Generate Haskell Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Initialize a new Haskell plugin project using the Extism CLI.

```bash
extism gen plugin -l Haskell -o plugin  
```

--------------------------------

### Generate C Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Use the Extism CLI to scaffold a new C plugin project and initialize submodules.

```bash
extism gen plugin -l C -o plugin  
cd ./plugin  
git submodule update --init --recursive  
```

--------------------------------

### Generate Zig Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Initialize a new Zig plugin project.

```bash
extism gen plugin -l Zig -o plugin  
```

--------------------------------

### Create a new plugin

Source: https://extism.org/docs/concepts/runtime-apis

Initializes a new plugin instance. The errmsg parameter must be freed using extism_plugin_new_error_free if an error occurs.

```c
ExtismPlugin extism_plugin_new(const uint8_t *wasm,  
                               ExtismSize wasm_size,  
                               const ExtismFunction **functions,  
                               ExtismSize n_functions,  
                               bool with_wasi,  
                               char **errmsg);
```

--------------------------------

### Implement Plug-in Logic in Rust

Source: https://extism.org/docs/concepts/plug-in-system

Rust implementation of the 'before_checkout' function using the Extism PDK to apply conditional discount logic.

```rust
#[plugin_fn]  
pub fn before_checkout(Json(cart): Json<Cart>) -> FnResult<Json<Discount>> {  
    let mut discount = Discount { discount_percent: 0.0 };  
  
    // merchant decides what to do here  
    if cart.is_new_customer && cart.cart_total_in_cents >= 10000 { // new customer & $100+ spend, give a 20% discount  
        discount.discount_percent = 20.0  
    }  
  
    Ok(Json(discount))  
}  
```

--------------------------------

### Compile Haskell Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Build the Haskell plugin using make.

```bash
make  
```

--------------------------------

### Compile Zig Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Build the Zig project using the Zig build system.

```bash
zig build  
```

--------------------------------

### Zig Plugin Implementation

Source: https://extism.org/docs/quickstart/plugin-quickstart

Implement the greet function in Zig with Wasm exports.

```zig
const std = @import("std");  
const extism_pdk = @import("extism-pdk");  
const Plugin = extism_pdk.Plugin;  
  
const allocator = std.heap.wasm_allocator;  
  
export fn greet() i32 {  
    const plugin = Plugin.init(allocator);  
    const name = plugin.getInput() catch unreachable;  
    defer allocator.free(name);  
  
    const output = std.fmt.allocPrint(allocator, "Hello, {s}!", .{name}) catch unreachable;  
    plugin.output(output);  
    return 0;  
}  
```

--------------------------------

### Compile and Run Java Plugin

Source: https://extism.org/docs/quickstart/host-quickstart

Command to compile and execute the Java application.

```bash
mvn compile exec:java -Dexec.mainClass="com.dylibso.myapp.Main"  
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}  
```

--------------------------------

### Run C# Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Execute the compiled C# WASM plugin using the Extism CLI.

```bash
extism call .\bin\Debug\net8.0\wasi-wasm\AppBundle\Plugin.wasm greet --input "Benjamin" --wasi  
# => Hello, Benjamin!  
```

--------------------------------

### Run PHP script

Source: https://extism.org/docs/quickstart/host-quickstart

Executes the index.php file.

```bash
php index.php  
```

--------------------------------

### Execute Plug-in via Host SDK

Source: https://extism.org/docs/concepts/plug-in-system

TypeScript function demonstrating how to load a Wasm plug-in and execute the 'before_checkout' function using the Extism JavaScript SDK.

```typescript
async function processCart(cart: Cart) {  
    const wasm = {  
        path: "/path/to/customer-discount-plugin.wasm"  
    }  
    const plugin = await ExtismPlugin.new(wasm)  
    const input = JSON.stringify(cart)  
    const res = await plugin.call("before_checkout", new TextEncoder().encode(input));  
    const discount: Discount = JSON.parse(res)  
  
    if (discount.discountPercentage > 0.0) {  
        checkoutCart(cart, discount.discountPercentage)  
    } else {  
        checkoutCart(cart)  
    }  
}  
```

--------------------------------

### Generate C# Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Use the Extism CLI to scaffold a new C# plugin project.

```bash
extism gen plugin -l C# -o plugin  
```

--------------------------------

### AssemblyScript Plugin Implementation

Source: https://extism.org/docs/quickstart/plugin-quickstart

Define the greet export in AssemblyScript.

```typescript
import { Config, Host, Var } from "@extism/as-pdk";  
  
function myAbort(  
  message: string | null,  
  fileName: string | null,  
  lineNumber: u32,  
  columnNumber: u32,  
): void {}  
  
export function greet(): i32 {  
  const name = Host.inputString();  
  Host.outputString("Hello, " + name);  
  return 0;  
}  
```

--------------------------------

### View Extism CLI call command help

Source: https://extism.org/docs/install

Displays the available flags and usage instructions for the 'extism call' command.

```bash
Usage:  
  extism call [flags] wasm_file function  
  
Flags:  
      --allow-host stringArray                  Allow access to an HTTP host, if no hosts are listed then all requests will fail. Globs may be used for wildcards  
      --allow-path stringArray                  Allow a path to be accessed from inside the Wasm sandbox, a path can be either a plain path or a map from HOST_PATH:GUEST_PATH  
      --config stringArray                      Set config values, should be in KEY=VALUE format  
  -h, --help                                    help for call  
      --http-response-max extism_http_request   Maximum HTTP response size in bytes when using extism_http_request (default -1)  
  -i, --input string                            Input data  
      --link stringArray                        Additional modules to link  
      --log-level string                        Set log level: trace, debug, warn, info, error  
      --loop int                                Number of times to call the function (default 1)  
  -m, --manifest                                When set the input file will be parsed as a JSON encoded Extism manifest instead of a WASM file  
      --memory-max int                          Maximum number of pages to allocate  
      --set-config config                       Create config object using JSON, this will be merged with any config arguments  
      --stdin                                   Read input from stdin  
      --timeout uint                            Timeout in milliseconds  
      --var-max int                             Maximum size in bytes of Extism var store (default -1)  
      --wasi                                    Enable WASI  
  
Global Flags:  
      --github-token string   Github access token, can also be set using the $GITHUB_TOKEN env variable  
  -q, --quiet                 Suppress output  
  -v, --verbose               Enable additional logging
```

--------------------------------

### Configuring mock input in xtp.toml

Source: https://extism.org/docs/concepts/testing

Define mock input data or file paths within the xtp.toml configuration file for automated testing.

```toml
# path or url locating the wasm plugin to test  
bin = "https://raw.githubusercontent.com/extism/extism/main/wasm/code.wasm"  
  
[[test]]  
# label this test something recognizable to see in CLI output  
name = "basic"  
# build the test wasm module, is run before the test  
build = "cd examples/countvowels && tinygo build -o test.wasm -target wasi test.go"  
# the wasm module to use as the test  
with = "examples/countvowels/test.wasm"  
# provide mock input data to the plugin test call, returned to a 'MockInput' type of function call  
mock_input = { data = "this is my mock input data" }  
  
[[test]]  
name = "basic - file input"  
build = "cd examples/countvowels && tinygo build -o test.wasm -target wasi test.go"  
with = "examples/countvowels/test.wasm"  
# load mock input data from a file instead of inline  
mock_input = { file = "examples/countvowels/test.go" }
```

--------------------------------

### Load a Plugin in Elixir

Source: https://extism.org/docs/quickstart/host-quickstart

Initializes a plugin using a map-based manifest in an IEx session.

```elixir
url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"  
manifest = %{wasm: [%{url: url}]}  
{:ok, plugin} = Extism.Plugin.new(manifest, false)  
```

--------------------------------

### Load a plugin in F#

Source: https://extism.org/docs/quickstart/host-quickstart

Initializes a plugin from a remote WASM source with WASI enabled.

```fsharp
open System  
  
open Extism.Sdk  
open Extism.Sdk.Native  
  
let uri = Uri("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm")  
let manifest = Manifest(new UrlWasmSource(uri))  
  
let plugin = new Plugin(manifest, Array.Empty<HostFunction>(), withWasi = true)  
```

--------------------------------

### Implement Mock Host Functions in Go

Source: https://extism.org/docs/concepts/testing

Create a Wasm module that exports functions to simulate host behavior. These exports are accessed by the plugin as imports.

```go
package main  
  
import (  
    // to simulate Host Functions, use the PDK to manage host/guest memory.  
    pdk "github.com/extism/go-pdk"  
)  
  
// this is our in-memory KV store (e.g. a mock database)  
var kv map[string]string = make(map[string]string)  
  
// This export will be made available to the plugin as an import function  
//go:export kv_read  
func kv_read(key uint64) uint64 {  
    // find the memory block that contains the key, read the bytes, and look up the   
    // corresponding value in the KV store  
    keyMem := pdk.FindMemory(key)  
    k := string(keyMem.ReadBytes())  
    // if the entry is not found, return 0  
    v, ok := kv[k]  
    if !ok {  
        return 0  
    }  
  
    // allocate a new memory block for the value, write the value bytes, and return the offset  
    valMem := pdk.AllocateString(v)  
    return valMem.Offset()  
}  
  
// This export will be made available to the plugin as an import function  
//go:export kv_write  
func kv_write(key uint64, value uint64) {  
    // find the memory block that contains the key and value, read their bytes,   
    // and store the key-value pair in the KV store  
    keyMem := pdk.FindMemory(key)  
    valueMem := pdk.FindMemory(value)  
    k := string(keyMem.ReadBytes())  
    v := string(valueMem.ReadBytes())  
    kv[k] = v  
}  
  
func main() {}  
```

--------------------------------

### Generate F# Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Use the Extism CLI to scaffold a new F# plugin project.

```bash
extism gen plugin -l F# -o plugin  
```

--------------------------------

### Run plugin tests via CLI

Source: https://extism.org/docs/concepts/testing

Executes the test suite using the xtp CLI, specifying the plugin, test harness, and mock host Wasm files.

```bash
xtp plugin test kvplugin.wasm --with kvtest.wasm --mock-host kvhost.wasm
```

--------------------------------

### Compile C Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Compile the C source code into a WASM binary using clang.

```bash
clang -o plugin.wasm --target=wasm32-unknown-unknown -nostdlib -Wl,--no-entry -mexec-model=reactor -Wl,--export=greet ./src/plugin.c  
```

--------------------------------

### Add Java Dependency

Source: https://extism.org/docs/quickstart/host-quickstart

Configuration snippets for Maven and Gradle to include the Extism Java SDK.

```xml
<dependency>  
    <groupId>org.extism.sdk</groupId>  
    <artifactId>extism</artifactId>  
    <version>1.0.0</version>  
</dependency>
```

```gradle
implementation 'org.extism.sdk:extism:1.0.0'
```

--------------------------------

### Build the C++ application

Source: https://extism.org/docs/quickstart/host-quickstart

Compile the C++ application using CMake.

```bash
cmake -B build && cmake --build build
```

--------------------------------

### Load Rust Plugin

Source: https://extism.org/docs/quickstart/host-quickstart

Initialize a plugin from a remote WASM URL using the Rust SDK.

```rust
use extism::*;

fn main() {
  let url = Wasm::url(
    "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
  );
  let manifest = Manifest::new([url]);
  let mut plugin = Plugin::new(&manifest, [], true).unwrap();
}
```

--------------------------------

### Compile AssemblyScript Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Build the AssemblyScript plugin using npm.

```bash
npm run build  
```

--------------------------------

### Testing plugins via xtp CLI

Source: https://extism.org/docs/concepts/testing

Pass mock input data directly via command line arguments when running plugin tests.

```bash
xtp plugin test plugin.wasm --with test.wasm --mock-input-data "this is my mock input data"  
# or a path to a file for --mock-input-file
```

--------------------------------

### Configure OCaml Dependencies

Source: https://extism.org/docs/quickstart/host-quickstart

Add the extism package to your project configuration files.

```dune
  (libraries extism)  
```

```dune
   (package  
     (depends (extism)))  
```

--------------------------------

### Generate Rust Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Use the Extism CLI to scaffold a new Rust plugin project.

```bash
extism gen plugin -l Rust -o plugin
```

--------------------------------

### Run Rust Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Execute the compiled Wasm module using the Extism CLI.

```bash
extism call target/wasm32-unknown-unknown/debug/rust_pdk_template.wasm greet --input "Benjamin"  
# => Hello, Benjamin!
```

--------------------------------

### Load JavaScript Plugin

Source: https://extism.org/docs/quickstart/host-quickstart

Initialize a plugin from a remote WASM URL in a Node.js environment.

```javascript
const createPlugin = require("@extism/extism")

const plugin = await createPlugin(
    'https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm',
    { useWasi: true }
);
```

--------------------------------

### Call a Host Function in Go

Source: https://extism.org/docs/concepts/host-functions

Demonstrates declaring an external host function using the //export annotation and invoking it within a Go plug-in.

```go
package main  
  
import (  
    "strconv"  
  
    "github.com/extism/go-pdk"  
)  
  
// `hello_world` declared below, is a function provided by the host and is linked as a WebAssembly  
// "import" available to the plug-in. By adding the `export $function_name` annotation, the TinyGo  
// compiler knows that this is an external function.  
  
//export hello_world  
func hello_world(x uint64) uint64  
  
//export say_hello  
func say_hello() int32 {  
    input := pdk.InputString()  
  
    // Create output, this will be passed through `hello_world`  
    output := "Hello, " + input  
    mem := pdk.AllocateString(output)  
  
    // Call `hello_world` host function, it accepts an offset in memory and  
    // returns an offset in memory  
    offs := hello_world(mem.Offset())  
    mem = pdk.FindMemory(offs)  
  
    pdk.OutputMemory(mem)  
    return 0  
}  
  
func main() {}
```

--------------------------------

### Define Go Export

Source: https://extism.org/docs/quickstart/plugin-quickstart

Use the //export magic comment to expose a function to the host.

```go
package main  
  
import (  
    "github.com/extism/go-pdk"  
)  
  
//export greet  
func greet() int32 {  
    input := pdk.Input()  
    greeting := `Hello, ` + string(input) + `!`  
    pdk.OutputString(greeting)  
    return 0  
}  
  
func main() {}
```

--------------------------------

### Configure PHP minimum-stability

Source: https://extism.org/docs/quickstart/host-quickstart

Sets the minimum-stability to dev in composer.json.

```json
{
   "minimum-stability": "dev",
}
```

--------------------------------

### Compile Rust Plugin

Source: https://extism.org/docs/quickstart/plugin-quickstart

Build the plugin for the wasm32-unknown-unknown target.

```bash
cargo build --target wasm32-unknown-unknown
```

```bash
rustup target add wasm32-unknown-unknown
```

```bash
cargo build --target wasm32-unknown-unknown --release
```

--------------------------------

### Set log file

Source: https://extism.org/docs/concepts/runtime-apis

Configures the log file path and the logging level.

```c
bool extism_log_file(const char *filename, const char *log_level);
```

--------------------------------

### Call a plugin function

Source: https://extism.org/docs/concepts/runtime-apis

Executes a function by name with the provided input data. Returns 0 on success.

```c
int32_t extism_plugin_call(ExtismPlugin *plugin,  
                           const char *func_name,  
                           const uint8_t *data,  
                           ExtismSize data_len);
```

--------------------------------

### Execute OCaml Plugin

Source: https://extism.org/docs/quickstart/host-quickstart

Run the compiled OCaml executable.

```bash
dune exec ./bin/main.exe  
```

--------------------------------

### Override xtp.toml location with CLI

Source: https://extism.org/docs/concepts/testing

Use the --path flag to specify a custom directory for the xtp.toml configuration file during plugin testing.

```bash
xtp plugin test --path tests/countvowels
```

--------------------------------

### Run Plugin via CLI

Source: https://extism.org/docs/quickstart/plugin-quickstart

Execute a compiled Wasm plugin using the Extism CLI.

```bash
extism call plugin.wasm greet --input "Benjamin"  
# => Hello, Benjamin  
```

```bash
extism call plugin.wasm greet --input "Benjamin" --wasi  
# => Hello, Benjamin!  
```

```bash
extism call ./zig-out/bin/zig-pdk-template.wasm greet --input "Benjamin"  
# => Hello, Benjamin!  
```

```bash
extism call ./index.wasm greet --input "Benjamin"  
# => Hello, Benjamin  
```

--------------------------------

### Free host function

Source: https://extism.org/docs/concepts/runtime-apis

Deallocates an ExtismFunction object.

```c
void extism_function_free(ExtismFunction *ptr);  
```

--------------------------------

### Exporting functions in a WebAssembly module

Source: https://extism.org/docs/concepts/plug-in

Demonstrates how to define private internal logic versus functions explicitly exported for external invocation.

```javascript
// this const and function are private  
const VOWELS = "aeiou";  
function isVowel(char) {  
    return VOWELS.includes(char)  
}  
  
// this function is exported and can be invoked from outside  
export function countVowels(input) {  
  return input  
      .split('')  
      .reduce((count, char) =>  
          count + isVowel(char) ? 1 : 0, 0)  
}  
```

--------------------------------

### Call a function with host context

Source: https://extism.org/docs/concepts/runtime-apis

Executes a function while providing an opaque pointer for host context access within host functions.

```c
int32_t extism_plugin_call_with_host_context(ExtismPlugin *plugin,  
                           const char *func_name,  
                           const uint8_t *data,  
                           ExtismSize data_len,  
                           void *host_ctx);
```
Tokens:
Raw