-
Notifications
You must be signed in to change notification settings - Fork 7
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.
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
feat: add discord link to end, minor tweaks to verbiage #35
Merged
Merged
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -6,7 +6,7 @@ This library can be used to write [Extism Plug-ins](https://extism.org/docs/conc | |
|
||
## Install | ||
|
||
Make sure you generate a `lib` project: | ||
Generate a `lib` project with Cargo: | ||
|
||
```bash | ||
cargo new --lib my-plugin | ||
|
@@ -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): | ||
|
||
```toml | ||
[lib] | ||
|
@@ -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/plug-in) 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 | ||
|
@@ -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. | ||
|
@@ -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 | ||
|
@@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
@@ -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 | ||
|
@@ -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)! |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
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.
I thought the presence of a
main
function is what determines whether or not it is a command or reactor moduleThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How about this:
There was a problem hiding this comment.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That would be determined by the target flag. This is from the wasm-pack doc but relevant:
There was a problem hiding this comment.
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