Document the schema of the cargo-component Cargo.toml configuration

[rylev]

The layout of the cargo-component Cargo.toml configuration needs to be documented preferably with the most common configuration items called out in the README.

[jeffparsons]

A handful of examples would go a long way, too. E.g. this morning I wanted to write a component targeting the wasi:http/proxy world. I couldn't figure out the "right" way to do this.

I'm guessing I can get this working by copying all the wasi .wit files from GitHub somewhere into my deps/ folder, and making my component's world extend proxy... or something like that... but I'm guessing that this is also not the way cargo-component wants me to do things. I.e. my not understanding what "magic" cargo-component brings to the table and what it doesn't is often a source of confusion for me. (This is not a request for help — I'm just offering an example of user confusion!)

If there were some real-ish-shaped examples, at least that would then offer a feel for how to do things the way that cargo-component wants me to.

Perhaps this should be a different ticket, though? I just figured I'd chime in on the general topic of "documentation priorities".

EDIT: My attempt to summarise some of the high questions I have about cargo-component that I'd love to have answered in the readme or somewhere:

• What is the difference between [package.metadata.component.dependencies] and [package.metadata.component.target.dependencies]? I've only ever found a way to do anything useful with the latter.
• Am I supposed to bring my own copies of the WASI .wit definitions, or is there a way to make cargo-component bring these in for me from somewhere? A registry? Is there a public official-ish registry housing the WASIp2 definitions?
• cargo-component seems to implicitly extend my target world somehow... exactly what does it do here? And does it expect me to always target my own world (possibly extending one or more other worlds I want to target), or is it okay to make it target something like wasi:http/proxy directly and not have my own .wit at all?
• Should I be generating bindings for wasi stuff myself, or use the wasi crate for this? If the latter, what does that look like?

[allanbrondumkr]

@jeffparsons Did you find any solution on how the intended way to include wasi:http/proxy is?

[calvinrp]

There's a few ways to do it. All this needs to be better documented. Worth noting, that the wasi:http bindings generated are very low-level and not ergonomic. Work is under way for ergonomic solutions, among them https://docs.rs/wstd/latest/wstd/http/index.html (not ready for usage yet, check back soon).

If you cargo component new --lib --target wasi:http/proxy my-project-name, that will setup a new project that targets wasi:http/proxy world. After doing, cargo component build a src/bindings.rs file is generated from wit-bindgen. You can inspect the bindings.

You can also use the wasi crate . Also, these instructions and example should be helpful https://github.com/sunfishcode/hello-wasi-http