Skip to content
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

Document semantics of use in deps/ #1046

Open
ouillie opened this issue Sep 6, 2024 · 3 comments
Open

Document semantics of use in deps/ #1046

ouillie opened this issue Sep 6, 2024 · 3 comments

Comments

@ouillie
Copy link

ouillie commented Sep 6, 2024

I'd like to use wit-bindgen to generate Rust bindings for wasi:cli/run@0.2.1, 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/imports@0.2.1 (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/imports@0.2.1 (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
Copy link
Member

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
Copy link
Author

ouillie commented Sep 6, 2024

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
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants