Merge pull request #35 from WebAssembly/component-rebase

Reframe Module Linking as the first proposal of the Component Model

Author: lukewagner

README.md

@@ -1,38 +1,17 @@
-# Component Model design and specification
+# Module Linking proposal
 
-This repository contains documents describing the high-level [goals],
-[use cases], [design choices] and [FAQ] of the component model.
+This repository contains the Module Linking proposal, which is the
+first proposal of the [Component Model].
 
-In the future, as proposals get merged, the repository will additionally
-contain the spec, a reference interpreter, a test suite, and directories for
-each proposal with the proposal's explainer and specific design documents.
-
-## Design Process & Contributing
-
-At this early stage, this repository only contains high-level design documents
-and discussions about the Component Model in general. Detailed explainers,
-specifications and discussions are broken into the following two repositories
-which, together, will form the "MVP" of the Component Model:
-
-* The [module-linking] proposal will initialize the Component Model
-  specification, adding the ability for WebAssembly to import, nest,
-  instantiate and link multiple Core WebAssembly modules without host-specific
-  support.
-
-* The [interface-types] proposal will extend the Component Model specification
-  with a new set of high-level types for defining shared-nothing,
-  language-neutral "components".
+Links:
+* the general [explainer](design/proposals/module-linking/Explainer.md) for this proposal
+* a sketch of the [binary format](design/proposals/module-linking/Binary.md)
+* a description of [module subtyping](design/proposals/module-linking/Subtyping.md)
 
 All Component Model work is done as part of the [W3C WebAssembly Community Group].
 To contribute to any of these repositories, see the Community Group's
 [Contributing Guidelines].
 
-
-[goals]: design/high-level/Goals.md
-[use cases]: design/high-level/UseCases.md
-[design choices]: design/high-level/Choices.md
-[FAQ]: design/high-level/FAQ.md
-[module-linking]: https://github.com/webassembly/module-linking/
-[interface-types]: https://github.com/webassembly/interface-types/
+[Component Model]: https://github.com/webassembly/component-model/
 [W3C WebAssembly Community Group]: https://www.w3.org/community/webassembly/
 [Contributing Guidelines]: https://webassembly.org/community/contributing/

design/proposals/module-linking/Binary.md

@@ -5,96 +5,89 @@ This document walks through the
 use case.
 
 We start with a child module that has been written and compiled separately,
-without regard to the parent module. It imports `wasi_file` to do file I/O:
-
+without regard to the parent module. It imports `wasi:filesystem` to do file I/O:
 ```wasm
-(module $CHILD
-  (import "wasi_file" (instance $wasi-file
-    (export "read" (func (param i32 i32 i32) (result i32)))
-    (export "write" (func (param i32 i32 i32) (result i32)))
-  ))
+(module $Child
+  (import "wasi:filesystem" "read" (func (param i32 i32 i32) (result i32)))
+  (import "wasi:filesystem" "write" (func (param i32 i32 i32) (result i32)))
   (func $play (export "play")
     ...
-    call (func $wasi-file "read")
-    ...
   )
 )
 ```
 
-We want to write a `parent` module that reuses `child`, but we don't want to
-give it real file operations, but rather some file operations we virtualized.
-For example, maybe we want an adapter that automatically compresses on write
-and decompresses on read. This adapter module can be factored out and reused
-as a separate module that imports a "real" `wasi_file` instance and uses it
-to implement a new virtualized `wasi_file` instance:
-
+We want to write a parent module that reuses the child module, but we don't
+want to give it real file operations, but rather some virtual filesystem.
+This virtual filesystem can be factored out and reused as a separate module
+that imports the "real" `wasi:filesystem` and exports a virtualized
+implementation of all the `wasi:filesystem` operations:
 ```wasm
-(module $VIRTUALIZE
-  (type $WasiFile (instance
-    (export "read" (func (param i32 i32 i32) (result i32)))
-    (export "write" (func (param i32 i32 i32) (result i32)))
-  ))
-  (import "wasi_file" (instance $wasi-file (type $WasiFile)))
+(module $VirtualFS
+  (import "wasi:filesystem" "read" (func (param i32 i32 i32) (result i32)))
+  (import "wasi:filesystem" "write" (func (param i32 i32 i32) (result i32)))
 
   (func (export "read") (param i32 i32 i32) (result i32)
-    ... impl
+    ...
   )
   (func (export "write") (param i32 i32 i32) (result i32)
-    ... impl
+    ...
   )
 )
 ```
 
