From 374cba8df7ec5bd50425f1b4e120955a191b31ae Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Mon, 30 Jun 2025 19:17:54 +0900 Subject: [PATCH 01/28] feat: add FAQ section This commit adds the beginnings of an FAQ section Signed-off-by: Victor Adossi --- component-model/src/SUMMARY.md | 1 + component-model/src/reference/faq.md | 127 +++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 component-model/src/reference/faq.md diff --git a/component-model/src/SUMMARY.md b/component-model/src/SUMMARY.md index cb1af074..c8c45fdc 100644 --- a/component-model/src/SUMMARY.md +++ b/component-model/src/SUMMARY.md @@ -40,4 +40,5 @@ # Reference +- [Frequently Asked Questions (FAQ)](./reference/faq.md) - [Useful Links](./reference/useful-links.md) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md new file mode 100644 index 00000000..305e4855 --- /dev/null +++ b/component-model/src/reference/faq.md @@ -0,0 +1,127 @@ +# Frequently Asked Questions (FAQ) + +This page hosts a series of questions that are frequently asked or that might be confusing about +WebAssembly (core), components, and the WebAssembly ecosystem as a whole. + +## Q: What is the difference between a WebAssembly component and a WebAssembly module? + +A WebAssembly module (more precisely referred to as a "WebAssembly core module") is a +binary that conforms to the [WebAssembly Core Specification][wasm-core-spec]. + +A WebAssembly component refers to a WebAssembly core module that has been wrapped in +the [Canonical ABI][cabi], i.e. the binary contract for the Component Model. By adhering to the +canonical ABI, WebAssembly components can take advantage of all the features the Component Model +has to offer. + +WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules +*cannot not* contain Components. One easy way to differentiate is by reading the WAT for a component: + +A WebAssembly core module generally starts with a `(module)` s-expression: +```wat +(module + ... +) +``` + +A WebAssembly component starts with the `(component)` s-expression: + +```wat +(component + ... +) +``` + +One part that might cause confusion here is that a WebAssembly Preview 1 "component" is in fact a +*core module*. More precisely, a Preview 1 "component" is a WebAssembly core module with a well-defined +set of exports ([specified in WITX][wasi-p1]). + +[cabi]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md +[wasi-p1]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/witx/wasi_snapshot_preview1.witx +[wasm-core-spec]: https://webassembly.github.io/spec/core/ + +## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other? + +WebAssembly core components do not have any access to the host system (by design) -- they can only perform +computations on a fixed set of types. The component model enables core components to interact with the "outside" +world via a rich set of types ([WebAssembly Interface Types][wit]). + +The WebAssembly System Interface (WASI) is a *standardization* of the interfaces, functions and types that +a system or platform can expose to a WebAssembly component. At a glance, many parts of WASI are UNIX-like, +in that they match traditional expectations for programs like STDIN, STDOUT, and writing to files. + +Some WASI system interfaces work at a much higher level than the command line however, like +[`wasi:http`][wasi-http]. `wasi:http` is included as a standardized platform due to the ubiquity +of the internet and the common use case of WebAssembly components with "the web" as a platform. + +With WIT, platform builders can define *any* interface to be *your* system interfaces that WebAssembly components can +expect to access -- WASI is a standardized set which enables to build on a shared base set of abstractions. + +[wit]: https://component-model.bytecodealliance.org/design/wit.html +[wasi-http]: https://github.com/WebAssembly/wasi-http + +## Q: I see the terms Preview 1 and Preview 2 frequently. What do those refer to? + +Preview 1 refers to the first iteration of the Component Model which was based on WITX and is now deprecated: + +https://github.com/WebAssembly/WASI/tree/main/legacy + +Preview 2 refers to a newer iteration of the Component Model which uses WebAssembly Interface Types (WIT): + +https://github.com/WebAssembly/WASI/tree/main/wasip2 + +Many programming language toolchains may only support Preview 1 components natively, but this isn't a problem +in practice as Preview 1 components can be *adapted* into Preview 2 components automatically. + +## Q: What are component imports? + +WebAssembly components represent a new kind of binary that can *describe* its interface or expected usage natively. +This means that WebAssembly components have functionality that they might *import* (e.g. `wasi:cli/environment`). + +Imports are easiest illustrated with WIT: + +```wit +package example-namespace:example-package; + +world example-world { + import wasi:cli/environment@0.2.4; +} +``` + +The [`environment` interface in `wasi:cli`][wasi-cli-env] provides various types and functions for interacting with +environment variables. + +The component is said to "import" the `wasi:cli/environment` interface, using the available functions and types therein. + +[wasi-cli-env]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/environment.wit + +## Q: What are component exports? + +WebAssembly components represent a new kind of binary that can *describe* it's expected usage natively. This means that +WebAssembly components have functionality that they *export*, which users of the component (e.g. another component, or +a WebAssembly host) can use. + +Exports are easiest illustrated with WIT: + +```wit +package example-namespace:example-package; + +interface example-interface { + say-hello: func(name: string) -> string; +} + +world example-world { + export example-interface; +} +``` + +For the component that inhabits the `example-world` defined above, the outside world can expect the WebAssembly binary to +have a `say-hello` function that is callable via the `example-namespace:example-package/example-interface` interface. + +The component is said to "export" the `example-interface` interface, making available the functions and types therein. + +## 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]. + +[gh-issues-new]: https://github.com/bytecodealliance/component-docs/issues/new From 958607474a7aa5f9af407c4fc802b1de2e1a8994 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 00:25:23 +0900 Subject: [PATCH 02/28] fix: improve emphasis in question title Co-authored-by: Mikhail Katychev --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 305e4855..ce860d9e 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -3,7 +3,7 @@ This page hosts a series of questions that are frequently asked or that might be confusing about WebAssembly (core), components, and the WebAssembly ecosystem as a whole. -## Q: What is the difference between a WebAssembly component and a WebAssembly module? +## Q: What is the difference between a _component_ and _module_ in WebAssembly? A WebAssembly module (more precisely referred to as a "WebAssembly core module") is a binary that conforms to the [WebAssembly Core Specification][wasm-core-spec]. From 93c6c7cb01d83849777109859025a27ab425f4bd Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 00:25:59 +0900 Subject: [PATCH 03/28] fix: comment out ellipsis in wat Co-authored-by: Mikhail Katychev --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index ce860d9e..8a7d9165 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -19,7 +19,7 @@ WebAssembly Components can (and often do) contain core modules, but generally We A WebAssembly core module generally starts with a `(module)` s-expression: ```wat (module - ... + ;; ... ) ``` From d10761dfde0116748ea93a764d467d52976f4800 Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Thu, 3 Jul 2025 00:26:33 +0900 Subject: [PATCH 04/28] fix: comment out component WAT ellipsis Signed-off-by: Victor Adossi --- component-model/src/reference/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 8a7d9165..078d758e 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -12,7 +12,7 @@ A WebAssembly component refers to a WebAssembly core module that has been wrappe the [Canonical ABI][cabi], i.e. the binary contract for the Component Model. By adhering to the canonical ABI, WebAssembly components can take advantage of all the features the Component Model has to offer. - +} WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules *cannot not* contain Components. One easy way to differentiate is by reading the WAT for a component: @@ -27,7 +27,7 @@ A WebAssembly component starts with the `(component)` s-expression: ```wat (component - ... + ;; ... ) ``` From 6d9d06f3198f249792673c95e068be0f72a379f3 Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Thu, 3 Jul 2025 00:30:42 +0900 Subject: [PATCH 05/28] fix: wording on s-expressions Signed-off-by: Victor Adossi --- component-model/src/reference/faq.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 078d758e..9de23afc 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -16,14 +16,15 @@ has to offer. WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules *cannot not* contain Components. One easy way to differentiate is by reading the WAT for a component: -A WebAssembly core module generally starts with a `(module)` s-expression: +A WebAssembly core module generally consists of a `(module)` s-expression: ```wat (module ;; ... ) ``` -A WebAssembly component starts with the `(component)` s-expression: +A WebAssembly component generally consists of a `(component)` s-expression (and may contain +nested `(module)`/`(component)` s-expressions): ```wat (component From 83b4fd7830d6a4a1bd646b5cfa778db9e64c1cec Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:31:40 +0900 Subject: [PATCH 06/28] fix: it's -> its Co-authored-by: itowlson --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 9de23afc..69bde063 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -97,7 +97,7 @@ The component is said to "import" the `wasi:cli/environment` interface, using th ## Q: What are component exports? -WebAssembly components represent a new kind of binary that can *describe* it's expected usage natively. This means that +WebAssembly components represent a new kind of binary that can *describe* its expected usage natively. This means that WebAssembly components have functionality that they *export*, which users of the component (e.g. another component, or a WebAssembly host) can use. From d676fedc5abb4d5c82529e3c8ee2e4d3fe671d8e Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:37:46 +0900 Subject: [PATCH 07/28] fix: remove errant brace --- component-model/src/reference/faq.md | 1 - 1 file changed, 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 69bde063..6e190789 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -12,7 +12,6 @@ A WebAssembly component refers to a WebAssembly core module that has been wrappe the [Canonical ABI][cabi], i.e. the binary contract for the Component Model. By adhering to the canonical ABI, WebAssembly components can take advantage of all the features the Component Model has to offer. -} WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules *cannot not* contain Components. One easy way to differentiate is by reading the WAT for a component: From 2ac73d7de34879ca5639eaf5cda976b902e7dbed Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:38:17 +0900 Subject: [PATCH 08/28] fix: webassembly -> wasi --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 6e190789..1d7d5401 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -31,7 +31,7 @@ nested `(module)`/`(component)` s-expressions): ) ``` -One part that might cause confusion here is that a WebAssembly Preview 1 "component" is in fact a +One part that might cause confusion here is that a WASI Preview 1 "component" is in fact a *core module*. More precisely, a Preview 1 "component" is a WebAssembly core module with a well-defined set of exports ([specified in WITX][wasi-p1]). From 95473721cefa77f41f67451ca82ea863c133df97 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:41:01 +0900 Subject: [PATCH 09/28] fix: note p1's legacy specification --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 1d7d5401..49423f0a 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -33,7 +33,7 @@ nested `(module)`/`(component)` s-expressions): One part that might cause confusion here is that a WASI Preview 1 "component" is in fact a *core module*. More precisely, a Preview 1 "component" is a WebAssembly core module with a well-defined -set of exports ([specified in WITX][wasi-p1]). +set of exports ([legacy specification][wasi-p1]). [cabi]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md [wasi-p1]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/witx/wasi_snapshot_preview1.witx From 3050a0d0c24b72c95fc78a10ee8397e8d2d2f0f3 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:41:39 +0900 Subject: [PATCH 10/28] fix: 'core components' --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 49423f0a..854af301 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -41,7 +41,7 @@ set of exports ([legacy specification][wasi-p1]). ## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other? -WebAssembly core components do not have any access to the host system (by design) -- they can only perform +WebAssembly core modules do not have any access to the host system (by design) -- they can only perform computations on a fixed set of types. The component model enables core components to interact with the "outside" world via a rich set of types ([WebAssembly Interface Types][wit]). From 358d6182041b9fb6e512307fb1ed97a30123b9d5 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:45:14 +0900 Subject: [PATCH 11/28] fix: contrast sentence --- component-model/src/reference/faq.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 854af301..252ef224 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -45,6 +45,8 @@ WebAssembly core modules do not have any access to the host system (by design) - computations on a fixed set of types. The component model enables core components to interact with the "outside" world via a rich set of types ([WebAssembly Interface Types][wit]). +Where as WebAssembly core components must find a way to represent higher level types with the primitives defined in an ad hoc manner, the Component Model presents a consistent way of representing complex types familiar in most high level languages. + The WebAssembly System Interface (WASI) is a *standardization* of the interfaces, functions and types that a system or platform can expose to a WebAssembly component. At a glance, many parts of WASI are UNIX-like, in that they match traditional expectations for programs like STDIN, STDOUT, and writing to files. From d08346357773eb4be1ecd6d7cd8150da858c1b26 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:47:25 +0900 Subject: [PATCH 12/28] fix: primitive types --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 252ef224..36534f2e 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -42,7 +42,7 @@ set of exports ([legacy specification][wasi-p1]). ## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other? WebAssembly core modules do not have any access to the host system (by design) -- they can only perform -computations on a fixed set of types. The component model enables core components to interact with the "outside" +computations on a fixed set of primitive types (`i32`, `i64`, `f32`, `f64`), `v128`). The component model enables core components to interact with the "outside" world via a rich set of types ([WebAssembly Interface Types][wit]). Where as WebAssembly core components must find a way to represent higher level types with the primitives defined in an ad hoc manner, the Component Model presents a consistent way of representing complex types familiar in most high level languages. From 7232d66ecc63f4912bb94de1e6383d9eb2b0a34e Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:49:45 +0900 Subject: [PATCH 13/28] fix: clarify interaction with outside world --- component-model/src/reference/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 36534f2e..69d05331 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -41,8 +41,8 @@ set of exports ([legacy specification][wasi-p1]). ## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other? -WebAssembly core modules do not have any access to the host system (by design) -- they can only perform -computations on a fixed set of primitive types (`i32`, `i64`, `f32`, `f64`), `v128`). The component model enables core components to interact with the "outside" +WebAssembly core modules use functions provided by the host system (the "outside world") but they can only perform +computations on a fixed set of primitive types (`i32`, `i64`, `f32`, `f64`), `v128`). The component model enables core components to interact with the "outside world" world via a rich set of types ([WebAssembly Interface Types][wit]). Where as WebAssembly core components must find a way to represent higher level types with the primitives defined in an ad hoc manner, the Component Model presents a consistent way of representing complex types familiar in most high level languages. From e96058dc3b8529a66f10dbee91b71df11a74edab Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:50:24 +0900 Subject: [PATCH 14/28] fix: typo --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 69d05331..c42b1a0b 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -43,7 +43,7 @@ set of exports ([legacy specification][wasi-p1]). WebAssembly core modules use functions provided by the host system (the "outside world") but they can only perform computations on a fixed set of primitive types (`i32`, `i64`, `f32`, `f64`), `v128`). The component model enables core components to interact with the "outside world" -world via a rich set of types ([WebAssembly Interface Types][wit]). + via a rich set of types ([WebAssembly Interface Types][wit]). Where as WebAssembly core components must find a way to represent higher level types with the primitives defined in an ad hoc manner, the Component Model presents a consistent way of representing complex types familiar in most high level languages. From 4be8023ee06ebce3c94f3e73d8c009021f1d6282 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:53:57 +0900 Subject: [PATCH 15/28] fix: contrast sentence --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index c42b1a0b..f83784df 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -45,7 +45,7 @@ WebAssembly core modules use functions provided by the host system (the "outside computations on a fixed set of primitive types (`i32`, `i64`, `f32`, `f64`), `v128`). The component model enables core components to interact with the "outside world" via a rich set of types ([WebAssembly Interface Types][wit]). -Where as WebAssembly core components must find a way to represent higher level types with the primitives defined in an ad hoc manner, the Component Model presents a consistent way of representing complex types familiar in most high level languages. +While WebAssembly core module *can* represent higher level types using the available primitives, every binary and platform may do so in an ad-hoc manner. The Component Model presents a consistent way of representing a rich set of types familiar in most high level languages that is consistent across binaries and platforms. The WebAssembly System Interface (WASI) is a *standardization* of the interfaces, functions and types that a system or platform can expose to a WebAssembly component. At a glance, many parts of WASI are UNIX-like, From 8f9eacd74a6f1fe4fa339fd97519d57563d6bd63 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:55:21 +0900 Subject: [PATCH 16/28] fix: wasi description --- component-model/src/reference/faq.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index f83784df..a2f79450 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -47,7 +47,9 @@ computations on a fixed set of primitive types (`i32`, `i64`, `f32`, `f64`), `v1 While WebAssembly core module *can* represent higher level types using the available primitives, every binary and platform may do so in an ad-hoc manner. The Component Model presents a consistent way of representing a rich set of types familiar in most high level languages that is consistent across binaries and platforms. -The WebAssembly System Interface (WASI) is a *standardization* of the interfaces, functions and types that +The WebAssembly System Interface (WASI) is a set of APIs for WASI being developed for eventual standardization by the WASI Subgroup, which is a subgroup of the WebAssembly Community Group. + +WASI defines interfaces, functions and types that a system or platform can expose to a WebAssembly component. At a glance, many parts of WASI are UNIX-like, in that they match traditional expectations for programs like STDIN, STDOUT, and writing to files. From d0149cb8af5a8b2c95c5f3cbef243163ba7e4677 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 12:56:39 +0900 Subject: [PATCH 17/28] fix: platform builder sentence --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index a2f79450..82cac827 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -57,7 +57,7 @@ Some WASI system interfaces work at a much higher level than the command line ho [`wasi:http`][wasi-http]. `wasi:http` is included as a standardized platform due to the ubiquity of the internet and the common use case of WebAssembly components with "the web" as a platform. -With WIT, platform builders can define *any* interface to be *your* system interfaces that WebAssembly components can +With WIT, platform builders can define *any* interface that WebAssembly components expect to access -- WASI is a standardized set which enables to build on a shared base set of abstractions. [wit]: https://component-model.bytecodealliance.org/design/wit.html From 8e8951c4a6ee0580b95a459eedabc04c193a9a3e Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 13:08:56 +0900 Subject: [PATCH 18/28] fix: self describing explanation --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 82cac827..918f9760 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -78,7 +78,7 @@ in practice as Preview 1 components can be *adapted* into Preview 2 components a ## Q: What are component imports? -WebAssembly components represent a new kind of binary that can *describe* its interface or expected usage natively. +WebAssembly components are self-describing -- information about required external functionality (which must be provided by the platform or another component) is included in the binary. This means that WebAssembly components have functionality that they might *import* (e.g. `wasi:cli/environment`). Imports are easiest illustrated with WIT: From 61e65a4edb8e08d8cf1ec20b8cead8d5f5e17062 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 13:13:58 +0900 Subject: [PATCH 19/28] refactor: wording around imports --- component-model/src/reference/faq.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 918f9760..7c778d5d 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -79,7 +79,14 @@ in practice as Preview 1 components can be *adapted* into Preview 2 components a ## Q: What are component imports? WebAssembly components are self-describing -- information about required external functionality (which must be provided by the platform or another component) is included in the binary. -This means that WebAssembly components have functionality that they might *import* (e.g. `wasi:cli/environment`). +For example, a WebAssembly component that may require some use of outside environment variables may *import* a WASI interface like `wasi:cli/environment`. + +> [!NOTE] +> The values provided by the `wasi:cli/environment` are not guaranteed +> to be ENV variables on the host machine -- this is a choice left to the +> platform, in the implementation of `wasi:cli/environment` that it exposes. +> +> For example, platforms may choose to elide sensitive environment variables, or provide none at all, in practice. Imports are easiest illustrated with WIT: From 6f5667b3ef2a28b91530461f1088c9c6d5308af1 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 13:20:17 +0900 Subject: [PATCH 20/28] fix: component description --- component-model/src/reference/faq.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 7c778d5d..1cfa2b33 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -8,8 +8,10 @@ WebAssembly (core), components, and the WebAssembly ecosystem as a whole. A WebAssembly module (more precisely referred to as a "WebAssembly core module") is a binary that conforms to the [WebAssembly Core Specification][wasm-core-spec]. -A WebAssembly component refers to a WebAssembly core module that has been wrapped in -the [Canonical ABI][cabi], i.e. the binary contract for the Component Model. By adhering to the +A WebAssembly component is a WebAssembly binary that: +- Adheres to the component model [binary format][cm-binary-format] (as opposed to a WebAssembly core binary format) +- Uses the [WebAssembly Interface types][wit] specification to encode type information. +- Adheres to the Component Model [Canonical ABI][cabi] for converting between rich types and those present in core WebAssembly. canonical ABI, WebAssembly components can take advantage of all the features the Component Model has to offer. WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules From 690f8381ea68aef39611ba8d5e5525da73697e26 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 13:20:54 +0900 Subject: [PATCH 21/28] refactor: remove unneeded sentence --- component-model/src/reference/faq.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 1cfa2b33..ac5df5e8 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -12,8 +12,6 @@ A WebAssembly component is a WebAssembly binary that: - Adheres to the component model [binary format][cm-binary-format] (as opposed to a WebAssembly core binary format) - Uses the [WebAssembly Interface types][wit] specification to encode type information. - Adheres to the Component Model [Canonical ABI][cabi] for converting between rich types and those present in core WebAssembly. -canonical ABI, WebAssembly components can take advantage of all the features the Component Model -has to offer. WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules *cannot not* contain Components. One easy way to differentiate is by reading the WAT for a component: From a42455c31d16f9eb6632cf82a19d144163649c16 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 13:22:44 +0900 Subject: [PATCH 22/28] fix: include imports --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index ac5df5e8..34516089 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -33,7 +33,7 @@ nested `(module)`/`(component)` s-expressions): One part that might cause confusion here is that a WASI Preview 1 "component" is in fact a *core module*. More precisely, a Preview 1 "component" is a WebAssembly core module with a well-defined -set of exports ([legacy specification][wasi-p1]). +set of imports and exports ([legacy specification][wasi-p1]). [cabi]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md [wasi-p1]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/witx/wasi_snapshot_preview1.witx From 1d6ecc51bbebb54329f235393e0ea0e6276b2e0a Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Thu, 3 Jul 2025 13:28:30 +0900 Subject: [PATCH 23/28] fix: add split up question --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 34516089..f001ebbe 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -14,7 +14,7 @@ A WebAssembly component is a WebAssembly binary that: - Adheres to the Component Model [Canonical ABI][cabi] for converting between rich types and those present in core WebAssembly. WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules *cannot not* contain Components. One easy way to differentiate is by reading the WAT for a component: - +## Q: How can I tell if a WebAssembly binary is a component or a module? A WebAssembly core module generally consists of a `(module)` s-expression: ```wat (module From 2db1009cd4f80a1ac38398eabfa88cbca40b31c8 Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Thu, 3 Jul 2025 14:27:20 +0900 Subject: [PATCH 24/28] refactor: WIT + WASI explanation Signed-off-by: Victor Adossi --- component-model/src/reference/faq.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index f001ebbe..265e1b2c 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -41,15 +41,14 @@ set of imports and exports ([legacy specification][wasi-p1]). ## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other? -WebAssembly core modules use functions provided by the host system (the "outside world") but they can only perform -computations on a fixed set of primitive types (`i32`, `i64`, `f32`, `f64`), `v128`). The component model enables core components to interact with the "outside world" - via a rich set of types ([WebAssembly Interface Types][wit]). +While WebAssembly core module *can* represent higher level types using the available primitives, every binary and platform +may do so in an ad-hoc manner. The Component Model presents a consistent way of representing a rich set of types familiar in +most high level languages that is consistent across binaries and platforms. -While WebAssembly core module *can* represent higher level types using the available primitives, every binary and platform may do so in an ad-hoc manner. The Component Model presents a consistent way of representing a rich set of types familiar in most high level languages that is consistent across binaries and platforms. +The set of rich types which can be used by WebAssembly components are called [WebAssembly Interface Types (WIT)][wit]. -The WebAssembly System Interface (WASI) is a set of APIs for WASI being developed for eventual standardization by the WASI Subgroup, which is a subgroup of the WebAssembly Community Group. - -WASI defines interfaces, functions and types that +The WebAssembly System Interface (WASI) is a set of APIs (specified in WIT) developed for eventual standardization by the WASI +Subgroup, which is a subgroup of the WebAssembly Community Group. WASI defines interfaces, functions and types that a system or platform can expose to a WebAssembly component. At a glance, many parts of WASI are UNIX-like, in that they match traditional expectations for programs like STDIN, STDOUT, and writing to files. From fb8acad72fd9715546d76f70a9746a1396be78d6 Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Thu, 3 Jul 2025 14:31:11 +0900 Subject: [PATCH 25/28] fix: cm section Signed-off-by: Victor Adossi --- component-model/src/reference/faq.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 265e1b2c..fd89a633 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -14,7 +14,14 @@ A WebAssembly component is a WebAssembly binary that: - Adheres to the Component Model [Canonical ABI][cabi] for converting between rich types and those present in core WebAssembly. WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules *cannot not* contain Components. One easy way to differentiate is by reading the WAT for a component: + +[cabi]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md +[cm-binary-format]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Binary.md +[wasi-p1]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/witx/wasi_snapshot_preview1.witx +[wasm-core-spec]: https://webassembly.github.io/spec/core/ + ## Q: How can I tell if a WebAssembly binary is a component or a module? + A WebAssembly core module generally consists of a `(module)` s-expression: ```wat (module @@ -31,14 +38,6 @@ nested `(module)`/`(component)` s-expressions): ) ``` -One part that might cause confusion here is that a WASI Preview 1 "component" is in fact a -*core module*. More precisely, a Preview 1 "component" is a WebAssembly core module with a well-defined -set of imports and exports ([legacy specification][wasi-p1]). - -[cabi]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md -[wasi-p1]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/witx/wasi_snapshot_preview1.witx -[wasm-core-spec]: https://webassembly.github.io/spec/core/ - ## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other? While WebAssembly core module *can* represent higher level types using the available primitives, every binary and platform @@ -75,6 +74,9 @@ https://github.com/WebAssembly/WASI/tree/main/wasip2 Many programming language toolchains may only support Preview 1 components natively, but this isn't a problem in practice as Preview 1 components can be *adapted* into Preview 2 components automatically. +While somewhat confusing a WASI Preview 1 "component" is in fact a *WebAssembly core module*. More precisely, a +Preview 1 "component" is a WebAssembly core module with a well-defined set of imports and exports ([legacy specification][wasi-p1]). + ## Q: What are component imports? WebAssembly components are self-describing -- information about required external functionality (which must be provided by the platform or another component) is included in the binary. @@ -135,3 +137,5 @@ Please contribute to the Component Book by filing your question (or one that you [an issue on GitHub][gh-issues]. [gh-issues-new]: https://github.com/bytecodealliance/component-docs/issues/new + +[!NOTE]: # From d3a1e0413a647357823f79a7194ac326cc1586bc Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Thu, 3 Jul 2025 14:41:24 +0900 Subject: [PATCH 26/28] fix: prose, organization Signed-off-by: Victor Adossi --- component-model/src/reference/faq.md | 31 ++++++++++++++++++---------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index fd89a633..60db5350 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -1,20 +1,25 @@ # Frequently Asked Questions (FAQ) -This page hosts a series of questions that are frequently asked or that might be confusing about -WebAssembly (core), components, and the WebAssembly ecosystem as a whole. +This page hosts a series of questions that are frequently asked along with descriptions +of concepts that may be confusing with regards to core WebAssembly, WebAssembly components +(i.e. the Component Model), and the WebAssembly ecosystem as a whole. -## Q: What is the difference between a _component_ and _module_ in WebAssembly? +## Q: What is the difference between a _module_ and _component_ in WebAssembly? A WebAssembly module (more precisely referred to as a "WebAssembly core module") is a binary that conforms to the [WebAssembly Core Specification][wasm-core-spec]. -A WebAssembly component is a WebAssembly binary that: +A WebAssembly component: - Adheres to the component model [binary format][cm-binary-format] (as opposed to a WebAssembly core binary format) - Uses the [WebAssembly Interface types][wit] specification to encode type information. - Adheres to the Component Model [Canonical ABI][cabi] for converting between rich types and those present in core WebAssembly. + WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules -*cannot not* contain Components. One easy way to differentiate is by reading the WAT for a component: +*cannot* contain Components. WebAssembly components and WebAssembly core modules have a different binary format. + +WebAssembly can be expressed via both a binary and textual format (["WAT", the WebAssembly Text format][wat]). +[wat]: https://webassembly.github.io/spec/core/text/index.html [cabi]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md [cm-binary-format]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Binary.md [wasi-p1]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/witx/wasi_snapshot_preview1.witx @@ -22,7 +27,10 @@ WebAssembly Components can (and often do) contain core modules, but generally We ## Q: How can I tell if a WebAssembly binary is a component or a module? -A WebAssembly core module generally consists of a `(module)` s-expression: +After converting a WebAssembly binary to it's textual format (e.g. via a tool like [`wasm-tools print`][wasm-tools-examples]), +it is easy to tell a WebAssembly core module and a WebAssembly component apart. + +A WebAssembly core module generally consists of a top level `(module)` s-expression: ```wat (module ;; ... @@ -30,7 +38,7 @@ A WebAssembly core module generally consists of a `(module)` s-expression: ``` A WebAssembly component generally consists of a `(component)` s-expression (and may contain -nested `(module)`/`(component)` s-expressions): +nested `(core:module)`/`(component)` s-expressions): ```wat (component @@ -38,6 +46,8 @@ nested `(module)`/`(component)` s-expressions): ) ``` +[WASM-tools-examples]: https://github.com/bytecodealliance/wasm-tools?tab=readme-ov-file#examples + ## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other? While WebAssembly core module *can* represent higher level types using the available primitives, every binary and platform @@ -108,9 +118,8 @@ The component is said to "import" the `wasi:cli/environment` interface, using th ## Q: What are component exports? -WebAssembly components represent a new kind of binary that can *describe* its expected usage natively. This means that -WebAssembly components have functionality that they *export*, which users of the component (e.g. another component, or -a WebAssembly host) can use. +WebAssembly components are self-describing -- along with imports, WebAssembly components can also describe what functionality +they *export*, which callers of the component (e.g. another component, a WebAssembly host) can reference. Exports are easiest illustrated with WIT: @@ -126,7 +135,7 @@ world example-world { } ``` -For the component that inhabits the `example-world` defined above, the outside world can expect the WebAssembly binary to +For the component that inhabits the `example-world` defined above, callers can expect the WebAssembly binary to have a `say-hello` function that is callable via the `example-namespace:example-package/example-interface` interface. The component is said to "export" the `example-interface` interface, making available the functions and types therein. From 5e2f93e9f2e13f2e0a86f77ba2e4a7c6f121d6e4 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Fri, 4 Jul 2025 09:25:33 +0900 Subject: [PATCH 27/28] fix: components mention Co-authored-by: itowlson --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 60db5350..b54cdb14 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -17,7 +17,7 @@ A WebAssembly component: WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules *cannot* contain Components. WebAssembly components and WebAssembly core modules have a different binary format. -WebAssembly can be expressed via both a binary and textual format (["WAT", the WebAssembly Text format][wat]). +WebAssembly components can be expressed via both a binary and textual format (["WAT", the WebAssembly Text format][wat]). [wat]: https://webassembly.github.io/spec/core/text/index.html [cabi]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md From 001bd1d6e7d3fb1feb067443183845de83e15bfa Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Fri, 4 Jul 2025 09:26:24 +0900 Subject: [PATCH 28/28] fix: it's -> its Co-authored-by: itowlson --- component-model/src/reference/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index b54cdb14..adacc836 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -27,7 +27,7 @@ WebAssembly components can be expressed via both a binary and textual format ([" ## Q: How can I tell if a WebAssembly binary is a component or a module? -After converting a WebAssembly binary to it's textual format (e.g. via a tool like [`wasm-tools print`][wasm-tools-examples]), +After converting a WebAssembly binary to its textual format (e.g. via a tool like [`wasm-tools print`][wasm-tools-examples]), it is easy to tell a WebAssembly core module and a WebAssembly component apart. A WebAssembly core module generally consists of a top level `(module)` s-expression: