-
Notifications
You must be signed in to change notification settings - Fork 82
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Document proposed
WIT
to enable component Worlds
This PR sketches out the initial format for WebAssembly profiles, i.e. world files. Signed-off-by: Brian H <brian.hardock@fermyon.com>
- Loading branch information
1 parent
ca2851c
commit 8f3228d
Showing
1 changed file
with
77 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,77 @@ | ||
# Component Worlds (i.e. `world` syntax in `WIT`) | ||
TODO -- Some background and purpose | ||
|
||
## Syntax | ||
The following sections reflect the syntactic additions to `WIT` to enable component Worlds. Lexical structure is identical to that of [WIT.md](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) with the addition of the following keywords: | ||
``` | ||
interface world import export | ||
``` | ||
|
||
Additionally, a new `WIT` token is introduced to allow parsing [URL](https://url.spec.whatwg.org/): | ||
``` | ||
token ::= whitespace | ||
| ... | ||
| quoted-string | ||
``` | ||
|
||
### Item: `interface` | ||
TODO | ||
|
||
### Item: `world` | ||
|
||
A `world` describes a set of imports and exports. From the perspective of a component targeting a `world`, the imports declared in the `world` describe the maximum set of imports that the component may choose to import, whereas the exports declared describe the minimum set of imports that the component must export. | ||
|
||
Conversely, from the perspective of a host implementing the same `world`, the imports declared by the `world` describe the minimum set of functions that must be implemented by the host and supplied as imports to components running on that host, whereas the exports declared describe the maximum set of functions that the host may call in response to host events. Thus, there are inherently two opposite perspectives on each `world`: the host perspective and the guest perspective. | ||
|
||
Because import and export in the syntax shown below go in the same direction as they are defined in a guest component, we can say that a `world` is written from the guest perspective. | ||
|
||
Because the Component Model allows one component to instantiate and link another component, wasm components can technically take either the host or guest perspective for a given `world` (although it will be far more common for components to take the guest perspective). Native host runtimes traditionally only take the host perspective, but in theory a native runtime could natively implement a component that is imported and instantiated by a wasm component, with the native runtime thereby taking the guest perspective. | ||
|
||
By way of metaphor, a `world` is like a function type: | ||
* `world` imports and exports are like parameters and results | ||
* `world` hosts are like the callers of a given function type | ||
* `world` guests are like functions that have a given function type | ||
* The rules for when a given guest is compatible with a given host are like traditional function subtyping | ||
|
||
From a component-model POV: | ||
* a `world` is syntax for a [componenttype](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#type-definitions) | ||
* an `interface` is syntax for an [instancetype](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#type-definitions) | ||
|
||
Thus, given any component `.wasm`, one should be able to automatically derive a `WIT` file containing a `world` that is the syntax for that `.wasm`'s component type. | ||
|
||
Conceretely, the structure of a `World` file is: | ||
|
||
``` | ||
world ::= 'world' id? '{' (import | export)* '}' | ||
``` | ||
|
||
TODO: Example | ||
|
||
#### Item: `import` | ||
|
||
An `import` statement imports an interface/instance. | ||
|
||
The structure of an import statment is: | ||
|
||
``` | ||
import ::= 'import' (id ':')? url | ||
import-kind ::= url | interface | ||
``` | ||
|
||
TODO: Example | ||
|
||
#### Item: `export` | ||
|
||
An `export` statement exports interface/instance. | ||
|
||
The structure of an export statment is: | ||
|
||
``` | ||
export ::= 'export' (id ':')? url | ||
export-kind ::= url | interface | ||
``` | ||
|
||
TODO: Example | ||
|
||
## Name resolution | ||
TODO |