-We can now write the parent module by composing `$VIRTUALIZE` and `$CHILD`:
-
+We can now write the parent module as an adapter module that composes `$Child`
+and `$VirtualFS`:
 ```wasm
-(module $PARENT
-  (type $WasiFile (instance
+(adapter module $Parent
+  (type $FSInstance (instance
     (export "read" (func (param i32 i32 i32) (result i32)))
     (export "write" (func (param i32 i32 i32) (result i32)))
   ))
-  (import "wasi_file" (instance $real-wasi (type $WasiFile)))
+  (import "wasi:filesystem" (instance $real-fs (type $FSInstance)))
 
-  (import "virtualize" (module $VIRTUALIZE
-    (import "wasi_file" (instance (type outer $PARENT $WasiFile)))
-    (export (type outer $PARENT $WasiFile))
+  (import "./virtualize.wasm" (module $VirtualFS
+    (import "wasi:filesystem" (instance (type $FSInstance)))
+    (export (type $FSInstance))
   ))
-  (import "child" (module $CHILD
-    (import "wasi_file" (instance (type outer $PARENT $WasiFile)))
+  (import "./child.wasm" (module $Child
+    (import "wasi:filesystem" (instance (type $FSInstance)))
     (export "play" (func))
   ))
 
-  (instance $virt-wasi (instantiate $VIRTUALIZE (import "wasi_file" (instance $real-wasi))))
-  (instance $child (instantiate $CHILD (import "wasi_file" (instance $virt-wasi))))
-
-  (func (export "work")
-    ...
-    call (func $child "play")
-    ...
-  )
+  (instance $virt-fs (instantiate $VirtualFS (import "wasi:filesystem" (instance $real-fs))))
+  (instance $child (instantiate $Child (import "wasi:filesystem" (instance $virt-fs))))
 )
 ```
-
-Here, we assume the host understands relative file paths, but we could also bundle
-all 3 files into one compound `$PARENT-BUNDLE` module:
-
+This example demonstrates several features of the Module Linking proposal:
+* The first line of the module is a [type definition](Explainer.md#type-definitions),
+  factoring out an instance type so it can be reused four times below.
+* The next line is an [import definition](Explainer.md#import-definitions),
+  importing an instance of `wasi:filesystem`. This instance import is logically
+  equivalent to two two-level imports in a core module with `wasi:filesystem` as the
+  "module" name and `read`/`write` as the "field" name.
+* The following two imports import *modules*, which is the other new importable
+  type (after instances).
+* The final two lines are [instance definitions](Explainer.md#instance-definitions),
+  instantiating and wiring up the `VirtualizeFS` and `Child` modules.
+
+Here, we assume that the host understands relative file paths. To remove this host
+assumption, a tool could replace the imports definitions in `$Parent` with
+[module definitions](Explainer.md#module-definitions):
 ```wasm
-(module $PARENT-BUNDLE
-  (type $WasiFile     ...same as above)
-  (import "wasi_file" ...same as above)
-
-  (module $VIRTUALIZE ... copied inline)
-  (module $CHILD      ... copied inline)
+(adapter module $Parent
+  (type $FSInstance         ... same as above)
+  (import "wasi:filesystem" ... same as above)
 
-  (instance $virt-wasi ...same as above)
-  (instance $child     ...same as above)
+  (module $VirtualizeFS     ... copied inline)
+  (module $Child            ... copied inline)
 
-  (func (export "work") ...same as above)
+  (instance $virt-fs        ... same as above)
+  (instance $child          ... same as above)
 )
 ```
 
-In general, a tool can trivially transform between nested modules and module
-imports without any understanding of their contents which allows bundling tools
-to optimize for the deployment target. For example, on the Web, the choice to
+In general, a tool can trivially go between nested modules and module imports
+without any understanding of their contents which allows bundling tools to
+optimize for the deployment target. For example, on the Web, the choice to
 import vs. nest modules can be based on the usual bundling considerations of
 caching, reuse and minimizing fetches.