Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: add discord link to end, minor tweaks to verbiage #35

Merged
merged 5 commits into from
Oct 12, 2023
Merged

feat: add discord link to end, minor tweaks to verbiage #35

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a130f83
feat: add discord link to end, minor tweaks to verbiage
wikiwong Oct 10, 2023
b8d40d8
fix: revert link back to /plugin
wikiwong Oct 11, 2023
f28cbbc
fix: change link to /plug-in
wikiwong Oct 11, 2023
b9d8a1c
fix: verbiage
wikiwong Oct 11, 2023
82790ef
chore: wording
wikiwong Oct 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 12 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

[![crates.io](https://img.shields.io/crates/v/extism_pdk.svg)](https://crates.io/crates/extism-pdk)

This library can be used to write [Extism Plug-ins](https://extism.org/docs/concepts/plug-in) in Rust.
This library can be used to write [Extism Plug-ins](https://extism.org/docs/concepts/pdk) in Rust.
bhelx marked this conversation as resolved.
Show resolved Hide resolved

## Install

Make sure you generate a `lib` project:
Generate a `lib` project with Cargo:

```bash
cargo new --lib my-plugin
Expand All @@ -18,7 +18,7 @@ Add the library from [crates.io](https://crates.io/crates/extism-pdk).
cargo add extism-pdk
```

Change your `Cargo.toml` to set the crate-type to `cdylib`:
Change your `Cargo.toml` to set the crate-type to `cdylib` (this instructs the compiler to produce a Wasm file):
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't exactly accurate. Compiling to a wasm32-* target is what makes the output a wasm file. This tells the compiler that you are emitting a dynamic library and not an executable (which in wasm parlance means a command pattern module with a _start function)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yeah I can see how that would be misleading. I meant as opposed to a .dylib or .so.

(which in wasm parlance means a command pattern module with a _start function)

I thought the presence of a main function is what determines whether or not it is a command or reactor module

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about this:

Change your `Cargo.toml` to set the crate-type to `cdylib` (this instructs the compiler to produce a dynamic library, which for our target will be a Wasm file):

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you're writing in c or rust your "main" function is called main in the source, but when it turns into wasm it becomes can export called _start

Copy link
Contributor

@bhelx bhelx Oct 11, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant as opposed to a .dylib or .so

That would be determined by the target flag. This is from the wasm-pack doc but relevant:

Here though crate-type = ["cdylib"] typically signifies that you'd like the compiler to create a dynamic system library, but for WebAssembly target it simply means "create a *.wasm file without a start function". On other platforms this output type will create *.so file on Linux, *.dylib on macOS, and *.dll Windows.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 I think that definition is in line with my latest update


```toml
[lib]
Expand All @@ -27,7 +27,7 @@ crate_type = ["cdylib"]

## Getting Started

The goal of writing an [Extism plug-in](https://extism.org/docs/concepts/plug-in) is to compile the your rust code to a Wasm module with some special export 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:
The goal of writing an [Extism plug-in](https://extism.org/docs/concepts/pdk) is to compile your Rust 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. For this, we use the `#[plugin_fn]` macro on our exported function:


```rust
Expand Down Expand Up @@ -64,11 +64,11 @@ extism call target/wasm32-unknown-unknown/debug/my_plugin.wasm greet --input "Be

### More About Exports

Adding the [plugin_fn](https://docs.rs/extism-pdk/latest/extism_pdk/attr.plugin_fn.html) macro to your function does a couple things. It exposes your function as an export and it handles some of the lower level ABI details that allow you to declare your Wasm function as if it were a normal rust function. Here are a few examples of exports you can define.
Adding the [plugin_fn](https://docs.rs/extism-pdk/latest/extism_pdk/attr.plugin_fn.html) macro to your function does a couple things. It exposes your function as an export and it handles some of the lower level ABI details that allow you to declare your Wasm function as if it were a normal Rust function. Here are a few examples of exports you can define.

### Primitive Types

A common thing you may want to do is pass some primitive rust data back and forth.
A common thing you may want to do is pass some primitive Rust data back and forth.
The [plugin_fn](https://docs.rs/extism-pdk/latest/extism_pdk/attr.plugin_fn.html) macro can map these types for you:

> **Note**: The [plugin_fn](https://docs.rs/extism-pdk/latest/extism_pdk/attr.plugin_fn.html) macro uses the [convert crate](https://github.com/extism/extism/tree/main/convert) to automatically convert and pass types across the guest / host boundary.
Expand Down Expand Up @@ -225,7 +225,7 @@ pub fn http_get(Json(req): Json<HttpRequest>) -> FnResult<HttpResponse> {

Like any other code module, Wasm not only let's you export functions to the outside world, you can
import them too. Host Functions allow a plug-in to import functions defined in the host. For example,
if you host application is written in python, it can pass a python function down to your rust plug-in
if you host application is written in Python, it can pass a Python function down to your Rust plug-in
where you can invoke it.

This topic can get fairly complicated and we have not yet fully abstracted the Wasm knowledge you need
Expand Down Expand Up @@ -259,8 +259,7 @@ pub fn hello_from_python() -> FnResult<String> {
### Testing it out

We can't really test this from the Extism CLI as something must provide the implementation. So let's
write out the python side here. You should check the docs for the language you're using on the host side
for how to implement host functions.
write out the Python side here. Check out the [docs for the host SDKs](https://extism.org/docs/category/integrate-into-your-codebase) to implement a host function in a language of your choice.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page will be going away I think. Might be better to link to the Host SDK concept doc?


```python
from extism import host_fn, Function, ValType
Expand All @@ -270,8 +269,8 @@ def a_python_func(plugin, input_, output, _user_data):
# The plug-in is passing us a string
input_str = plugin.input_string(input_[0])

# just printing this out to prove we're in python land
print("Hello from python!")
# just printing this out to prove we're in Python land
print("Hello from Python!")

# let's just add "!" to the input string
# but you could imagine here we could add some
Expand Down Expand Up @@ -306,6 +305,6 @@ python3 app.py
# => An argument to send to Python!
```

### Reach Out!



Have a question or just want to drop in and say hi? [Hop on the Discord](https://extism.org/discord)!
Loading