Document semantics of `use` in `deps/`

[ouillie]

I'd like to use wit-bindgen to generate Rust bindings for wasi:cli/[email protected], but I'm confused about the semantics of the use statement from within a dependency, and would like to at least clarify the documentation.

Here's what I did:

1. Start by copying all the WIT files in this directory to a local directory called wit/, and try to generate the bindings with wit-bindgen rust wit/ --world command. This fails with package not found ... wasi:io/[email protected] (imported here).
2. Try creating a subdirectory in wit/ called deps/, and copy the WIT file contents of the IO directory there. Running the same wit-bindgen command, now I get a new error: interface or world `error` not found in package (referring to this line).

Here's the directory structure for reference. File 1 (imports.wit) references file 2 (deps/world.wit), which references file 3, which should reference 4, but wit-bingen if failing to resolve that last one.

.
└── wit
    ├── command.wit
    ├── deps
    │   ├── error.wit     # 4. Contains definition of error type
    │   ├── poll.wit
    │   ├── streams.wit   # 3. use error.{error}
    │   └── world.wit     # 2. import streams
    ├── environment.wit
    ├── exit.wit
    ├── imports.wit       # 1. include wasi:io/[email protected] (from deps/world.wit)
    ├── run.wit
    ├── stdio.wit
    └── terminal.wit

I'm not sure how to proceed since the structure of the deps/ subfolder is under-documented, especially how it relates to the 3 different types of external references in WIT: include, import, and use. The world called error is found in the same package as streams.wit, yet wit-bindgen cannot find it. I also tried moving it to the top-level wit/ directory (and changing the package name), but that didn't work either.

What am I doing wrong?

[alexcrichton]

Thanks for the report! This is a case where a bad error message is leading you astray of the root cause of what's happening, and it's something we should fix! The problem is that you've placed the wasi:io files directly in the deps folder. While deps/foo.wit is supported that means that foo.wit must itself be a standalone package. In the case here the wasi:io package is split into multiple files so they won't work if each file thinks it's its own package. To fix this you'd need to place all files in wit/deps/io/*.wit.

Alternatively you can also copy the whole original directory wholesale (the entire top-level wit) and you should then be able to use --world wasi:cli/command I think.

Does that at least help resolve the immediate issue? This is definitely something worth fixing at the underlying parsing layer to improve the error message here.

[ouillie]

That does fix things, thanks! I think this is mostly a documentation issue. Did I miss anything that explains how the special deps/ folder should look? But ya, I suppose a link to that documentation should go into error messages like this. Happy to conjure a PR if you can point me to any similar-ish existing PR as an example.

[alexcrichton]

The best documentation for WIT is probably here where the official specification is here, but I suspect that neither is necessarily up-to-date or rigorous about the deps folder. I haven't done a great job about pushing documentation upstream for how things work.

Perhaps the best course of action for now, would you mind opening an issue in https://github.com/bytecodealliance/wasm-tools? That's where all this parsing happens and the changes would happen in wit-parser for error messages for example. I'm not sure how best to change the error though... Otherwise though sending a PR to https://github.com/bytecodealliance/component-docs would also be most welcome to update the docs