Complete the tutorial please

[justjoheinz]

https://component-model.bytecodealliance.org/composing-and-distributing/distributing.html

the last sentence on the page reads:

Now, you can use the language toolchain of your choice to generate bindings and create your component.

That leaves an otherwise very useful tutorial quite incomplete, at least I was happy to find a tutorial which covered the (at least for me) newer tools cargo component and wkg. I finally managed to access wit definitions for wasi:cli and from my own packages using wkg wit fetch. They now live in the wit directory of my project:

wit
├── deps
│   ├── wasi-cli-0.2.8
│   │   └── package.wit
│   ├── wasi-clocks-0.2.8
│   │   └── package.wit
│   ├── wasi-filesystem-0.2.8
│   │   └── package.wit
│   ├── wasi-io-0.2.8
│   │   └── package.wit
│   ├── wasi-random-0.2.8
│   │   └── package.wit
│   ├── wasi-sockets-0.2.8
│   │   └── package.wit
│   └── wasm-common-fibonacci-0.1.0
│       └── package.wit
└── world.wit

Now I somehow need to tell Cargo.toml how to deal with this. So far the only solution I managed to get working is to have a Cargo.toml which looks like:

[package]
name = "fib-cli"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]

[package.metadata.component]
package = "component:fib-cli"

[package.metadata.component.dependencies]

[package.metadata.component.target.dependencies]
"wasm-common:fibonacci" = { path = "wit/deps/wasm-common-fibonacci-0.1.0" }
"wasi:cli" = { path = "wit/deps/wasi-cli-0.2.8" }
"wasi:io" = { path = "wit/deps/wasi-io-0.2.8" }
"wasi:clocks" = { path = "wit/deps/wasi-clocks-0.2.8" }
"wasi:filesystem" = { path = "wit/deps/wasi-filesystem-0.2.8" }
"wasi:sockets" = { path = "wit/deps/wasi-sockets-0.2.8" }
"wasi:random" = { path = "wit/deps/wasi-random-0.2.8" }

this somehow does not look right - why do I have to repeat all the information? I understand that the tooling is evolving, however this still does not seem right. Having an authorative source for the build process on page mentioned above would be excellent. Given that the rust tooling is certainly among the most popular in the WASM world, it would also benefit a lot of people.

I also wonder - the wkg wit build steps builds a wasm file, containing a wit description. Is that of any use for my local build problem?

[vados-cosmonic]

Hey @justjoheinz with regards to wkg, you can actually use wkg wit fetch -- that will pull down the wit files without actually building a wasm component. Official WASI WITs will be pulled automatically, but if you have any custom interfaces, you'd have to configure wkg.toml to get it to be able to find the appropriate WITs.

We have a PR outstanding that reworks the Rust guide, but unfortunately it hasn't merged yet

[justjoheinz]

@vados-cosmonic : I have been reading most of the PR you pointed out. In the meantime I also made some progress in understanding all the different tools involved, and believe that the PR is going in the right direction. I wouldn't mind if it is verbose and detailed, going from use case to use case, as the component model (and tooling) is evolving so fast, so that it is hard to find a good (not-outdated) resource.

In this spirit, I believe it would be important to illustrate how to build a component, how to use a WASI component, how to reference another non-wasi component, how to make all that available to others. I think most of the issues are addressed in the PR, with the exception of publishing maybe?

[vados-cosmonic]

In this spirit, I believe it would be important to illustrate how to build a component, how to use a WASI component, how to reference another non-wasi component, how to make all that available to others. I think most of the issues are addressed in the PR, with the exception of publishing maybe?

Glad to hear that -- yes, publishing isn't covered in the guide, but it is closer to the sections on distribution

If we can get the PR merged, we should be a in a much better place! Hopefully we can get some reviews in (that's what we're waiting on now) and that can happen this week.

[justjoheinz]

In the building a simple component section it mentions:
!WARNING Building with --release removes all debug-related information from the resulting .wasm file.

What it does not mention though, or I have configured something wrongly, is that it also changes the wit world considerably. A dbeug build imports a lot more packages then a release build. Isn't that something which we do not wish as composing debug builds and release builds would be different then?

the above just as an example, but it is these magic steps which leave me wanting more information and not knowing where to find it.

[itowlson]

@justjoheinz This is a good catch. What's going on is Rust release builds doing dead code elimination - thus, pruning imports that are not used on any code path - but it can be surprising to see and good to mention.

(For me the surprise is more when I look at a debug build and it imports a whole truckload of interfaces that I never went anywhere near!)

[vados-cosmonic]

Hey @justjoheinz I'm closing this since we've landed the new guide, looking forward to feedback on it (feel free to post here if it's worth re-opening this PR, or make a new issue for other bugs/usability issues).

Thanks again for reporting the issues -- I appreciate it and hope the new docs are an improvement for you.