Fully document instantiation workflows

[whitequark]

Right now the environment variables, the arguments, and some other parts of the environment are global. For the filesystem and standard I/O streams this is OK (in some cases sharing the filesystem is desirable, in some it is not) but the need to set global arguments is really awkward. I would like to be able to run WASI commands without relying quite so much on global environment.

One of my WASI applications should ideally spawn another via a custom exported function (they're built as separate binaries originally). Right now that wouldn't work because the callee crashes when built for Wasm and the crash is incomprehensible, but eventually I do care about reentrancy, and the current approach is decidedly non-reentrant.

[whitequark]

I eventually figured out that I can do what I want by using --instantiation combined with --no-wasi-shim.

The fact that no --instantiation argument, --instantiation sync, and --instantiation async lead to three completely different behaviors is extremely unintuitive. Even having read the source code of most of the library it took serendipity to discover that the latter two modes offer something that I want.

In any case, I think what I want to do is already doable.

[guybedford]

--no-wasi-shim should always be the default when passing --instantiation. If that was not applying, I would be interested to know how.

Glad you discovered the feature - yes better documentation for custom instantiation is needed. Reopening as a docs issue.

[whitequark]

--no-wasi-shim should always be the default when passing --instantiation. If that was not applying, I would be interested to know how.

I did not realize that (I first tried the former then the latter, and never the latter without the former). I checked and it applies.

[landonxjames]

I believe I am running into some similar issues. I would like to run a WASI component inside a Worker thread (as a kind of async shim until preview3 is available). A naive attempt to run the function in a Worker fails because it is looking for the global const resourceHandleSymbol = Symbol('resource');. Rebuilding the component with --instantiation async and instantiating inside the Worker thread seems like it might work, but it throws in the --no-wasi-shim complication, so I haven't quite gotten that working yet (I think I have to provide some of the wasi functionality myself?).

[whitequark]

Providing a shim isn't as difficult as it first seems:

https://github.com/YoWASP/runtime-js/blob/develop/lib/wasi-virt.js

https://github.com/YoWASP/yosys/blob/b5e194f514fa29907fd1a848b4792c69af8a4e7e/npmjs/package-in.json#L34

[guybedford]

Instantiation is documented in https://bytecodealliance.github.io/jco/transpiling.html#instantiation. If there is anything more we can do here please do follow-up.