Skip to content

Commit 7981778

Browse files
committed
Add the inline-vs-import distinction to description and diagram
1 parent 0964d03 commit 7981778

2 files changed

Lines changed: 48 additions & 10 deletions

File tree

design/mvp/Linking.md

Lines changed: 47 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,10 @@
22

33
The Component Model enables multiple complementary forms of linking which allow
44
producer toolchains to control which Core WebAssembly modules do or don't share
5-
low-level memory. At a high-level, there are two primary forms of linking:
6-
**shared-everything linking** and **shared-nothing linking**:
5+
low-level memory. At a high-level, there are two primary axes of choices to
6+
make when linking:
7+
* **shared-everything** vs. **shared-nothing**:
8+
* **inline** vs. **import**
79

810
When two modules are linked together to share Core WebAssembly `memory` and
911
`table` instances, it is called **shared-everything linking**. In this case,
@@ -39,6 +41,18 @@ producer toolchain, it's completely invisible to the Component Model and the
3941
runtime and thus mostly only relevant when talking about entire end-to-end
4042
workflows (like we'll do next).
4143

44+
Regardless of whether or not memory is shared when linking, when two (child)
45+
modules or components are linked together to create a new (parent) component,
46+
the Component Model gives two options for how the parent represents its
47+
children:
48+
* A parent component can **inline** its children, literally storing the child
49+
module or component binaries in a contiguous byte range inside the parent
50+
(via the `core:module` and `component` sections in the [binary format]).
51+
* A parent component can **import** its children, using the import name to
52+
refer to modules or components stored in an external shared registry that is
53+
mutually known to later stages in the deployment pipeline (specifically with
54+
the [`depname`] case of `importname` in the text and binary format).
55+
4256
Given this terminology, the following diagram shows how the different forms of
4357
linking can be used together in the context of C/C++:
4458
<p align="center"><img src="examples/images/combined-linking.svg" width="800"></p>
@@ -71,6 +85,19 @@ further composed with other components. For a low-level sketch of how
7185
shared-nothing linking works at the WAT level, see
7286
[this example](examples/LinkTimeVirtualization.md).
7387

88+
With both `wasm-tools link` and `wac`, the developer will have the option to
89+
either store child modules or components **inline** or to **import** them from
90+
an external registry. This registry toolchain integration is still in progress,
91+
but by reusing common support libries such as [`wasm-pkg-tools`], higher-level
92+
tooling can uniformly interact with multiple kinds of storage backends such as
93+
local directories, [OCI Wasm Artifacts] stored in standard [OCI Registries] and
94+
[warg registries]. Of note, even when modules or components are stored inline
95+
by earlier stages of the build pipeline, when creating an OCI Wasm Artifact, a
96+
toolchain can enable deduplication by content-hash of common modules or
97+
components by placing them in separate OCI [`layers`] which are imported via
98+
[`hashname`] by the root component stored in the first layer of the OCI Wasm
99+
Artifact.
100+
74101

75102
## Fully-runtime dynamic linking
76103

@@ -127,16 +154,27 @@ or DLL that can be efficiently loaded at runtime.
127154
post-Preview 2 features of WIT and the Component Model.)
128155

129156

130-
[ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
131-
[AOT compilation]: https://en.wikipedia.org/wiki/Ahead-of-time_compilation
157+
[Canonical ABI]: CanonicalABI.md
158+
[Binary Format]: Binary.md
159+
[WIT]: WIT.md
160+
[`depname`]: Explainer.md#import-and-export-definitions
161+
[`hashname`]: Explainer.md#import-and-export-definitions
162+
132163
[WebAssembly/tool-conventions]: https://github.com/WebAssembly/tool-conventions
133164
[WebAssembly Object File]: https://github.com/WebAssembly/tool-conventions/blob/main/Linking.md
134-
[`wit-bindgen`]: https://github.com/bytecodealliance/wit-bindgen
135-
[Canonical ABI]: CanonicalABI.md
136165
[Custom Section]: https://webassembly.github.io/spec/core/binary/modules.html#custom-section
166+
[JS API]: https://webassembly.github.io/spec/js-api/index.html
167+
[JIT Future Feature]: https://github.com/WebAssembly/design/blob/main/FutureFeatures.md#platform-independent-just-in-time-jit-compilation
168+
137169
[`wasm-ld`]: https://lld.llvm.org/WebAssembly.html
170+
[`wit-bindgen`]: https://github.com/bytecodealliance/wit-bindgen
138171
[`wasm-tools`]: https://github.com/bytecodealliance/wasm-tools#tools-included
139172
[`wac`]: https://github.com/bytecodealliance/wac
140-
[JS API]: https://webassembly.github.io/spec/js-api/index.html
141-
[JIT Future Feature]: https://github.com/WebAssembly/design/blob/main/FutureFeatures.md#platform-independent-just-in-time-jit-compilation
142-
[WIT]: WIT.md
173+
[`wasm-pkg-tools`]: https://github.com/bytecodealliance/wasm-pkg-tools
174+
175+
[ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
176+
[AOT Compilation]: https://en.wikipedia.org/wiki/Ahead-of-time_compilation
177+
[OCI Wasm Artifacts]: https://tag-runtime.cncf.io/wgs/wasm/deliverables/wasm-oci-artifact/
178+
[OCI Registries]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#definitions
179+
[`layers`]: https://github.com/opencontainers/image-spec/blob/v1.0.1/manifest.md
180+
[warg registries]: https://warg.io/

design/mvp/examples/images/combined-linking.svg

Lines changed: 1 addition & 1 deletion
Loading

0 commit comments

Comments
 (0)