|
| 1 | +# Frequently Asked Questions (FAQ) |
| 2 | + |
| 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. |
| 6 | + |
| 7 | +## Q: What is the difference between a _module_ and _component_ in WebAssembly? |
| 8 | + |
| 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]. |
| 11 | + |
| 12 | +A WebAssembly component: |
| 13 | +- Adheres to the component model [binary format][cm-binary-format] (as opposed to a WebAssembly core binary format) |
| 14 | +- 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. |
| 16 | + |
| 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. |
| 19 | + |
| 20 | +WebAssembly components can be expressed via both a binary and textual format (["WAT", the WebAssembly Text format][wat]). |
| 21 | + |
| 22 | +[wat]: https://webassembly.github.io/spec/core/text/index.html |
| 23 | +[cabi]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md |
| 24 | +[cm-binary-format]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Binary.md |
| 25 | +[wasi-p1]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/witx/wasi_snapshot_preview1.witx |
| 26 | +[wasm-core-spec]: https://webassembly.github.io/spec/core/ |
| 27 | + |
| 28 | +## Q: How can I tell if a WebAssembly binary is a component or a module? |
| 29 | + |
| 30 | +After converting a WebAssembly binary to its textual format (e.g. via a tool like [`wasm-tools print`][wasm-tools-examples]), |
| 31 | +it is easy to tell a WebAssembly core module and a WebAssembly component apart. |
| 32 | + |
| 33 | +A WebAssembly core module generally consists of a top level `(module)` s-expression: |
| 34 | +```wat |
| 35 | +(module |
| 36 | + ;; ... |
| 37 | +) |
| 38 | +``` |
| 39 | + |
| 40 | +A WebAssembly component generally consists of a `(component)` s-expression (and may contain |
| 41 | +nested `(core:module)`/`(component)` s-expressions): |
| 42 | + |
| 43 | +```wat |
| 44 | +(component |
| 45 | + ;; ... |
| 46 | +) |
| 47 | +``` |
| 48 | + |
| 49 | +[WASM-tools-examples]: https://github.com/bytecodealliance/wasm-tools?tab=readme-ov-file#examples |
| 50 | + |
| 51 | +## Q: How do WebAssembly Components and the WebAssembly System Interface (WASI) relate to each other? |
| 52 | + |
| 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. |
| 56 | + |
| 57 | +The set of rich types which can be used by WebAssembly components are called [WebAssembly Interface Types (WIT)][wit]. |
| 58 | + |
| 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. |
| 67 | + |
| 68 | +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. |
| 70 | + |
| 71 | +[wit]: https://component-model.bytecodealliance.org/design/wit.html |
| 72 | +[wasi-http]: https://github.com/WebAssembly/wasi-http |
| 73 | + |
| 74 | +## Q: I see the terms Preview 1 and Preview 2 frequently. What do those refer to? |
| 75 | + |
| 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 |
| 83 | + |
| 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. |
| 86 | + |
| 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]). |
| 89 | + |
| 90 | +## Q: What are component imports? |
| 91 | + |
| 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`. |
| 94 | + |
| 95 | +> [!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. |
| 99 | +> |
| 100 | +> For example, platforms may choose to elide sensitive environment variables, or provide none at all, in practice. |
| 101 | +
|
| 102 | +Imports are easiest illustrated with WIT: |
| 103 | + |
| 104 | +```wit |
| 105 | +package example-namespace:example-package; |
| 106 | +
|
| 107 | +world example-world { |
| 108 | + import wasi:cli/environment@0.2.4; |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +The [`environment` interface in `wasi:cli`][wasi-cli-env] provides various types and functions for interacting with |
| 113 | +environment variables. |
| 114 | + |
| 115 | +The component is said to "import" the `wasi:cli/environment` interface, using the available functions and types therein. |
| 116 | + |
| 117 | +[wasi-cli-env]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/environment.wit |
| 118 | + |
| 119 | +## Q: What are component exports? |
| 120 | + |
| 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 | + |
| 124 | +Exports are easiest illustrated with WIT: |
| 125 | + |
| 126 | +```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 | +} |
| 136 | +``` |
| 137 | + |
| 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. |
| 140 | + |
| 141 | +The component is said to "export" the `example-interface` interface, making available the functions and types therein. |
| 142 | + |
| 143 | +## Still have questions? |
| 144 | + |
| 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]. |
| 147 | + |
| 148 | +[gh-issues-new]: https://github.com/bytecodealliance/component-docs/issues/new |
| 149 | + |
| 150 | +[!NOTE]: # |
0 commit comments