Add documentation

[cjihrig]

Since things are beginning to stabilize (as much as they can, given that WASI itself is still unstable), it's probably time to document the public API.

To avoid too much reinvention of the wheel, the WASI API docs are probably a good place to start, with the following alterations:

• Replace __WASI_* with UVWASI_*.
• All of the API functions also take an additional uvwasi_t* uvwasi as their first argument (this represents the context so that multiple uvwasis can exists side by side).
• All of the API functions return a uvwasi_errno_t.
• There are also the uvwasi_init() and uvwasi_destroy() functions that are needed to setup and teardown uvwasi instances.

[cjihrig]

Pushed up a small documentation update in 2fdc620. Still lots of room for improvement though, and the example usage is incomplete, so I'm going to leave this open for now.

[hostilefork]

I'm a big fan of documentation. :-) In this particular case, it might help most to have some higher level contextualization of what this is...

For instance: let's say someone (hypothetically) has a libuv app in C which has successful filesystem and network I/O on several platforms (Linux, Win, Mac, Haiku, etc.)

Then let's say they build a version of that for WasmEdge using Emscripten. It successfully compiles and prints messages like a champ. Unfortunately, without the Networking and Filesystem behaviors enabled, it doesn't have much use. Trying to use libuv will get you missing symbols at link time.

If you look in libuv at CMakeLists.txt, it splits out into Windows vs. POSIX, with small deviations in the POSIX case for platform variations...e.g. this bit for HaikuOS. There is unfortunately no mention of WASI in that file.

But, then there is this project... which is used (somehow?) by libuv and called "uvwasi". But I'm not seeing what the relationship is.

Perhaps an illuminating explanation of this top level would be the best use for the README.md - an overview of what this is and what it is not (vs. a list of functions, which seems they'd be best in a dedicated page).

And if you have any advice for this hypothetical someone...who has a libuv-based app who'd like to just flip a switch and see it run in a WASI container and have file/networking...I'd imagine that sort of person would quite appreciate hearing it. :-)

[tniessen]

@hostilefork What you are describing sounds like the reverse of what uvwasi does to me. uvwasi does not run libuv-based applications as WebAssembly and does not translate libuv calls into WASI calls.

It's the other way around: uvwasi implements WASI on top of libuv so that WebAssembly runtimes can easily implement WASI calls.

                              |
WebAssembly code              |      WebAssembly application code
                              |                 |
                              |                 v
                              | WASI syscalls (inserted by compiler toolchain)
                              |                 |
------------------------------+                 |
                              |                 v
WebAssembly runtime (Node.js) |    uvwasi (implementation of WASI)
                              |                 |
                              |                 v
                              |               libuv
                              |                 |
                              |                 v
                              |        platform-specific calls
                              | 

In particular, note that uvwasi sits above libuv and within the WebAssembly runtime in this simplified call stack; the WebAssembly application does not interact with libuv directly and should even be entirely unaware of libuv.

[hostilefork]

uvwasi implements WASI on top of libuv so that WebAssembly runtimes can easily implement WASI calls.

ahh. That sentence (and the diagram) seem like a great way to start the README!

uvwasi does not (...) translate libuv calls into WASI calls.

(Maybe I'm just seeing this through the lens of what I'm doing right now, but that would strike me as the "more common search intent" for libuv+wasi...enough so that perhaps that clarification would be useful in the README as well.)

Might you (or anyone) have pointers on that? Right now I'm trying to figure out if this is some of the magic that Emscripten (or perhaps wasi-sdk as an Emscripten-alternative?) could do beneath libuv. So you'd target libuv for some generic POSIX with no threading or exotic options, and then it would "just work" (?) Wonder if anyone has done this.

---

Update for anyone interested: I found a prebuilt clang with wasi-sdk and it hits problems during unix.h... it appears the <pthread> dependency is non-negotiable, and there are also missing headers in wasi-sdk's libc for pwd.h, netdb.h, and termios.h. When you look at the WASI roadmap, being able to compile libuv for pure WASI is probably something that can't be made to work in the near term.