From 9fdda73de78fb2ff0feba3c0c2ff23ff516a6b64 Mon Sep 17 00:00:00 2001 From: Tim Chevalier Date: Tue, 9 Sep 2025 13:11:59 -0700 Subject: [PATCH] Revise FAQ Copyedited, added semantic line breaks, moved WIT examples into separate files. --- .../examples/faq/example-hello.wit | 9 ++ component-model/examples/faq/example.wit | 5 + component-model/src/reference/faq.md | 128 +++++++++--------- 3 files changed, 76 insertions(+), 66 deletions(-) create mode 100644 component-model/examples/faq/example-hello.wit create mode 100644 component-model/examples/faq/example.wit diff --git a/component-model/examples/faq/example-hello.wit b/component-model/examples/faq/example-hello.wit new file mode 100644 index 00000000..5905267e --- /dev/null +++ b/component-model/examples/faq/example-hello.wit @@ -0,0 +1,9 @@ +package example-namespace:example-package; + +interface example-interface { + say-hello: func(name: string) -> string; +} + +world example-world { + export example-interface; +} diff --git a/component-model/examples/faq/example.wit b/component-model/examples/faq/example.wit new file mode 100644 index 00000000..29d0ba99 --- /dev/null +++ b/component-model/examples/faq/example.wit @@ -0,0 +1,5 @@ +package example-namespace:example-package; + +world example-world { + import wasi:cli/environment@0.2.4; +} diff --git a/component-model/src/reference/faq.md b/component-model/src/reference/faq.md index 3bfba489..149f703f 100644 --- a/component-model/src/reference/faq.md +++ b/component-model/src/reference/faq.md @@ -1,21 +1,23 @@ # Frequently Asked Questions (FAQ) -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. +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 _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 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: -- Adheres to the component model [binary format][cm-binary-format] (as opposed to a WebAssembly core binary format) +- Adheres to the component model [binary format][cm-binary-format] (as opposed to the 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. +- 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* contain Components. WebAssembly components and WebAssembly core modules have a different binary format. +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 components can be expressed via both a binary and textual format (["WAT", the WebAssembly Text format][wat]). @@ -27,18 +29,19 @@ 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 its 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: +A WebAssembly core module generally consists of a top level `(module)` [s-expression][s-expression]: ```wat (module ;; ... ) ``` -A WebAssembly component generally consists of a `(component)` s-expression (and may contain -nested `(core:module)`/`(component)` s-expressions): +A WebAssembly component generally consists of a `(component)` s-expression +(and may contain nested `(core:module)`/`(component)` s-expressions): ```wat (component @@ -47,103 +50,96 @@ nested `(core:module)`/`(component)` s-expressions): ``` [WASM-tools-examples]: https://github.com/bytecodealliance/wasm-tools?tab=readme-ov-file#examples +[s-expression]: https://en.wikipedia.org/wiki/S-expression ## 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 -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 modules *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 representation for a rich set of +types—familiar from most high-level languages—that is consistent across binaries and platforms. +The set of rich types that can be used by WebAssembly components is called [WebAssembly Interface Types (WIT)][wit]. -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 (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. -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. - -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. +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 that WebAssembly components -expect to access -- WASI is a standardized set which enables to build on a shared base set of abstractions. +expect to access—WASI enables building interfaces on top of a shared standard 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 +Preview 1 refers to [the first iteration of the Component Model](https://github.com/WebAssembly/WASI/tree/main/legacy) +which was based on WITX and is now deprecated. +Preview 2 refers to [a newer iteration of the Component Model](https://github.com/WebAssembly/WASI/tree/main/wasip2) +which uses WebAssembly Interface Types (WIT). -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. +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]). +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. -For example, a WebAssembly component that may require some use of outside environment variables may *import* a WASI interface like `wasi:cli/environment`. +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. +For example, a WebAssembly component that may require 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. +> The values provided by the `wasi:cli/environment` interface are not guaranteed +> to be environment 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: +Imports are most easily illustrated with WIT: ```wit -package example-namespace:example-package; - -world example-world { - import wasi:cli/environment@0.2.4; -} +{{#include ../../examples/faq/example.wit}} ``` -The [`environment` interface in `wasi:cli`][wasi-cli-env] provides various types and functions for interacting with -environment variables. +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. +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 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. +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 or a WebAssembly host) can reference. 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; -} +{{#include ../../examples/faq/example-hello.wit}} ``` -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. +For a component that implements 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. ## 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-new]. +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-new]. [gh-issues-new]: https://github.com/bytecodealliance/component-docs/issues/new