diff --git a/component-model/.gitignore b/component-model/.gitignore index 0623c43a..a6481744 100644 --- a/component-model/.gitignore +++ b/component-model/.gitignore @@ -1,2 +1,4 @@ book .spin +# package created from component tutorial +examples/tutorial/add diff --git a/component-model/examples/example-host/README.md b/component-model/examples/example-host/README.md index 651d66ca..67e543ef 100644 --- a/component-model/examples/example-host/README.md +++ b/component-model/examples/example-host/README.md @@ -35,7 +35,7 @@ $ cargo run --release -- 1 2 add.wasm ``` > [!NOTE] -> `add.wasm` is available in thsi folder, but can be replaced with your own built WebAssembly component +> `add.wasm` is available in this folder, but can be replaced with your own built WebAssembly component > at any time (written in any language that supports WebAssembly Components), given that it satisfies > the `adder` world described above. diff --git a/component-model/examples/tutorial/README.md b/component-model/examples/tutorial/README.md index 54c37f2e..3ea8c159 100644 --- a/component-model/examples/tutorial/README.md +++ b/component-model/examples/tutorial/README.md @@ -54,7 +54,7 @@ wac plug command/target/wasm32-wasip1/release/command.wasm --plug composed.wasm Now, run the component with Wasmtime: -```sh +```console wasmtime run final.wasm 1 2 add 1 + 2 = 3 ``` @@ -84,12 +84,12 @@ package example:composition; let adder-instance = new docs:adder-impl { }; // Instantiate the calculator-impl component that implements the calculator world. -// In the `new` expression, specify the source of the `add` import to be `adder-instance`'s `add` export. +// In the `new` expression, specify the source of the `add` import to be `adder-instance`'s `add` export. let calculator-instance = new docs:calculator-impl { add: adder-instance.add }; // Instantiate a command-impl component that implements the app world. -// The command component might import other interfaces, such as WASI interfaces, but we want to leave -// those as imports in the final component, so supply `...` to allow those other imports to remain unresolved. +// The command component might import other interfaces, such as WASI interfaces, but we want to leave +// those as imports in the final component, so supply `...` to allow those other imports to remain unresolved. // The command's exports (in this case, `wasi:cli/run`) remain unaffected in the resulting instance. let command-instance = new docs:command-impl { calculate: calculator-instance.calculate,... }; @@ -101,7 +101,7 @@ export command-instance["wasi:cli/run@0.2.0"]; Now, perform your composition by passing the WAC file to `wac compose`. ```sh -wac compose composition.wac -o final.wasm +wac compose composition.wac -o final.wasm ``` > Note, instead of moving all the components to a `deps/docs` directory, you can pass the paths to the components inline diff --git a/component-model/src/creating-and-consuming/composing.md b/component-model/src/creating-and-consuming/composing.md index 168cb3fc..89fb8ca2 100644 --- a/component-model/src/creating-and-consuming/composing.md +++ b/component-model/src/creating-and-consuming/composing.md @@ -57,13 +57,13 @@ You can use the [WAC](https://github.com/bytecodealliance/wac) CLI to compose co To perform quick and simple compositions, use the `wac plug` command. `wac plug` satisfies the import of a "socket" component by plugging a "plug" component's export into the socket. For example, a component that implements the [`validator` world above](#what-is-composition) needs to satisfy it's `match` import. It is a socket. While a component that implements the `regex` world, exports the `match` interface, and can be used as a plug. `wac plug` can plug a regex component's export into the validator component's import, creating a resultant composition: -```sh +```console wac plug validator-component.wasm --plug regex-component.wasm -o composed.wasm ``` A component can also be composed with two components it depends on. -```sh +```console wac plug path/to/component.wasm --plug path/to/dep1.wasm --plug path/to/dep2.wasm -o composed.wasm ``` @@ -94,7 +94,7 @@ export validator...; Then, `wac compose` can be used to compose the components, passing in the paths to the components. Alternatively, you can place the components in a `deps` directory with an expected structure, and in the near future, you will be able to pull in components from registries. See the [`wac` documentation](https://github.com/bytecodealliance/wac) for more details. -```sh +```console wac compose --dep docs:regex-impl=regex-component.wasm --dep docs:validator-impl=validator-component.wasm -o composed.wasm composition.wac ``` diff --git a/component-model/src/creating-and-consuming/running.md b/component-model/src/creating-and-consuming/running.md index a76398b6..cd031916 100644 --- a/component-model/src/creating-and-consuming/running.md +++ b/component-model/src/creating-and-consuming/running.md @@ -8,7 +8,7 @@ You must use a recent version of `wasmtime` ([`v14.0.0` or greater](https://gith To run your component, run: -```sh +```console wasmtime run ``` diff --git a/component-model/src/language-support.md b/component-model/src/language-support.md index 1eb02c53..69eb5a4f 100644 --- a/component-model/src/language-support.md +++ b/component-model/src/language-support.md @@ -79,7 +79,7 @@ working with WebAssembly modules and components. 4. Use `wasm-tools` to create a component from the core module, first embedding component metadata inside the core module and then encoding the WAT to a Wasm binary. - ```sh + ```console $ wasm-tools component embed adder/world.wit add.wat -o add.wasm $ wasm-tools component new add.wasm -o add.component.wasm ``` diff --git a/component-model/src/language-support/csharp.md b/component-model/src/language-support/csharp.md index de2009a3..127adf68 100644 --- a/component-model/src/language-support/csharp.md +++ b/component-model/src/language-support/csharp.md @@ -26,7 +26,7 @@ You should also have [wasmtime](https://wasmtime.dev/) installed so you can run Once you have the .NET SDK installed, create a new project: -```sh +```console dotnet new install BytecodeAlliance.Componentize.DotNet.Templates dotnet new componentize.wasi.cli -o adder cd adder @@ -106,7 +106,7 @@ public class AdderWorldImpl : IAdderWorld Then, we can build our component: -```sh +```console dotnet build ``` @@ -199,7 +199,7 @@ public class AddImpl : IAdd Once again, compile an application to a Wasm component using `dotnet build`: -```sh +```console $ dotnet build Restore complete (0.4s) You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy @@ -223,7 +223,7 @@ Now we will be taking the `adder` component and executing it from another WebAss Back out of the current project and create a new one: -```sh +```console cd .. dotnet new componentize.wasi.cli -o host-app cd host-app @@ -275,7 +275,7 @@ Console.WriteLine($"{left} + {right} = {result}"); Once again, compile your component with `dotnet build`: -```sh +```console $ dotnet build Restore complete (0.4s) You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy @@ -293,7 +293,7 @@ Since the `host-app` component depends on the `add` function which is defined in world, it needs to be composed the first component. You can compose your `host-app` component with your `adder` component by running [`wac plug`](https://github.com/bytecodealliance/wac): -```sh +```console wac plug \ bin/Debug/net10.0/wasi-wasm/native/host-app.wasm \ --plug ../adder/bin/Debug/net10.0/wasi-wasm/native/adder.wasm \ @@ -317,7 +317,7 @@ Run `dotnet build` again you will have a composed component in `./dist/main.wasm Then you can run the composed component: -```sh +```console wasmtime run ./dist/main.wasm 1 + 2 = 3 ``` diff --git a/component-model/src/language-support/javascript.md b/component-model/src/language-support/javascript.md index b0640bae..eb17eec8 100644 --- a/component-model/src/language-support/javascript.md +++ b/component-model/src/language-support/javascript.md @@ -216,7 +216,7 @@ With `jco transpile` any WebAssembly binary (compiled from any language) can be Reactor components are WebAssembly components that are long running and meant to be called repeatedly over time. They're analogous to libraries of functionality rather than an executable (a "command" component). -Components expose their interfaces via [WebAssembly Interface Types][docs-wit], hand-in-hand with the [Component Model][docs-component-model] which enables components to use higher level types interchangably. +Components expose their interfaces via [WebAssembly Interface Types][docs-wit], hand-in-hand with the [Component Model][docs-component-model] which enables components to use higher level types interchangeably. [docs-wit]: ../design/wit.md @@ -312,7 +312,7 @@ You should see output like the following: OK Successfully written string-reverse.wasm. ``` -Now that we have a WebAssembly binary, we can *also* use `jco` to run it in a native JavaScript context by *transpiling* the WebAsssembly binary (which could have come from anywhere!) to a JavaScript module. +Now that we have a WebAssembly binary, we can *also* use `jco` to run it in a native JavaScript context by *transpiling* the WebAssembly binary (which could have come from anywhere!) to a JavaScript module. ```console npx jco transpile string-reverse.wasm -o dist/transpiled diff --git a/component-model/src/language-support/python.md b/component-model/src/language-support/python.md index cbe5a805..bc2cf907 100644 --- a/component-model/src/language-support/python.md +++ b/component-model/src/language-support/python.md @@ -7,7 +7,7 @@ application to a WebAssembly component. First, install [Python 3.10 or later](https://www.python.org/) and [pip](https://pypi.org/project/pip/) if you don't already have them. Then, install `componentize-py`: -```sh +```console pip install componentize-py ``` @@ -28,7 +28,7 @@ world adder { If you want to generate bindings produced for the WIT world (for an IDE or typechecker), you can generate them using the `bindings` subcommand. Specify the path to the WIT interface with the world you are targeting: -```sh +```console $ componentize-py --wit-path wit/component/wit --world adder bindings . ``` @@ -61,7 +61,7 @@ Component built successfully To test the component, run it using the [Rust `add` host](./rust.md#creating-a-command-component-with-cargo-component): -```sh +```console $ cd component-model/examples/add-host $ cargo run --release -- 1 2 ../path/to/add.wasm 1 + 2 = 3 @@ -99,7 +99,7 @@ class Add(example.Example): Once again, compile an application to a Wasm component using the `componentize` subcommand: -```sh +```console $ componentize-py --wit-path add-interface.wit --world example componentize app -o add.wasm Component built successfully ``` @@ -113,13 +113,13 @@ to call the [pre-built `app.wasm` component][add-wasm] in the examples. First, install [Python 3.11 or later](https://www.python.org/) and [pip](https://pypi.org/project/pip/) if you don't already have them. Then, install [`wasmtime-py`](https://github.com/bytecodealliance/wasmtime-py): -```sh +```console $ pip install wasmtime ``` First, generate the bindings to be able to call the component from a Python host application. -```sh +```console # Get an add component that does not import the WASI CLI world $ wget https://github.com/bytecodealliance/component-docs/raw/main/component-model/examples/example-host/add.wasm $ python3 -m wasmtime.bindgen add.wasm --out-dir add @@ -146,7 +146,7 @@ if __name__ == '__main__': Run the Python host program: -```sh +```console $ python3 host.py 1 + 2 = 3 ``` diff --git a/component-model/src/language-support/rust.md b/component-model/src/language-support/rust.md index f03e531b..7f379f51 100644 --- a/component-model/src/language-support/rust.md +++ b/component-model/src/language-support/rust.md @@ -9,7 +9,7 @@ using Rust as the component's implementation language. To install `cargo component`, run: -```sh +```console cargo install cargo-component ``` @@ -21,7 +21,7 @@ Create a Rust library that implements the `add` function in the [`adder`world][a First scaffold a project: -```sh +```console $ cargo component new add --lib && cd add ``` @@ -114,7 +114,7 @@ component targeting the [`adder` world][adder-wit]. The application uses [`wasmtime`](https://github.com/bytecodealliance/wasmtime) crates to generate Rust bindings, bring in WASI worlds, and execute the component. -```sh +```console $ cd examples/example-host $ cargo run --release -- 1 2 ../add/target/wasm32-wasip1/release/add.wasm 1 + 2 = 3 @@ -240,7 +240,7 @@ A _command_ is a component with a specific export that allows it to be executed To create a command with cargo component, run: -```sh +```console cargo component new ``` @@ -256,7 +256,7 @@ You can write Rust in this project, just as you normally would, including import To run your command component: -```sh +```console cargo component build wasmtime run ./target/wasm32-wasip1/debug/.wasm ``` @@ -313,7 +313,7 @@ As mentioned above, `cargo component build` doesn't generate a WIT file for a co 6. Run the composed component: - ```sh + ```console $ wasmtime run ./my-composed-command.wasm 1 + 1 = 579 # might need to go back and do some work on the calculator implementation ``` diff --git a/component-model/src/runtimes/jco.md b/component-model/src/runtimes/jco.md index 6c61f305..e9444013 100644 --- a/component-model/src/runtimes/jco.md +++ b/component-model/src/runtimes/jco.md @@ -4,7 +4,7 @@ To run a component with `jco`, run: -```sh +```console jco run ``` diff --git a/component-model/src/runtimes/wasmtime.md b/component-model/src/runtimes/wasmtime.md index d0a3b471..e86c6e52 100644 --- a/component-model/src/runtimes/wasmtime.md +++ b/component-model/src/runtimes/wasmtime.md @@ -5,7 +5,7 @@ ## Running command components with Wasmtime To run a command component with Wasmtime, execute: -```sh +```console wasmtime run ``` @@ -15,10 +15,10 @@ By default, Wasmtime denies the component access to all system resources. For ex ## Running HTTP components with Wasmtime -You can now execute components that implement the [HTTP proxy world](https://github.com/WebAssembly/wasi-http/blob/main/wit/proxy.wit) with the `wasmtime serve` subcommand. [The Wasmtime CLI](https://github.com/bytecodealliance/wasmtime) supports serving these components as of `v14.0.3`. +You can now execute components that implement the [HTTP proxy world](https://github.com/WebAssembly/wasi-http/blob/main/wit/proxy.wit) with the `wasmtime serve` subcommand. [The Wasmtime CLI](https://github.com/bytecodealliance/wasmtime) supports serving these components as of `v14.0.3`. To run a HTTP component with Wasmtime, execute: -```sh +```console wasmtime serve ``` diff --git a/component-model/src/tutorial.md b/component-model/src/tutorial.md index c4f35428..ace3e355 100644 --- a/component-model/src/tutorial.md +++ b/component-model/src/tutorial.md @@ -145,17 +145,17 @@ For reference, see a completed [example](https://github.com/bytecodealliance/com ## Composing the calculator Now, we are ready to bring our components together into one runnable calculator component, using -`wac`. +`wac`. We will: 1. Compose the calculator component with the add component to satisfy the calculator component's `adder` import -2. Compose that resolved calculator component once more with the command component to satisfy the command component's `calculate` import. +2. Compose that resolved calculator component once more with the command component to satisfy the command component's `calculate` import. The result is a fully-formed command component that has all its imports satisfied and has a single export (the `wasi:cli/run` interface), which can be executed by [`wasmtime`][wasmtime]. -```sh +```console wac plug calculator.wasm --plug adder.wasm -o composed.wasm wac plug command.wasm --plug composed.wasm -o final.wasm ``` @@ -168,7 +168,7 @@ Now it all adds up! Run the final component with the `wasmtime` CLI, ensuring yo [recent release][wasmtime-releases] (`v14.0.0` or greater), as earlier releases of the `wasmtime` CLI do not include component model support. -``` +```console wasmtime run final.wasm 1 2 add 1 + 2 = 3 ```