initial prereqs commit

Author: mkatychev

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

component-model/src/language-support/rust.md

@@ -1,59 +1,106 @@
 # Components in Rust
 
-Rust has first-class support for the component model via [the `cargo component` tool](https://github.com/bytecodealliance/cargo-component). It is a `cargo` subcommand for
-creating WebAssembly components using Rust as the component's implementation language.
+Rust has first-class support for the component model via the [`cargo-component`
+tool](https://github.com/bytecodealliance/cargo-component). We will be using
+the `cargo component` subcommand to create WebAssembly components using Rust as
+the component's implementation language.
 
-## Installing `cargo component`
+> [!NOTE]
+> You can find more details about `cargo-component` on [crates.io](https://crates.io/crates/cargo-component).
 
-To install `cargo component`, run:
+## Prerequisites
 
+Install [`cargo-component`](https://github.com/bytecodealliance/cargo-component#installation):
 ```sh
-cargo install cargo-component
+cargo install --locked cargo-component
+```
+Install [`wasm-tools`](https://github.com/bytecodealliance/wasm-tools#installation):
+```sh
+cargo install --locked wasm-tools
+```
+Install [`wasmtime`](https://github.com/bytecodealliance/wasmtime#installation):
+```sh
+curl https://wasmtime.dev/install.sh -sSf | bash
+```
+Clone the [component-docs](https://github.com/bytecodealliance/component-docs) repo:
+```sh
+git clone https://github.com/bytecodealliance/component-docs
 ```
-
-> You can find more details about `cargo component` in its [crates.io page](https://crates.io/crates/cargo-component).
 
 ## Building a Component with `cargo component`
 
-Create a Rust library that implements the `add` function in the [`example`
-world](https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/example-host/add.wit). First scaffold a project:
+We will create a component in Rust that implements the `add` function exported
+by the [`example:component/example`][example-component] world in the
+`example:component`
+[package](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#package-names).
 
+First `cd` into the `tutorial` directory found in the repo we just cloned:
+```sh
+cd component-docs/component-model/examples/tutorial
+```
+
+Now create a new WebAssembly component package called `add`:
 ```sh
 $ cargo component new add --lib && cd add
 ```
 
-Note that `cargo component` generates the necessary bindings as a module called `bindings`. 
+> [!NOTE]
+> `cargo-component` generates the necessary bindings for us in a module called `bindings` found in `src/bindings.rs`.
+
+Next change our generated `wit/world.wit` to match `example:component`:
+```wit
+{{#include ../../examples/example-host/add.wit}}
+```
 
-Next, update `wit/world.wit` to match `add.wit` and modify the component package reference to change the
-package name to `example:component`. The `component` section of `Cargo.toml` should look like the following:
+Since our WIT file changed names (from `component:add` to
+`example:component`) this needs to be reflected in our `Cargo.toml`,
+let's change the `package.metadata.component.package` string to `"example:component"`:
 
 ```toml
 [package.metadata.component]
 package = "example:component"
 ```
 
-`cargo component` will generate bindings for the world specified in a package's `Cargo.toml`. In particular, it will create a `Guest` trait that a component should implement. Since our `example` world has no interfaces, the trait lives directly under the bindings module. Implement the `Guest` trait in `add/src/lib.rs` such that it satisfies the `example` world, adding an `add` function:
+`cargo component` will generate bindings for the
+`example:component/example` world we specified `Cargo.toml`, it will also
+create a `Guest` trait that a component can implement.
+Since our `example:component/example` world has no interfaces, our
+generated `Guest` trait lives at the top of the `bindings` module.
+
+Implementing the `Guest` trait for our `Component` struct requires us
+to match the structure specified by `example:component/example`, we do this by
+implementing the `add` method with the equivalent function signature. Our
+`src/lib.rs` should look similar to the following:
 
 ```rs
+mod bindings;
+
 struct Component;
 
 impl Guest for Component {
     fn add(x: i32, y: i32) -> i32 {
         x + y
     }
 }
+
+bindings::export!(Component with_types_in bindings);
 ```
 
-Now, use `cargo component` to build the component, being sure to optimize with a release build.
+Now, let's build our component with release optimizations:
 
 ```sh
-$ cargo component build --release
+cargo component build --release
 ```
 
-You can use `wasm-tools component wit` to output the WIT package of the component:
+You can use `wasm-tools` to inspect the WIT package generated by `cargo-component`:
 
 ```sh
-$ wasm-tools component wit target/wasm32-wasip1/release/add.wasm
+wasm-tools component wit target/wasm32-wasip1/release/add.wasm
+```
+
+The command above should produce the output below:
+
+```wit
 package root:component;
 
 world root {
@@ -64,7 +111,7 @@ world root {
 ### Running a Component from Rust Applications
 
 To verify that our component works, lets run it from a Rust application that knows how to run a
-component targeting the [`example` world](https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/example-host/add.wit).
+component targeting the [`example:component/example` world](#example-component).
 
 The application uses [`wasmtime`](https://github.com/bytecodealliance/wasmtime) crates to generate
 Rust bindings, bring in WASI worlds, and execute the component.
@@ -77,41 +124,30 @@ $ cargo run --release -- 1 2 ../add/target/wasm32-wasip1/release/add.wasm
 
 ## Exporting an interface with `cargo component`
 
-The [sample `add.wit` file](https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/example-host/add.wit) exports a function. However, you'll often prefer to export an interface, either to comply with an existing specification or to capture a set of functions and types that tend to go together. For example, to implement the following world:
+Notice how our `example` world currently exports `add` as a function. It's
+often preferable to export an interface rather than a function, either to
+comply with an existing specification or to capture several functions and types
+at once.
+For example, to implement the [`docs:adder/adder`][docs-adder] world:
 
 ```wit
-package docs:[email protected];
-
-interface add {
-    add: func(a: u32, b: u32) -> u32;
-}
-
-world adder {
-    export add;
-}
+{{#include ../../examples/tutorial/wit/adder/world.wit}}
 ```
 
 you would write the following Rust code:
 
 ```rust
-mod bindings;
-// Separating out the interface puts it in a sub-module
-use bindings::exports::docs::adder::add::Guest;
-
-struct Component;
-
-impl Guest for Component {
-    fn add(a: u32, b: u32) -> u32 {
-        a + b
-    }
-}
+{{#include ../../examples/tutorial/adder/src/lib.rs}}
 ```
 
 ## Importing an interface with `cargo component`
 
 The world file (`wit/world.wit`) generated for you by `cargo component new --lib` doesn't specify any imports.
 
-> `cargo component build`, by default, uses the Rust `wasm32-wasi` target, and therefore automatically imports any required WASI interfaces - no action is needed from you to import these. This section is about importing custom WIT interfaces from library components.
+> [!NOTE]
+> This section is about importing custom WIT interfaces from library components.
+> By default, `cargo component build` imports any required [WASI interfaces](https://wasi.dev/interfaces)
+> for us without needing to explicitly declare them.
 
 If your component consumes other components, you can edit the `world.wit` file to import their interfaces.
 
@@ -139,10 +175,13 @@ Because the `docs:adder` package is in a different project, we must first tell `
 
 ```toml
 [package.metadata.component.target.dependencies]
-"docs:adder" = { path = "../adder/wit" }  # directory containing the WIT package
+"docs:adder" = { path = "../wit/adder" }  # directory containing the WIT package
 ```
 
-Note that the path is to the adder project's WIT _directory_, not to the `world.wit` file. A WIT package may be spread across multiple files in the same directory; `cargo component` will look at all the files.
+> [!NOTE]
+> The path for `docs:adder` is relative to the `wit` _directory_, not to the `world.wit` file.
+>
+> A WIT package may be spread across multiple files in the same directory; `cargo component` will search them all.
 
 ### Calling the import from Rust
 
@@ -534,3 +573,6 @@ If you are hosting a Wasm runtime, you can export a resource from your host for
         // etc.
     }
     ```
+
+[example-component]: https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/example-host/add.wit
+[docs-adder]: https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/tutorial/wit/adder/world.wit