Skip to content

Commit ee558a3

Browse files
catamorphismcatamorphism
authored
refactor: Revise FAQ (#317)
Copyedited, added semantic line breaks, moved WIT examples into separate files.
1 parent 71059eb commit ee558a3

File tree

3 files changed

+76
-66
lines changed

3 files changed

+76
-66
lines changed

‎component-model/examples/faq/example-hello.wit‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
package example-namespace:example-package;
2+
3+
interface example-interface {
4+
say-hello: func(name: string) -> string;
5+
}
6+
7+
world example-world {
8+
export example-interface;
9+
}

‎component-model/examples/faq/example.wit‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
package example-namespace:example-package;
2+
3+
world example-world {
4+
import wasi:cli/environment@0.2.4;
5+
}

‎component-model/src/reference/faq.md‎

Lines changed: 62 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,23 @@
11
# Frequently Asked Questions (FAQ)
22

3-
This page hosts a series of questions that are frequently asked along with descriptions
4-
of concepts that may be confusing with regards to core WebAssembly, WebAssembly components
5-
(i.e. the Component Model), and the WebAssembly ecosystem as a whole.
3+
This page hosts a series of questions that are frequently asked
4+
along with descriptions of concepts that may be confusing with regards to core WebAssembly,
5+
WebAssembly components (i.e. the Component Model), and the WebAssembly ecosystem as a whole.
66

77
## Q: What is the difference between a _module_ and _component_ in WebAssembly?
88

9-
A WebAssembly module (more precisely referred to as a "WebAssembly core module") is a
10-
binary that conforms to the [WebAssembly Core Specification][wasm-core-spec].
9+
A WebAssembly module (more precisely referred to as a "WebAssembly core module")
10+
is a binary that conforms to the [WebAssembly Core Specification][wasm-core-spec].
1111

1212
A WebAssembly component:
13-
- Adheres to the component model [binary format][cm-binary-format] (as opposed to a WebAssembly core binary format)
13+
- Adheres to the component model [binary format][cm-binary-format] (as opposed to the WebAssembly core binary format).
1414
- Uses the [WebAssembly Interface types][wit] specification to encode type information.
15-
- Adheres to the Component Model [Canonical ABI][cabi] for converting between rich types and those present in core WebAssembly.
15+
- Adheres to the Component Model [Canonical ABI][cabi] for converting between rich types
16+
and those present in core WebAssembly.
1617

17-
WebAssembly Components can (and often do) contain core modules, but generally WebAssembly core modules
18-
*cannot* contain Components. WebAssembly components and WebAssembly core modules have a different binary format.
18+
WebAssembly Components can (and often do) contain core modules,
19+
but generally WebAssembly core modules *cannot* contain components.
20+
WebAssembly components and WebAssembly core modules have a different binary format.
1921

2022
WebAssembly components can be expressed via both a binary and textual format (["WAT", the WebAssembly Text format][wat]).
2123

@@ -27,18 +29,19 @@ WebAssembly components can be expressed via both a binary and textual format (["
2729

2830
## Q: How can I tell if a WebAssembly binary is a component or a module?
2931

30-
After converting a WebAssembly binary to its textual format (e.g. via a tool like [`wasm-tools print`][wasm-tools-examples]),
32+
After converting a WebAssembly binary to its textual format
33+
(e.g. via a tool like [`wasm-tools print`][wasm-tools-examples]),
3134
it is easy to tell a WebAssembly core module and a WebAssembly component apart.
3235

33-
A WebAssembly core module generally consists of a top level `(module)` s-expression:
36+
A WebAssembly core module generally consists of a top level `(module)` [s-expression][s-expression]:
3437
```wat
3538
(module
3639
;; ...
3740
)
3841
```
3942

40-
A WebAssembly component generally consists of a `(component)` s-expression (and may contain
41-
nested `(core:module)`/`(component)` s-expressions):
43+
A WebAssembly component generally consists of a `(component)` s-expression
44+
(and may contain nested `(core:module)`/`(component)` s-expressions):
4245

4346
```wat
4447
(component
@@ -47,103 +50,96 @@ nested `(core:module)`/`(component)` s-expressions):
4750
```
4851

4952
[WASM-tools-examples]: https://github.com/bytecodealliance/wasm-tools?tab=readme-ov-file#examples
53+
[s-expression]: https://en.wikipedia.org/wiki/S-expression
5054

5155
## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other?
5256

53-
While WebAssembly core module *can* represent higher level types using the available primitives, every binary and platform
54-
may do so in an ad-hoc manner. The Component Model presents a consistent way of representing a rich set of types familiar in
55-
most high level languages that is consistent across binaries and platforms.
57+
While WebAssembly core modules *can* represent higher-level types using the available primitives,
58+
every binary and platform may do so in an *ad hoc* manner.
59+
The Component Model presents a representation for a rich set of
60+
types—familiar from most high-level languages—that is consistent across binaries and platforms.
61+
The set of rich types that can be used by WebAssembly components is called [WebAssembly Interface Types (WIT)][wit].
5662

57-
The set of rich types which can be used by WebAssembly components are called [WebAssembly Interface Types (WIT)][wit].
63+
The WebAssembly System Interface (WASI) is a set of APIs (specified in WIT)
64+
developed for eventual standardization by the WASI Subgroup, which is a subgroup of the WebAssembly Community Group.
65+
WASI defines interfaces, functions and types that a system or platform can expose to a WebAssembly component.
66+
At a glance, many parts of WASI are UNIX-like, in that they match traditional expectations for programs
67+
like `stdin`, `stdout`, and writing to files.
5868

59-
The WebAssembly System Interface (WASI) is a set of APIs (specified in WIT) developed for eventual standardization by the WASI
60-
Subgroup, which is a subgroup of the WebAssembly Community Group. WASI defines interfaces, functions and types that
61-
a system or platform can expose to a WebAssembly component. At a glance, many parts of WASI are UNIX-like,
62-
in that they match traditional expectations for programs like STDIN, STDOUT, and writing to files.
63-
64-
Some WASI system interfaces work at a much higher level than the command line however, like
65-
[`wasi:http`][wasi-http]. `wasi:http` is included as a standardized platform due to the ubiquity
66-
of the internet and the common use case of WebAssembly components with "the web" as a platform.
69+
Some WASI system interfaces work at a much higher level than the command line, however,
70+
like [`wasi:http`][wasi-http].
71+
`wasi:http` is included as a standardized platform due to the ubiquity of the Internet
72+
and the common use case of WebAssembly components with the Web as a platform.
6773

6874
With WIT, platform builders can define *any* interface that WebAssembly components
69-
expect to access -- WASI is a standardized set which enables to build on a shared base set of abstractions.
75+
expect to access—WASI enables building interfaces on top of a shared standard set of abstractions.
7076

7177
[wit]: https://component-model.bytecodealliance.org/design/wit.html
7278
[wasi-http]: https://github.com/WebAssembly/wasi-http
7379

7480
## Q: I see the terms Preview 1 and Preview 2 frequently. What do those refer to?
7581

76-
Preview 1 refers to the first iteration of the Component Model which was based on WITX and is now deprecated:
77-
78-
https://github.com/WebAssembly/WASI/tree/main/legacy
79-
80-
Preview 2 refers to a newer iteration of the Component Model which uses WebAssembly Interface Types (WIT):
81-
82-
https://github.com/WebAssembly/WASI/tree/main/wasip2
82+
Preview 1 refers to [the first iteration of the Component Model](https://github.com/WebAssembly/WASI/tree/main/legacy)
83+
which was based on WITX and is now deprecated.
84+
Preview 2 refers to [a newer iteration of the Component Model](https://github.com/WebAssembly/WASI/tree/main/wasip2)
85+
which uses WebAssembly Interface Types (WIT).
8386

84-
Many programming language toolchains may only support Preview 1 components natively, but this isn't a problem
85-
in practice as Preview 1 components can be *adapted* into Preview 2 components automatically.
87+
Many programming language toolchains may only support Preview 1 components natively,
88+
but this isn't a problem in practice as Preview 1 components can be *adapted* into Preview 2 components automatically.
8689

87-
While somewhat confusing a WASI Preview 1 "component" is in fact a *WebAssembly core module*. More precisely, a
88-
Preview 1 "component" is a WebAssembly core module with a well-defined set of imports and exports ([legacy specification][wasi-p1]).
90+
While somewhat confusing, a WASI Preview 1 "component" is in fact a *WebAssembly core module*.
91+
More precisely, a Preview 1 "component" is a WebAssembly core module with a well-defined set of imports and exports ([legacy specification][wasi-p1]).
8992

9093
## Q: What are component imports?
9194

92-
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.
93-
For example, a WebAssembly component that may require some use of outside environment variables may *import* a WASI interface like `wasi:cli/environment`.
95+
WebAssembly components are self-describing: information about required external functionality
96+
(which must be provided by the platform or another component) is included in the binary.
97+
For example, a WebAssembly component that may require outside environment variables may *import*
98+
a WASI interface like `wasi:cli/environment`.
9499

95100
> [!NOTE]
96-
> The values provided by the `wasi:cli/environment` are not guaranteed
97-
> to be ENV variables on the host machine -- this is a choice left to the
98-
> platform, in the implementation of `wasi:cli/environment` that it exposes.
101+
> The values provided by the `wasi:cli/environment` interface are not guaranteed
102+
> to be environment variables on the host machine—this is a choice left to the platform,
103+
> in the implementation of `wasi:cli/environment` that it exposes.
99104
>
100105
> For example, platforms may choose to elide sensitive environment variables, or provide none at all, in practice.
101106
102-
Imports are easiest illustrated with WIT:
107+
Imports are most easily illustrated with WIT:
103108

104109
```wit
105-
package example-namespace:example-package;
106-
107-
world example-world {
108-
import wasi:cli/[email protected];
109-
}
110+
{{#include ../../examples/faq/example.wit}}
110111
```
111112

112-
The [`environment` interface in `wasi:cli`][wasi-cli-env] provides various types and functions for interacting with
113-
environment variables.
113+
The [`environment` interface in `wasi:cli`][wasi-cli-env] provides various types and functions
114+
for interacting with environment variables.
114115

115-
The component is said to "import" the `wasi:cli/environment` interface, using the available functions and types therein.
116+
The component is said to "import" the `wasi:cli/environment` interface,
117+
using the available functions and types therein.
116118

117119
[wasi-cli-env]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/environment.wit
118120

119121
## Q: What are component exports?
120122

121-
WebAssembly components are self-describing -- along with imports, WebAssembly components can also describe what functionality
122-
they *export*, which callers of the component (e.g. another component, a WebAssembly host) can reference.
123+
WebAssembly components are self-describing: along with imports, WebAssembly components
124+
can also describe what functionality they *export*, which callers of the component
125+
(e.g. another component or a WebAssembly host) can reference.
123126

124127
Exports are easiest illustrated with WIT:
125128

126129
```wit
127-
package example-namespace:example-package;
128-
129-
interface example-interface {
130-
say-hello: func(name: string) -> string;
131-
}
132-
133-
world example-world {
134-
export example-interface;
135-
}
130+
{{#include ../../examples/faq/example-hello.wit}}
136131
```
137132

138-
For the component that inhabits the `example-world` defined above, callers can expect the WebAssembly binary to
139-
have a `say-hello` function that is callable via the `example-namespace:example-package/example-interface` interface.
133+
For a component that implements the `example-world` defined above,
134+
callers can expect the WebAssembly binary to have a `say-hello` function that is callable
135+
via the `example-namespace:example-package/example-interface` interface.
140136

141137
The component is said to "export" the `example-interface` interface, making available the functions and types therein.
142138

143139
## Still have questions?
144140

145-
Please contribute to the Component Book by filing your question (or one that you think should be covered here) as
146-
[an issue on GitHub][gh-issues-new].
141+
Please contribute to the Component Book by filing your question (or one that you think should be covered here)
142+
as [an issue on GitHub][gh-issues-new].
147143

148144
[gh-issues-new]: https://github.com/bytecodealliance/component-docs/issues/new
149145

0 commit comments

Comments
 (0)