From 160ebedf1b1498b7c178d53e1c87945f79848fe8 Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Tue, 20 May 2025 11:45:33 +0900 Subject: [PATCH 1/6] refactor: add overview to introduction Signed-off-by: Victor Adossi Co-authored-by: itowlson --- component-model/src/introduction.md | 44 ++++++++++++++++++-- component-model/src/language-support/rust.md | 2 + 2 files changed, 43 insertions(+), 3 deletions(-) diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index ca1b113b..ef09b8f4 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -1,6 +1,6 @@ # Home -The WebAssembly Component Model is a broad-reaching architecture for building interoperable Wasm libraries, applications, and environments. +The WebAssembly Component Model is a broad-reaching architecture for building interoperable WebAssembly libraries, applications, and environments. | Understanding components | Building components | Using components | |--------------------------|----------------------|-------------------| @@ -27,14 +27,52 @@ The WebAssembly Component Model is a broad-reaching architecture for building in [Running]: ./creating-and-consuming/running.md [Distributing]: ./creating-and-consuming/distributing.md -> This documentation is aimed at _users_ of the component model: developers of libraries and applications. _Compiler and Wasm runtime developers_ can take a look at the [Component Model specification](https://github.com/WebAssembly/component-model) to see how to add support for the component model to their project. +> [!NOTE] +>This documentation is aimed at _users_ of the component model: developers of libraries and applications. +> +> _Compiler and Wasm runtime developers_ can take a look at the [Component Model specification](https://github.com/WebAssembly/component-model) to +> see how to add support for the component model to their project. + +## A quick overview of core concepts + +This section introduces the core concepts and [rationale](./design/why-component-model.md) of the component model. + +* A [WebAssembly Component](./design/components.md) is the next evolution of core WebAssembly binaries. + * WebAssembly components are *nestable* -- they may contain one or more core modules and/or sub-components composed together. +* The Component Model extends core WebAssembly by introducing higher level types and interface-driven development + * [WebAssembly Interface Types (WIT)][wit] is the [IDL (Interface Definition Language)][wiki-idl] used to formally define functionality for WebAssembly modules. + * With WIT, WebAssembly components gain the ability to conform an language-agnostic and encode that support, so any WebAssembly component binary can be interrogated *and* executed. + * An [Interface](./design/interfaces.md) describes the types and functions used for a specific, focused bit of functionality. + * A [World](./design/worlds.md) assembles interfaces to express what features a component offers, and what features it depends on. + * A [Package](./design/packages.md) is a set of WIT files containing a related set of interfaces and worlds. +* The Component Model introduces the idea of a "platform" to core WebAssembly -- enabling the structured, standardized use of "host" functionality for WebAssembly "guest"s. + * The WebAssembly System Interface (WASI) defines in WIT a family of interfaces for common system-level functions. + * WASI defines common execution environments such as the command line (`wasi:cli`) or a HTTP server (`wasi:http`). +* The Component Model introducs makes core WebAssembly composable -- components that provide functionality and those that use them can be composed together into *one* resulting component + +> [!NOTE] +> The Component Model is stewarded by the Bytecode Alliance and designed [in the open][cm-repo]. +> +> See the [`WebAssembly/component-model`][cm-repo] repository for [Goals][goals],[use cases][use-cases], and [high level design choices][design-choices]. + +[cm-repo]: https://github.com/WebAssembly/component-model +[wiki-idl]: https://en.wikipedia.org/wiki/Web_IDL +[goals]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Goals.md +[use-cases]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/UseCases.md +[design-choices]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Choices.md +[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md ## Status -[WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model. This [is a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2) that components can target. WASI proposals will continue to evolve and new ones will be introduced; however, users of the component model can now pin to the stable 0.2.0 release. +[WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model. +This [is a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2) that components can target. WASI proposals will +continue to evolve and new ones will be introduced; however, users of the component model can now pin to the stable 0.2.0 release. ## Contributing If you find a mistake, omission, ambiguity, or other problem, please let us know via [GitHub issues](https://github.com/bytecodealliance/component-docs/issues). If you'd like to contribute content to the guide, please see the [contribution guide](https://github.com/bytecodealliance/component-docs/blob/main/CONTRIBUTING.md) for information on how to contribute. + +[!NOTE]: # +[!WARNING]: # diff --git a/component-model/src/language-support/rust.md b/component-model/src/language-support/rust.md index ceecc827..5bfed024 100644 --- a/component-model/src/language-support/rust.md +++ b/component-model/src/language-support/rust.md @@ -559,3 +559,5 @@ If you are hosting a Wasm runtime, you can export a resource from your host for [cargo-component]: https://github.com/bytecodealliance/cargo-component [cargo-component-install]: https://github.com/bytecodealliance/cargo-component#install [docs-adder]: https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/tutorial/wit/adder/world.wit +[!NOTE]: # +[!WARNING]: # From 1e1955db1cb5dfaeeb7e3107ef5ee2c8456f6e82 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Wed, 21 May 2025 01:31:23 +0900 Subject: [PATCH 2/6] fix: phrasing for released versions in intro Co-authored-by: Kate Goldenring --- component-model/src/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index ef09b8f4..c8c0f361 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -66,7 +66,7 @@ This section introduces the core concepts and [rationale](./design/why-component [WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model. This [is a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2) that components can target. WASI proposals will -continue to evolve and new ones will be introduced; however, users of the component model can now pin to the stable 0.2.0 release. +continue to evolve and new ones will be introduced; however, users of the component model can now pin to any stable release >= 0.2.0. See WASI.dev to stay up to date on the latest releases. ## Contributing From be9909d582b1d2d7cc8881ee649b0ffb0170e851 Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Wed, 21 May 2025 23:53:34 +0900 Subject: [PATCH 3/6] refactor: create new component model concepts section Signed-off-by: Victor Adossi --- component-model/src/SUMMARY.md | 11 +++---- .../src/design/component-model-concepts.md | 30 +++++++++++++++++++ component-model/src/introduction.md | 30 ------------------- 3 files changed, 36 insertions(+), 35 deletions(-) create mode 100644 component-model/src/design/component-model-concepts.md diff --git a/component-model/src/SUMMARY.md b/component-model/src/SUMMARY.md index 26fe0bf1..ccf9ecb0 100644 --- a/component-model/src/SUMMARY.md +++ b/component-model/src/SUMMARY.md @@ -6,11 +6,12 @@ # Understanding Component Model - [Why the Component Model?](./design/why-component-model.md) -- [Components](./design/components.md) -- [Interfaces](./design/interfaces.md) -- [Worlds](./design/worlds.md) -- [WIT](./design/wit.md) -- [Packages](./design/packages.md) +- [Component Model concepts](./design/component-model-concepts.md) + - [Components](./design/components.md) + - [Interfaces](./design/interfaces.md) + - [Worlds](./design/worlds.md) + - [Packages](./design/packages.md) +- [WIT Reference](./design/wit.md) # Using Component Model diff --git a/component-model/src/design/component-model-concepts.md b/component-model/src/design/component-model-concepts.md new file mode 100644 index 00000000..ce15a58e --- /dev/null +++ b/component-model/src/design/component-model-concepts.md @@ -0,0 +1,30 @@ +## Component Model Concepts + +This section introduces the core concepts and [rationale](./why-component-model.md) of the component model. + +* A [WebAssembly Component](./components.md) is the next evolution of core WebAssembly binaries. + * WebAssembly components are *nestable* -- they may contain one or more core modules and/or sub-components composed together. +* The Component Model extends core WebAssembly by introducing higher level types and interface-driven development + * [WebAssembly Interface Types (WIT)][wit] is the [IDL (Interface Definition Language)][wiki-idl] used to formally define functionality for WebAssembly modules. + * With WIT, WebAssembly components gain the ability to conform an language-agnostic and encode that support, so any WebAssembly component binary can be interrogated *and* executed. + * An [Interface](./interfaces.md) describes the types and functions used for a specific, focused bit of functionality. + * A [World](./worlds.md) assembles interfaces to express what features a component offers, and what features it depends on. + * A [Package](./packages.md) is a set of WIT files containing a related set of interfaces and worlds. +* The Component Model introduces the idea of a "platform" to core WebAssembly -- enabling the structured, standardized use of "host" functionality for WebAssembly "guest"s. + * The WebAssembly System Interface (WASI) defines in WIT a family of interfaces for common system-level functions. + * WASI defines common execution environments such as the command line (`wasi:cli`) or a HTTP server (`wasi:http`). +* The Component Model introducs makes core WebAssembly composable -- components that provide functionality and those that use them can be composed together into *one* resulting component + +> [!NOTE] +> The Component Model is stewarded by the Bytecode Alliance and designed [in the open][cm-repo]. +> +> See the [`WebAssembly/component-model`][cm-repo] repository for [Goals][goals],[use cases][use-cases], and [high level design choices][design-choices]. + +[cm-repo]: https://github.com/WebAssembly/component-model +[wiki-idl]: https://en.wikipedia.org/wiki/Web_IDL +[goals]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Goals.md +[use-cases]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/UseCases.md +[design-choices]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Choices.md +[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md + +[!NOTE]: # diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index c8c0f361..ce31554b 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -33,35 +33,6 @@ The WebAssembly Component Model is a broad-reaching architecture for building in > _Compiler and Wasm runtime developers_ can take a look at the [Component Model specification](https://github.com/WebAssembly/component-model) to > see how to add support for the component model to their project. -## A quick overview of core concepts - -This section introduces the core concepts and [rationale](./design/why-component-model.md) of the component model. - -* A [WebAssembly Component](./design/components.md) is the next evolution of core WebAssembly binaries. - * WebAssembly components are *nestable* -- they may contain one or more core modules and/or sub-components composed together. -* The Component Model extends core WebAssembly by introducing higher level types and interface-driven development - * [WebAssembly Interface Types (WIT)][wit] is the [IDL (Interface Definition Language)][wiki-idl] used to formally define functionality for WebAssembly modules. - * With WIT, WebAssembly components gain the ability to conform an language-agnostic and encode that support, so any WebAssembly component binary can be interrogated *and* executed. - * An [Interface](./design/interfaces.md) describes the types and functions used for a specific, focused bit of functionality. - * A [World](./design/worlds.md) assembles interfaces to express what features a component offers, and what features it depends on. - * A [Package](./design/packages.md) is a set of WIT files containing a related set of interfaces and worlds. -* The Component Model introduces the idea of a "platform" to core WebAssembly -- enabling the structured, standardized use of "host" functionality for WebAssembly "guest"s. - * The WebAssembly System Interface (WASI) defines in WIT a family of interfaces for common system-level functions. - * WASI defines common execution environments such as the command line (`wasi:cli`) or a HTTP server (`wasi:http`). -* The Component Model introducs makes core WebAssembly composable -- components that provide functionality and those that use them can be composed together into *one* resulting component - -> [!NOTE] -> The Component Model is stewarded by the Bytecode Alliance and designed [in the open][cm-repo]. -> -> See the [`WebAssembly/component-model`][cm-repo] repository for [Goals][goals],[use cases][use-cases], and [high level design choices][design-choices]. - -[cm-repo]: https://github.com/WebAssembly/component-model -[wiki-idl]: https://en.wikipedia.org/wiki/Web_IDL -[goals]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Goals.md -[use-cases]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/UseCases.md -[design-choices]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Choices.md -[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md - ## Status [WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model. @@ -75,4 +46,3 @@ If you find a mistake, omission, ambiguity, or other problem, please let us know If you'd like to contribute content to the guide, please see the [contribution guide](https://github.com/bytecodealliance/component-docs/blob/main/CONTRIBUTING.md) for information on how to contribute. [!NOTE]: # -[!WARNING]: # From b0686432eca01978848d5adbfbc43ab1e9f961fe Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 22 May 2025 00:20:19 +0900 Subject: [PATCH 4/6] fix: capitalization Co-authored-by: Kate Goldenring --- component-model/src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/SUMMARY.md b/component-model/src/SUMMARY.md index ccf9ecb0..cb1af074 100644 --- a/component-model/src/SUMMARY.md +++ b/component-model/src/SUMMARY.md @@ -6,7 +6,7 @@ # Understanding Component Model - [Why the Component Model?](./design/why-component-model.md) -- [Component Model concepts](./design/component-model-concepts.md) +- [Component Model Concepts](./design/component-model-concepts.md) - [Components](./design/components.md) - [Interfaces](./design/interfaces.md) - [Worlds](./design/worlds.md) From ed068e951fa6233946e595d45b4b443e975cc70f Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 22 May 2025 00:20:36 +0900 Subject: [PATCH 5/6] fix: version tag Co-authored-by: Kate Goldenring --- component-model/src/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index ce31554b..ae0cd5fc 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -37,7 +37,7 @@ The WebAssembly Component Model is a broad-reaching architecture for building in [WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model. This [is a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2) that components can target. WASI proposals will -continue to evolve and new ones will be introduced; however, users of the component model can now pin to any stable release >= 0.2.0. See WASI.dev to stay up to date on the latest releases. +continue to evolve and new ones will be introduced; however, users of the component model can now pin to any stable release >= `v0.2.0`. See [WASI.dev](www.wasi.dev) to stay up to date on the latest releases. ## Contributing From c188b9f9be3067374501c210e0b6597257953cbd Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Thu, 22 May 2025 00:27:15 +0900 Subject: [PATCH 6/6] fix: wasi dev link Signed-off-by: Victor Adossi --- component-model/src/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index ae0cd5fc..c840f67a 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -37,7 +37,7 @@ The WebAssembly Component Model is a broad-reaching architecture for building in [WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model. This [is a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2) that components can target. WASI proposals will -continue to evolve and new ones will be introduced; however, users of the component model can now pin to any stable release >= `v0.2.0`. See [WASI.dev](www.wasi.dev) to stay up to date on the latest releases. +continue to evolve and new ones will be introduced; however, users of the component model can now pin to any stable release >= `v0.2.0`. See [WASI.dev](https://www.wasi.dev) to stay up to date on the latest releases. ## Contributing