Skip to content
Merged
Changes from all commits
Commits
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
41 changes: 24 additions & 17 deletions SetjmpLongjmp.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# C setjmp/longjmp support

WASI-SDK provides basic setjmp/longjmp support.

Note that it's still under active development and may change in
future versions.

## Build an application

To build an application using setjmp/longjmp, you need two things:
Expand All @@ -11,13 +16,13 @@ To build an application using setjmp/longjmp, you need two things:
### Example without LTO

```shell
clang -Os -mllvm -wasm-enable-sjlj -o your_app.wasm your_app.c -lsetjmp
clang -Os -mllvm -wasm-enable-sjlj -o your_app.legacy.wasm your_app.c -lsetjmp
```

### Example with LTO

```shell
clang -Os -flto=full -mllvm -wasm-enable-sjlj -Wl,-mllvm,-wasm-enable-sjlj -o your_app.wasm your_app.c -lsetjmp
clang -Os -flto=full -mllvm -wasm-enable-sjlj -Wl,-mllvm,-wasm-enable-sjlj -o your_app.legacy.wasm your_app.c -lsetjmp
```

## Run an application
Expand All @@ -30,42 +35,44 @@ Unfortunately, there are two incompatible versions of

* The latest version with `exnref`

* The [phase3] version
* The legacy [phase3] version

### Example with the latest exception handling proposal

Because the current version of WASI-SDK produces an old version
of [exception handling proposal] instructions, if your runtime
implements the latest version of the proposal, you need to convert
your module to the latest version.
By default, the current version of WASI-SDK produces the legacy
"phase3" version of [exception handling proposal] instructions.

[toywasm] is an example of such runtimes.
You can tell the llvm to produce the latest version of proposal by
specifying `-mllvm -wasm-use-legacy-eh=false`. This is expected
to be the default in a future version.

You can use binaryen `wasm-opt` command for the conversion.
Alternatively, you can use binaryen `wasm-opt` command to convert
existing modules from the legacy "phase3" version to the "exnref" version.

```shell
wasm-opt --translate-to-exnref -all -o your_app.exnref.wasm your_app.wasm
wasm-opt --translate-to-exnref -all -o your_app.wasm your_app.legacy.wasm
```

Then you can run it with a runtime supporting the latest version of
[exception handling proposal].
Then you can run it with a runtime supporting the "exnref" version of
the proposal.
[toywasm] is an example of such runtimes.

```shell
toywasm --wasi your_app.exnref.wasm
toywasm --wasi your_app.wasm
```
(You may need to enable the support with `-D TOYWASM_ENABLE_WASM_EXCEPTION_HANDLING=ON`.)

### Example with the phase3 exception handling proposal (a bit older version)
### Example with the legacy phase3 exception handling proposal

If your runtime supports the [phase3] version of
If your runtime supports the legacy [phase3] version of
[exception handling proposal], which is the same version as what WASI-SDK
currently produces, you can run the produced module as it is.
currently produces by default, you can run the produced module as it is.

For example, the classic interpreter of [wasm-micro-runtime] is
one of such runtimes.

```shell
iwasm your_app.wasm
iwasm your_app.legacy.wasm
```
(You may need to enable the support with `-D WAMR_BUILD_EXCE_HANDLING=1 -D WAMR_BUILD_FAST_INTERP=0`.)

Expand Down
Loading