Merge pull request #119 from rylev/move-canonical-abi

Move the canonical abi section to an advanced section

component-model/src/SUMMARY.md

@@ -11,7 +11,6 @@
 - [Worlds](./design/worlds.md)
 - [WIT](./design/wit.md)
 - [Packages](./design/packages.md)
-- [Canonical ABI](./design/canonical-abi.md)
 
 # Using Component Model
 
@@ -30,3 +29,7 @@
 
 - [Wasmtime](./runtimes/wasmtime.md)
 - [jco](./runtimes/jco.md)
+
+# Advanced Topics
+
+- [Canonical ABI](./advanced/canonical-abi.md)

component-model/src/design/components.md

@@ -1,6 +1,6 @@
 # Components
 
-* Logically, components are containers for modules - or other components - which express their [interfaces](./interfaces.md) and dependencies via [WIT](./wit.md) and the [Canonical ABI](./canonical-abi.md).
+* Logically, components are containers for modules - or other components - which express their [interfaces](./interfaces.md) and dependencies via [WIT](./wit.md).
 * Conceptually, components are self-describing units of code that interact only through interfaces instead of shared memory.
 * Physically, a **component** is a specially-formatted WebAssembly file. Internally, the component could include multiple traditional ("core") WebAssembly modules, and sub-components, composed via their imports and exports.
 

component-model/src/design/why-component-model.md

@@ -6,13 +6,13 @@ Core modules are, however, limited in how they expose their functionality to the
 
 For Wasm modules to interoperate, therefore, there needs to be an agreed-upon way for exposing those richer types across module boundaries.
 
-In the component model, these type definitions are written in a language called [WIT (Wasm Interface Type)](./wit.md), and the way they translate into bits and bytes is called the [Canonical ABI (Application Binary Interface)](./canonical-abi.md). A Wasm [component](./components.md) is thus a wrapper around a core module that specifies its imports and exports using such [Interfaces](./interfaces.md).
+In the component model, these type definitions are written in a language called [WIT (Wasm Interface Type)](./wit.md), and the way they translate into bits and bytes is called the [Canonical ABI (Application Binary Interface)](./../advanced/canonical-abi.md). A Wasm [component](./components.md) is thus a wrapper around a core module that specifies its imports and exports using such [Interfaces](./interfaces.md).
 
 The agreement of an interface adds a new dimension to Wasm portability. Not only are components portable across architectures and operating systems, but they are now portable across languages. A Go component can communicate directly and safely with a C or Rust component. It need not even know which language another component was written in - it needs only the component interface, expressed in WIT. Additionally, components can be linked into larger graphs, with one component's exports satisfying another's imports.
 
 Combined with Wasm's strong sandboxing, this opens the door to yet further benefits. By expressing higher-level semantics than integers and floats, it becomes possible to statically analyse and reason about a component's behaviour - to enforce and guarantee properties just by looking at the surface of the component. The relationships within a graph of components can be analysed, for example to verify that a component containing business logic has no access to a component containing personally identifiable information.
 
-Moreover, components interact _only_ through the Canonical ABI. Specifically, unlike core modules, components may not export Wasm memory. This not only reinforces sandboxing, but enables interoperation between languages that make different assumptions about memory - for example, allowing a component that relies on Wasm GC (garbage collected) memory to collaborate with one that uses conventional linear memory.
+Moreover, a component interacts with a runtime or other components _only_ by calling its imports and having its exports called. Specifically, unlike core modules, a component may not export Wasm memory, and thus it cannot indirectly communicate to others by writing to its memory and having others read from that memory. This not only reinforces sandboxing, but enables interoperation between languages that make different assumptions about memory - for example, allowing a component that relies on Wasm GC (garbage collected) memory to collaborate with one that uses conventional linear memory.
 
 Now that you have a better idea about how the component model can help you, take a look at [how to build components](../language-support.md) in your favorite language!