You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The goal of writing an [Extism plug-in](https://extism.org/docs/concepts/plug-in) is to compile your Zig code to a Wasm module with exported functions that the host application can invoke. The first thing you should understand is creating an export. Let's write a simple program that exports a `greet` function which will take a name as a string and return a greeting string. Zig has excellent support for this through the `export` keyword:
53
+
The goal of writing an
54
+
[Extism plug-in](https://extism.org/docs/concepts/plug-in) is to compile your
55
+
Zig code to a Wasm module with exported functions that the host application can
56
+
invoke. The first thing you should understand is creating an export. Let's write
57
+
a simple program that exports a `greet` function which will take a name as a
58
+
string and return a greeting string. Zig has excellent support for this through
59
+
the `export` keyword:
53
60
54
61
```zig
55
62
const std = @import("std");
@@ -69,27 +76,31 @@ export fn greet() i32 {
69
76
}
70
77
```
71
78
72
-
> Note: if you started with the generated project files from `zig init`, you should delete `src/root.zig`
73
-
and any references to it if they are in your `build.zig` file.
79
+
> Note: if you started with the generated project files from `zig init`, you
80
+
> should delete `src/root.zig` and any references to it if they are in your
81
+
> `build.zig` file.
74
82
75
83
Then run:
84
+
76
85
```sh
77
86
zig build
78
87
```
79
88
80
-
This will put your compiled wasm in `zig-out/bin`.
81
-
We can now test it using the [Extism CLI](https://github.com/extism/cli)'s `run`
82
-
command:
89
+
This will put your compiled wasm in `zig-out/bin`. We can now test it using the
Suppose want to re-write our greeting module to never greet Benjamins. We can use `Plugin.setError`:
101
+
102
+
Suppose want to re-write our greeting module to never greet Benjamins. We can
103
+
use `Plugin.setError`:
93
104
94
105
```zig
95
106
export fn greet() i32 {
@@ -123,7 +134,9 @@ echo $?
123
134
124
135
### Json
125
136
126
-
Extism export functions simply take bytes in and bytes out. Those can be whatever you want them to be. A common and simple way to get more complex types to and from the host is with json:
137
+
Extism export functions simply take bytes in and bytes out. Those can be
138
+
whatever you want them to be. A common and simple way to get more complex types
139
+
to and from the host is with json:
127
140
128
141
```zig
129
142
export fn add() i32 {
@@ -149,7 +162,7 @@ export fn add() i32 {
149
162
}
150
163
```
151
164
152
-
To use a json helper, you can accomplish the same as the above with:
165
+
To use a json helper, you can accomplish the same as the above with:
Configs are key-value pairs that can be passed in by the host when creating a
182
-
plug-in. These can be useful to statically configure the plug-in with some data that exists across every function call. Here is a trivial example using `Plugin.getConfig`:
195
+
plug-in. These can be useful to statically configure the plug-in with some data
196
+
that exists across every function call. Here is a trivial example using
197
+
`Plugin.getConfig`:
183
198
184
199
```zig
185
200
export fn greet() i32 {
@@ -195,7 +210,8 @@ export fn greet() i32 {
195
210
}
196
211
```
197
212
198
-
To test it, the [Extism CLI](https://github.com/extism/cli) has a `--config` option that lets you pass in `key=value` pairs:
213
+
To test it, the [Extism CLI](https://github.com/extism/cli) has a `--config`
> **Note**: Use the untyped variants `Plugin.setVar(self: Plugin, key: []const u8, value: []const u8)` and `Plugin.getVar(self: Plugin, key: []const u8) !?[]u8` to handle your own types.
255
+
> **Note**: Use the untyped variants
256
+
> `Plugin.setVar(self: Plugin, key: []const u8, value: []const u8)` and
257
+
> `Plugin.getVar(self: Plugin, key: []const u8) !?[]u8` to handle your own
258
+
> types.
239
259
240
260
## Logging
241
261
242
-
Because Wasm modules by default do not have access to the system, printing to stdout won't work (unless you use WASI).
243
-
Extism provides a simple logging function that allows you to use the host application to log without having to give the plug-in permission to make syscalls.
262
+
Because Wasm modules by default do not have access to the system, printing to
263
+
stdout won't work (unless you use WASI). Extism provides a simple logging
264
+
function that allows you to use the host application to log without having to
> *Note*: From the CLI you need to pass a level with `--log-level`. If you are running the plug-in in your own host using one of our SDKs, you need to make sure that you call `set_log_file` to `"stdout"` or some file location.
290
+
> _Note_: From the CLI you need to pass a level with `--log-level`. If you are
291
+
> running the plug-in in your own host using one of our SDKs, you need to make
292
+
> sure that you call `set_log_file` to `"stdout"` or some file location.
269
293
270
294
## HTTP
271
295
272
-
Sometimes it is useful to let a plug-in [make HTTP calls]. [see: Extism HTTP library](src/http.zig)
296
+
Sometimes it is useful to let a plug-in [make HTTP calls].
297
+
[see: Extism HTTP library](src/http.zig)
273
298
274
299
```zig
275
300
const http = extism_pdk.http;
@@ -324,7 +349,9 @@ export fn http_get() i32 {
324
349
}
325
350
```
326
351
327
-
By default, Extism modules cannot make HTTP requests unless you specify which hosts it can connect to. You can use `--allow-host` in the Extism CLI to set this:
352
+
By default, Extism modules cannot make HTTP requests unless you specify which
353
+
hosts it can connect to. You can use `--allow-host` in the Extism CLI to set
Like any other code module, Wasm not only let's you export functions to the outside world, you can
337
-
import them too. Host Functions allow a plug-in to import functions defined in the host. For example,
338
-
if you host application is written in Python, it can pass a Python function down to your Zig plug-in
339
-
where you can invoke it.
363
+
Like any other code module, Wasm not only let's you export functions to the
364
+
outside world, you can import them too. Host Functions allow a plug-in to import
365
+
functions defined in the host. For example, if you host application is written
366
+
in Python, it can pass a Python function down to your Zig plug-in where you can
367
+
invoke it.
340
368
341
-
This topic can get fairly complicated and we have not yet fully abstracted the Wasm knowledge you need
342
-
to do this correctly. So we recommend reading our [concept doc on Host Functions](https://extism.org/docs/concepts/host-functions) before you get started.
369
+
This topic can get fairly complicated and we have not yet fully abstracted the
370
+
Wasm knowledge you need to do this correctly. So we recommend reading our
371
+
[concept doc on Host Functions](https://extism.org/docs/concepts/host-functions)
372
+
before you get started.
343
373
344
374
### A Simple Example
345
375
346
-
Host functions have a similar interface as exports. You just need to declare them as extern. You only declare the interface as it is the host's responsibility to provide the implementation:
376
+
Host functions have a similar interface as exports. You just need to declare
377
+
them as extern. You only declare the interface as it is the host's
We can't really test this from the Extism CLI as something must provide the implementation. So let's
379
-
write out the Python side here. Check out the [docs for Host SDKs](https://extism.org/docs/concepts/host-sdk) to implement a host function in a language of your choice.
411
+
We can't really test this from the Extism CLI as something must provide the
412
+
implementation. So let's write out the Python side here. Check out the
413
+
[docs for Host SDKs](https://extism.org/docs/concepts/host-sdk) to implement a
0 commit comments