package extism

  1. Overview
  2. Docs

Extism bindings for OCaml

Introduction

Extism is a framework for executing WebAssembly plugins. The OCaml bindings require libextism, installation information is available on the Extism website

  • The Plugin and Manifest modules are the main modules to look at.
  • Type provides different types that can be encoded as input/output to Plugin.call
  • Function is used to define host functions and Host_function is used from inside host functions to access the plugin memory

Basic example

The following loads a Plugin from a file on disk using Manifest then calls a function with a string and prints the string output:

open Extism

let () =
  let plugin =
    Plugin.of_manifest_exn
    @@ Manifest.create [ Manifest.Wasm.file "test/code.wasm" ]
  in
  let res =
    Plugin.call_string_exn plugin ~name:"count_vowels" "input data"
  in
  print_endline res

Using the typed plugin interface you can pre-define plug-in functions:

open Extism

module Example = struct
  include Plugin.Typed.Init ()

  let count_vowels = exn @@ fn "count_vowels" Type.string Type.string
end

let () =
  let plugin =
    Example.of_plugin_exn
    @@ Plugin.of_manifest_exn
    @@ Manifest.create [ Manifest.Wasm.file "test/code.wasm" ]
  in
  let res =
    Example.count_vowels plugin "input data"
  in
  print_endline res

API

module Manifest = Extism_manifest

The Manifest module is a reference to the Extism_manifest package, it allows you to programatically construct Extism manifests.

module Val_type : sig ... end

Val_type enumerates the available Wasm types, this should only be used when implementing host functions

module Val : sig ... end

Val represents low-level WebAssembly values

module Type : sig ... end

Type defines conversions from OCaml values in and out of Extism memory

module Host_function : sig ... end

Host_function represents the plugin that is currently running from inside a host function definition

module Function : sig ... end

Function is used to create new a new function, which can be called from a WebAssembly plugin

module Plugin : sig ... end

Plugins contain functions that can be called

val set_log_file : ?level:[ `Error | `Warn | `Info | `Debug | `Trace | `Filter of string ] -> string -> bool

Set the log file and level for all Extism plugins, the names stdout or stderr can be used to write to the terminal

type drain_logs = unit -> unit
val set_log_custom : ?level:[ `Error | `Warn | `Info | `Debug | `Trace | `Filter of string ] -> (string -> unit) -> drain_logs

Set the log level and enable buffered logging. Returns a function that can be used to drain the logs

module Error : sig ... end

Extism error type

val with_plugin : (Plugin.t -> 'a) -> Plugin.t -> 'a

with_plugin f plugin uses Fun.protect to ensure that a plugin is freed when f finished executing

val extism_version : unit -> string

Returns the libextism version, not the version of the OCaml library