Registry tooling and wac #129
Conversation
|
The relevant PRs have been merged now, so the tools should work as indicated in the proposed changes (when building from main, I don't believe new releases have occurred yet). In the SIG Docs group there was some conversation about if some of the information about Also... it seems this PR has some goals in common with the changes proposed here. Specifically this PR splits wit packages and publishes them to a registry. It also covers how to use example components that have been published to the registry in a composition, as well as how the user can compose their own components that they've published. Still having a think on it... but it seems that since both split up wit across multiple packages, perhaps they should do so the same way. |
macovedj
force-pushed
the
registry
branch
2 times, most recently
from
934f515
to
10e3dc4
Compare
|
Removed a lot of the details covered in the README's for the tools referenced. Think this is ready for review at this point. |
| @@ -43,6 +52,12 @@ wasm-tools compose calculator/target/wasm32-wasi/release/calculator.wasm -d adde | |||
| wasm-tools compose command/target/wasm32-wasi/release/command.wasm -d composed.wasm -o command.wasm | |||
| ``` | |||
|
|
|||
| You can also use `wac` instead of `wasm-tools compose` if you would like to fetch these components from a registry instead: | |||
There was a problem hiding this comment.
Would it make sense for us to remove wasm-tools compose completely given bytecodealliance/wasm-tools#1564?
| @@ -1,12 +1,29 @@ | |||
| # Building a Calculator of Wasm Components | |||
|
|
|||
| This tutorial walks through how to compose a component to build a Wasm calculator. | |||
| It is a rich example of using multiple components, targeting distinct worlds described across multiple WIT packages | |||
There was a problem hiding this comment.
| It is a rich example of using multiple components, targeting distinct worlds described across multiple WIT packages | |
| This example uses multiple components that target distinct worlds defined across multiple WIT packages. |
| export add; | ||
| } | ||
| ``` | ||
|
|
||
| The WIT package for the calculator consists of a world for each mathematical operator | ||
| add an `op` enum that delineates each operator. The following example interface only |
There was a problem hiding this comment.
| add an `op` enum that delineates each operator. The following example interface only | |
| and an `op` enum that delineates each operator. The following example interface only |
| export add; | ||
| } | ||
| ``` | ||
|
|
||
| The WIT package for the calculator consists of a world for each mathematical operator |
There was a problem hiding this comment.
| The WIT package for the calculator consists of a world for each mathematical operator | |
| The second WIT package defines the calculator which consists of a world for each mathematical operator |
| You can also use `wac` instead of `wasm-tools compose` if you would like to fetch these components from a registry instead: | ||
|
|
||
| ``` | ||
| wac plug component-book:calculator-impl --plug component-book:adder-impl -o composed.wasm && wac plug component-book:command-impl --plug ./composed.wasm -o command.wasm |
There was a problem hiding this comment.
nit: let's break up the invocations on to two lines for readability.
| One of the primary use cases of a Warg registry is publishing and downloading WIT packages. The easiest way to create and use WIT packages is with the [wit](https://github.com/bytecodealliance/cargo-component/tree/main/crates/wit) CLI. After installing the CLI, you can use it to create WIT packages that depend on other packages in a registry, as well as to build a final binary and publish the result to a registry | ||
|
|
||
| ## Using Warg registries to author and distribute components | ||
| Another tool that is set up to interact with warg registries is `cargo-component`. You can read about how to build and use published packages in your rust projects in the [rust](../language-support/rust.md) section. Components authored with other tools and languages can also be published to the registry, but have less support for importing/exporting functionality between components today. In general, given a .wasm binary, you can always publish and download using the [warg cli](https://github.com/bytecodealliance/registry?tab=readme-ov-file#installation) |
There was a problem hiding this comment.
| Another tool that is set up to interact with warg registries is `cargo-component`. You can read about how to build and use published packages in your rust projects in the [rust](../language-support/rust.md) section. Components authored with other tools and languages can also be published to the registry, but have less support for importing/exporting functionality between components today. In general, given a .wasm binary, you can always publish and download using the [warg cli](https://github.com/bytecodealliance/registry?tab=readme-ov-file#installation) | |
| Another tool that is set up to interact with warg registries is `cargo-component`. You can read about how to build and use published packages in your Rust projects in the [Rust](../language-support/rust.md) section. Components authored with other tools and languages can also be published to the registry, but have less support for importing/exporting functionality between components today. In general, given a .wasm binary, you can always publish and download using the [warg cli](https://github.com/bytecodealliance/registry?tab=readme-ov-file#installation) |
| @@ -111,6 +111,11 @@ impl Guest for Component { | |||
| } | |||
| ``` | |||
|
|
|||
| ## Exporting an interface from a registry with `cargo component` | |||
There was a problem hiding this comment.
nit:
| ## Exporting an interface from a registry with `cargo component` | |
| ## Exporting an interface from a registry with `cargo component` | |
| } | ||
| ``` | ||
|
|
||
| As the import is unfulfilled, the `calculator.wasm` component could not run by itself in its current form. To fulfill the `add` import, so that only `calculate` is exported, you would need to [compose the `calculator.wasm` with some `exports-add.wasm` into a single, self-contained component](../creating-and-consuming/composing.md). | ||
| As the import is unfulfilled, the `calculator.wasm` component could not run by itself in its current form. To fulfill the `add` import, so that only `calculate` is exported, you would need to [compose the `calculator.wasm` with some `exports-add.wasm` into a single, self-contained component](../creating-and-consuming/composing.md), or use the [wac CLI](../creating-and-consuming/composing.md#composing-components-with-the-wac-cli). |
There was a problem hiding this comment.
or use the [wac CLI]
This doesn't really make sense as using the wac CLI is a way to compose components which is what was already suggested. So I think this should be removed.
component-model/src/tutorial.md
Outdated
| @@ -15,8 +15,10 @@ Wasm components, we will compose them into a single runnable component, and test | |||
|
|
|||
| ## The calculator interface | |||
|
|
|||
| For tutorial purposes, we are going to define all our interfaces in one WIT package (in fact, one | |||
| `.wit` file). This file defines: | |||
| <!-- For tutorial purposes, we are going to define all our interfaces in one WIT package (in fact, one | |||
There was a problem hiding this comment.
Why are we keeping this as a comment?
component-model/src/tutorial.md
Outdated
|
|
||
| You'll notice in the [wit examples](https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/tutorial/wit) that we have definitions in the `local` folder that resolve packages locally, as well as packages that were authored using the [wit](https://github.com/bytecodealliance/cargo-component/tree/main/crates/wit) CLI, which resolves packages using the registry. | ||
|
|
||
| If you're using rust and you want to learn how to use a registry instead of the local files, you can use the WIT packages that have been published for this tutorial ([calculator](https://preview.wa.dev/component-book:calculator) and [adder](https://preview.wa.dev/component-book:adder)) or publish the same packages on your own namespace using the [wit CLI](./creating-and-consuming/distributing.md#using-warg-registries-for-wit-packages-with-the-wit-cli) |
There was a problem hiding this comment.
| If you're using rust and you want to learn how to use a registry instead of the local files, you can use the WIT packages that have been published for this tutorial ([calculator](https://preview.wa.dev/component-book:calculator) and [adder](https://preview.wa.dev/component-book:adder)) or publish the same packages on your own namespace using the [wit CLI](./creating-and-consuming/distributing.md#using-warg-registries-for-wit-packages-with-the-wit-cli) | |
| If you're using Rust, and you want to learn how to use a registry instead of the local files, you can use the WIT packages that have been published for this tutorial ([calculator](https://preview.wa.dev/component-book:calculator) and [adder](https://preview.wa.dev/component-book:adder)) or publish the same packages on your own namespace using the [wit CLI](./creating-and-consuming/distributing.md#using-warg-registries-for-wit-packages-with-the-wit-cli) |
… of preview in examples
|
We talked about this a bit in the TSC meeting today, since it touches on interesting aspects for Bytecode Alliance hosted activities. What we realized is that we think that content hosted by the Bytecode Alliance should be vendor-neutral when it comes to anything directly relevant to the Bytecode Alliance's mission and principles. We're looking into how best to document this as a general policy, but in the meantime I wanted to give a heads-up about how it impacts the content here. Specifically, we concluded that examples and documentation shouldn't rely on workflows that are only possible with proprietary products or services in the domain the Bytecode Alliance operates in, nor should they showcase such products or services over alternatives. As such, we think the documentation and examples here shouldn't rely on the wa.dev registry, and would like to request those to be changed before this PR is merged. I want to emphasize that this isn't in any way about wa.dev specifically: the same principles would apply to documentation or examples showing how to deploy components to a proprietary hosting platform, for example. (To give a completely unrelated historical example of a change that we discussed and agreed would also be required by this policy, if for slightly different reasons: this very project initially relied on Fermyon's Spin runtime, and Fermyon's hosting platform, but has since been changed to use GitHub Pages instead. While none of the user-visible content showed that anything proprietary was used, and while the change back then wasn't made to achieve alignment with a policy, in our discussion today we agreed that this use of Fermyon's product would not be compliant with the policy, as it would force everyone contributing to this project to use said product, giving it a preferential position. [Which wasn't the intent behind the original approach, but in hindsight would've been a result.]) |
Makes sense! I'll have a go at reducing the changes to those that introduce |
Added instructions for tools that have registry support, (
cargo-component,wit, andwac). The tools that have registry support have a few different assumptions about how both WIT packages and components are referenced, so I had to change some of the existing examples a bit.That being said I'm not sure if we want to continue to encourage users to perform composition using some of the old flows anymore (
wasm-composemay end up being replaced bywac, in which case UI based composition may look a bit different?).I figure these changes are a good starting point for a discussion about these topics, which may lead to more changes in the examples. Also opening as a draft as there are some pending code changes that will be needed in order for users to have multiple namespaces in their compositions... namely bytecodealliance/cargo-component#275, bytecodealliance/wac#91, bytecodealliance/registry#263. The docs should probably not be updated until these get merged.