|
2 | 2 |
|
3 | 3 | The Component Model enables multiple complementary forms of linking which allow |
4 | 4 | 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** |
7 | 9 |
|
8 | 10 | When two modules are linked together to share Core WebAssembly `memory` and |
9 | 11 | `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 |
39 | 41 | runtime and thus mostly only relevant when talking about entire end-to-end |
40 | 42 | workflows (like we'll do next). |
41 | 43 |
|
| 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 | + |
42 | 56 | Given this terminology, the following diagram shows how the different forms of |
43 | 57 | linking can be used together in the context of C/C++: |
44 | 58 | <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 |
71 | 85 | shared-nothing linking works at the WAT level, see |
72 | 86 | [this example](examples/LinkTimeVirtualization.md). |
73 | 87 |
|
| 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 | + |
74 | 101 |
|
75 | 102 | ## Fully-runtime dynamic linking |
76 | 103 |
|
@@ -127,16 +154,27 @@ or DLL that can be efficiently loaded at runtime. |
127 | 154 | post-Preview 2 features of WIT and the Component Model.) |
128 | 155 |
|
129 | 156 |
|
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 | + |
132 | 163 | [WebAssembly/tool-conventions]: https://github.com/WebAssembly/tool-conventions |
133 | 164 | [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 |
136 | 165 | [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 | + |
137 | 169 | [`wasm-ld`]: https://lld.llvm.org/WebAssembly.html |
| 170 | +[`wit-bindgen`]: https://github.com/bytecodealliance/wit-bindgen |
138 | 171 | [`wasm-tools`]: https://github.com/bytecodealliance/wasm-tools#tools-included |
139 | 172 | [`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/ |
0 commit comments