diff --git a/component-model/book.toml b/component-model/book.toml index 72ef7f32..d72758b8 100644 --- a/component-model/book.toml +++ b/component-model/book.toml @@ -10,6 +10,15 @@ git-repository-url = "https://github.com/bytecodealliance/component-docs/tree/ma edit-url-template = "https://github.com/bytecodealliance/component-docs/tree/main/component-model/{path}" additional-css = ["theme/head.hbs"] +[output.html.redirect] +"/creating-and-consuming/composing.html" = "/composing-and-distributing/composing.html" +"/creating-and-consuming/distributing.html" = "/composing-and-distributing/distributing.html" +"/creating-and-consuming/running.html" = "/running-components.html" +"/creating-and-consuming/authoring.html" = "/language-support.html" +"/creating-and-consuming.html" = "/language-support.html" +"/runtimes/wasmtime.html" = "/running-components/wasmtime.html" +"/runtimes/jco.html" = "/running-components/jco.html" + [preprocessor.alerts] [output.linkcheck] diff --git a/component-model/src/SUMMARY.md b/component-model/src/SUMMARY.md index c8c45fdc..8f685fd6 100644 --- a/component-model/src/SUMMARY.md +++ b/component-model/src/SUMMARY.md @@ -22,18 +22,14 @@ - [JavaScript](./language-support/javascript.md) - [Python](./language-support/python.md) - [Rust](./language-support/rust.md) -- [Creating and Consuming Components](./creating-and-consuming.md) - - [Authoring Components](./creating-and-consuming/authoring.md) - - [Composing Components](./creating-and-consuming/composing.md) - - [Running Components](./creating-and-consuming/running.md) - - [Distributing and Fetching Components and WIT](./creating-and-consuming/distributing.md) +- [Running Components](./running-components.md) + - [Wasmtime](./running-components/wasmtime.md) + - [jco](./running-components/jco.md) +- [Consuming and Distributing Components](./composing-and-distributing.md) + - [Composing Components](./composing-and-distributing/composing.md) + - [Distributing and Fetching Components and WIT](./composing-and-distributing/distributing.md) - [Tutorial](./tutorial.md) -# Runtime Support - -- [Wasmtime](./runtimes/wasmtime.md) -- [jco](./runtimes/jco.md) - # Advanced Topics - [Canonical ABI](./advanced/canonical-abi.md) diff --git a/component-model/src/creating-and-consuming.md b/component-model/src/composing-and-distributing.md similarity index 87% rename from component-model/src/creating-and-consuming.md rename to component-model/src/composing-and-distributing.md index c608f30c..8a351668 100644 --- a/component-model/src/creating-and-consuming.md +++ b/component-model/src/composing-and-distributing.md @@ -1,3 +1,3 @@ -# Creating and Consuming Components +# Composing and Distributing Components The component model defines how components interface to each other and to hosts. This section describes how to work with components - from authoring them in custom code or by composing existing components, through to using them in applications and distributing them via registries. diff --git a/component-model/src/creating-and-consuming/composing.md b/component-model/src/composing-and-distributing/composing.md similarity index 100% rename from component-model/src/creating-and-consuming/composing.md rename to component-model/src/composing-and-distributing/composing.md diff --git a/component-model/src/creating-and-consuming/distributing.md b/component-model/src/composing-and-distributing/distributing.md similarity index 100% rename from component-model/src/creating-and-consuming/distributing.md rename to component-model/src/composing-and-distributing/distributing.md diff --git a/component-model/src/creating-and-consuming/authoring.md b/component-model/src/creating-and-consuming/authoring.md deleted file mode 100644 index 4e207188..00000000 --- a/component-model/src/creating-and-consuming/authoring.md +++ /dev/null @@ -1,5 +0,0 @@ -# Authoring Components - -You can write WebAssembly core modules in a wide variety of languages, and the set of languages that can directly create components is growing. See the [Language Support](../language-support.md) section for information on building components directly from source code. - -If your preferred language supports WebAssembly but not components, you can still create components using the [`wasm-tools component`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wit-component) tool. (A future version of this page will cover this in more detail.) \ No newline at end of file diff --git a/component-model/src/creating-and-consuming/running.md b/component-model/src/creating-and-consuming/running.md deleted file mode 100644 index a76398b6..00000000 --- a/component-model/src/creating-and-consuming/running.md +++ /dev/null @@ -1,31 +0,0 @@ -# Running Components - -You can "run" a component by calling one of its exports. In some cases, this requires a custom host. For "command" components, though, you can use the `wasmtime` command line. This can be a convenient tool for testing components and exploring the component model. Other runtimes are also available - see the "Runtimes" section of the sidebar for more info. - -> A "command" component is one that exports the `wasi:cli/run` interface, and imports only interfaces listed in the [`wasi:cli/command` world](https://github.com/WebAssembly/wasi-cli/blob/main/wit/command.wit). - -You must use a recent version of `wasmtime` ([`v14.0.0` or greater](https://github.com/bytecodealliance/wasmtime/releases)), as earlier releases of the `wasmtime` command line do not include component model support. - -To run your component, run: - -```sh -wasmtime run -``` - -## Running components with custom exports - -If you're writing a library-style component - that is, one that exports a custom API - then you can run it in `wasmtime` by writing a "command" component that imports and invokes your custom API. By [composing](./composing.md) the command and the library, you can exercise the library in `wasmtime`. - -1. Write your library component. The component's world (`.wit` file) must export an interface and/or one or more functions through which a consumer can call it. See the [language support guide](../language-support.md) for how to implement an export. - -2. Build your library component to a `.wasm` file. - -3. Write your command component. The component's world (`.wit` file) must import the interface or functions exported from the library. Write the command to call the library's API. See the [language support guide](../language-support.md) for how to call an imported interface. - -4. Build your command component to a `.wasm` file. You will not be able to run this in `wasmtime` yet, as its imports are not yet satisfied. - -5. Compose your command component with your library component by running `wac plug --plug -o main.wasm`. - -6. Run the composed component using `wasmtime run main.wasm` - -See [Composing Components](./composing.md) for more details. diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index 8d0546e6..8cc6212c 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -23,9 +23,9 @@ The WebAssembly Component Model is a broad-reaching architecture for building in [Python]: ./language-support/python.md [Rust]: ./language-support/rust.md -[Composing]: ./creating-and-consuming/composing.md -[Running]: ./creating-and-consuming/running.md -[Distributing]: ./creating-and-consuming/distributing.md +[Composing]: ./composing-and-distributing/composing.md +[Running]: ./running-components.md +[Distributing]: ./composing-and-distributing/distributing.md > [!NOTE] >This documentation is aimed at _users_ of the component model: developers of libraries and applications. diff --git a/component-model/src/language-support.md b/component-model/src/language-support.md index 1eb02c53..b1bc1084 100644 --- a/component-model/src/language-support.md +++ b/component-model/src/language-support.md @@ -89,5 +89,4 @@ working with WebAssembly modules and components. You can "run" a component by calling one of its exports. Hosts and runtimes often only support running components with certain exports. The [`wasmtime`](https://github.com/bytecodealliance/wasmtime) CLI can only run "command" components, so in order to run the `add` function above, it first must be composed with a primary "command" component -that calls it. See [documentation on running components](./creating-and-consuming/running.md) for -more details. +that calls it. See [documentation on running components](./running-components/wasmtime.md) for more details. diff --git a/component-model/src/language-support/javascript.md b/component-model/src/language-support/javascript.md index 9e9b0690..2390306f 100644 --- a/component-model/src/language-support/javascript.md +++ b/component-model/src/language-support/javascript.md @@ -54,7 +54,7 @@ download a pre-existing interface that defines what your component should do. The [`adder` world][adder-world] contains an interface with a single `add` function that sums two numbers: ```wit -{{#include ../../exmaples/tutorial/wit/adder/world.wit}} +{{#include ../../examples/tutorial/wit/adder/world.wit}} ``` > [!NOTE] diff --git a/component-model/src/language-support/rust.md b/component-model/src/language-support/rust.md index 5bfed024..165bd39d 100644 --- a/component-model/src/language-support/rust.md +++ b/component-model/src/language-support/rust.md @@ -207,7 +207,7 @@ world root { ``` 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 `adder.wasm` into a single, self-contained component](../creating-and-consuming/composing.md). +only `calculate` is exported, you would need to [compose the `calculator.wasm` with some `adder.wasm` into a single, self-contained component](../composing-and-distributing/composing.md). ## Creating a command component with `cargo component` @@ -284,7 +284,7 @@ As mentioned above, `cargo component build` doesn't generate a WIT file for a co } ``` -5. [Compose the command component with the `.wasm` components that implement the imports.](../creating-and-consuming/composing.md) +5. [Compose the command component with the `.wasm` components that implement the imports.](../composing-and-distributing/composing.md) 6. Run the composed component: @@ -488,7 +488,7 @@ To use the calculator engine in another component, that component must import th } ``` -You can now build the command component and [compose it with the `.wasm` component that implements the resource.](../creating-and-consuming/composing.md). You can then run the composed command with `wasmtime run`. +You can now build the command component and [compose it with the `.wasm` component that implements the resource.](../composing-and-distributing/composing.md). You can then run the composed command with `wasmtime run`. ### Implementing and exporting a resource implementation in a host diff --git a/component-model/src/running-components.md b/component-model/src/running-components.md new file mode 100644 index 00000000..fef5e190 --- /dev/null +++ b/component-model/src/running-components.md @@ -0,0 +1,3 @@ +# Running Components + +There are two standard wit worlds that runtimes support. These worlds are the [`wasi:cli/command` world](https://github.com/WebAssembly/wasi-cli/blob/main/wit/command.wit) and the [`wasi:http/proxy` world](https://github.com/WebAssembly/wasi-http/blob/main/wit/proxy.wit). All other wit worlds and interfaces are considered to be custom. In the following sections, you'll see how to run components that implement either world, as well as how to invoke custom exports. \ No newline at end of file diff --git a/component-model/src/runtimes/jco.md b/component-model/src/running-components/jco.md similarity index 100% rename from component-model/src/runtimes/jco.md rename to component-model/src/running-components/jco.md diff --git a/component-model/src/runtimes/wasmtime.md b/component-model/src/running-components/wasmtime.md similarity index 68% rename from component-model/src/runtimes/wasmtime.md rename to component-model/src/running-components/wasmtime.md index d0a3b471..a75a220e 100644 --- a/component-model/src/runtimes/wasmtime.md +++ b/component-model/src/running-components/wasmtime.md @@ -1,6 +1,6 @@ # Wasmtime -[Wasmtime](https://github.com/bytecodealliance/wasmtime/) is the reference implementation of the Component Model. It supports running components that implement the [`wasi:cli/command` world](https://github.com/WebAssembly/wasi-cli/blob/main/wit/command.wit) and serving components that implement the [`wasi:http/proxy` world](https://github.com/WebAssembly/wasi-http/blob/main/wit/proxy.wit). +[Wasmtime](https://github.com/bytecodealliance/wasmtime/) is the reference implementation of the Component Model. It supports running components that implement the [`wasi:cli/command` world](https://github.com/WebAssembly/wasi-cli/blob/main/wit/command.wit) and serving components that implement the [`wasi:http/proxy` world](https://github.com/WebAssembly/wasi-http/blob/main/wit/proxy.wit). Wasmtime can also invoke functions exported from a component. ## Running command components with Wasmtime To run a command component with Wasmtime, execute: @@ -27,3 +27,14 @@ Try out building and running HTTP components with one of these tutorials 1. [Hello WASI HTTP tutorial](https://github.com/sunfishcode/hello-wasi-http) - build and serve a simple Rust-based HTTP component 2. [HTTP Auth Middleware tutorial](https://github.com/fermyon/http-auth-middleware#running-with-wasmtime) - compose a HTTP authentication middleware component with a business logic component + +## Running components with custom exports +As of Wasmtime Version 33.0.0, there is [support for invoking components with custom exports](https://bytecodealliance.org/articles/invoking-component-functions-in-wasmtime-cli). + + +As an example, if your component exports a function `add` which takes two numeric arguments, you can make use of this feature with the following command. + +```sh +wasmtime run --invoke 'foo(1, 2)' +``` +Make sure to wrap your invocation in single quotes abd to include parentheses, even if your function doesn't take any arguments. For a full list of ways to represent the various wit types when passing arguments to your exported function, visit the [WAVE repo](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-wave). \ No newline at end of file diff --git a/component-model/src/tutorial.md b/component-model/src/tutorial.md index c4f35428..60b4244a 100644 --- a/component-model/src/tutorial.md +++ b/component-model/src/tutorial.md @@ -79,8 +79,7 @@ These files define: ## Create an `add` component -Reference the [language guide](language-support.md) and [authoring components -documentation](creating-and-consuming/authoring.md) to create a component that implements the +Reference the [language guide](language-support.md) to create a component that implements the `adder` world of `adder/wit/world.wit`. For reference, see the completed @@ -88,8 +87,7 @@ For reference, see the completed ## Create a `calculator` component -Reference the [language guide](language-support.md) and [authoring components -documentation](creating-and-consuming/authoring.md) to create a component that implements the +Reference the [language guide](language-support.md) to create a component that implements the `calculator` world of `wit/calculator/world.wit`. For reference, see the completed @@ -160,7 +158,7 @@ wac plug calculator.wasm --plug adder.wasm -o composed.wasm wac plug command.wasm --plug composed.wasm -o final.wasm ``` -> If you'd prefer to take a more visual approach to composing components, see the [documentation on composing components with wasmbuilder.app](creating-and-consuming/composing.md#composing-components-with-a-visual-interface). +> If you'd prefer to take a more visual approach to composing components, see the [documentation on composing components with wasmbuilder.app](composing-and-distributing/composing.md#composing-components-with-a-visual-interface). ## Running the calculator