From f1e0402a67f5a19434384b5ae2dc574c2043a87e Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Tue, 15 Jul 2025 15:48:14 -0700 Subject: [PATCH 1/3] Revise introduction --- component-model/src/SUMMARY.md | 4 ++-- component-model/src/introduction.md | 33 ++++++++++++++++++++-------- component-model/src/reference/faq.md | 2 +- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/component-model/src/SUMMARY.md b/component-model/src/SUMMARY.md index 8f685fd6..bdad6f04 100644 --- a/component-model/src/SUMMARY.md +++ b/component-model/src/SUMMARY.md @@ -3,7 +3,7 @@ - [Introduction](./introduction.md) -# Understanding Component Model +# Understanding WebAssembly Components - [Why the Component Model?](./design/why-component-model.md) - [Component Model Concepts](./design/component-model-concepts.md) @@ -13,7 +13,7 @@ - [Packages](./design/packages.md) - [WIT Reference](./design/wit.md) -# Using Component Model +# Using WebAssembly Components - [Language Support for Components](./language-support.md) - [C/C++](./language-support/c.md) diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index 8cc6212c..7b33e8eb 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -2,6 +2,14 @@ The WebAssembly Component Model is a broad-reaching architecture for building interoperable WebAssembly libraries, applications, and environments. +This documentation is aimed at _users_ of the component model: developers of libraries and applications. +> [!NOTE] +> +> _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. + +## Table of contents + | Understanding components | Building components | Using components | |--------------------------|----------------------|-------------------| | [Why Components?] | [C/C++] | [Composing] | @@ -27,17 +35,24 @@ The WebAssembly Component Model is a broad-reaching architecture for building in [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. -> -> _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. -## Status +## APIs for building WebAssembly components + +It's useful to have a standard, shared set of APIs +that WebAssembly components can depend on. +[WASI](https://wasi.dev/) (the WebAssembly System Interface) is a standards-track specification +that defines these APIs. +A system or platform may expose some or all of the WASI APIs to components. + +### 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 any stable release >= `v0.2.0`. See [WASI.dev](https://wasi.dev) to stay up to date on the latest releases. +The current stable release of WASI is [WASI 0.2.0](https://github.com/WebAssembly/WASI/pull/577), +which was released on January 25, 2024. +WASI 0.2.0 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`. +The [WASI.dev roadmap](https://wasi.dev/roadmap) tracks upcoming releases. ## Contributing diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index adacc836..3bfba489 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -143,7 +143,7 @@ The component is said to "export" the `example-interface` interface, making avai ## Still have questions? Please contribute to the Component Book by filing your question (or one that you think should be covered here) as -[an issue on GitHub][gh-issues]. +[an issue on GitHub][gh-issues-new]. [gh-issues-new]: https://github.com/bytecodealliance/component-docs/issues/new From 38af0f29b3b510c6db544ce135e12cc681d8f3a5 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Tue, 15 Jul 2025 16:21:36 -0700 Subject: [PATCH 2/3] Update component-model/src/introduction.md Co-authored-by: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> --- component-model/src/introduction.md | 1 + 1 file changed, 1 insertion(+) diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index 7b33e8eb..e3f4f5d4 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -3,6 +3,7 @@ The WebAssembly Component Model is a broad-reaching architecture for building interoperable WebAssembly libraries, applications, and environments. This documentation is aimed at _users_ of the component model: developers of libraries and applications. + > [!NOTE] > > _Compiler and Wasm runtime developers_ can take a look at the [Component Model specification](https://github.com/WebAssembly/component-model) to From 2da3ade84e6f3b8d2f53d05e5e6be3a182357d82 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Tue, 15 Jul 2025 17:07:23 -0700 Subject: [PATCH 3/3] More detail on platforms / what APIs are for --- component-model/src/introduction.md | 31 +++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/component-model/src/introduction.md b/component-model/src/introduction.md index e3f4f5d4..1ed749b9 100644 --- a/component-model/src/introduction.md +++ b/component-model/src/introduction.md @@ -37,8 +37,39 @@ This documentation is aimed at _users_ of the component model: developers of lib [Distributing]: ./composing-and-distributing/distributing.md +## WebAssembly components + +As with all programming, the goal of writing a component +is to make new functionality available +by building it out of existing functionality. + +A WebAssembly component runs on a _platform_, +which may be a Web browser, +a stand-alone runtime, +or even an operating system (when compiling WebAssembly to an executable). +By running the component, the platform gains the functionality +that the component implements. +Likewise, the platform provides functionality +that code in components can use to interact +with the outside world. + +For example: + +- A user of the component model can build a component + that converts the system time to another time zone. +- For the component to work as intended, the underlying platform + must provide the component with a means to access + the current system time and the system time zone. + ## APIs for building WebAssembly components +In general, a platform that runs components +must provide well-defined APIs for accessing functionality +that components need: +for example, reading from standard input, +accessing environment variables, +or manipulating network sockets. + It's useful to have a standard, shared set of APIs that WebAssembly components can depend on. [WASI](https://wasi.dev/) (the WebAssembly System Interface) is a standards-track specification