Merge pull request #313 from dschuff/dl_separate_file

Factor dynamic linking section into its own file

8 files changed, 41 insertions, 30 deletions

diff --git a/AstSemantics.md b/AstSemantics.md
index 48d1185..6fb71b1 100644
--- a/AstSemantics.md
+++ b/AstSemantics.md
@@ -326,7 +326,7 @@ the integer value of a coerced function-pointer value is an abstract index and
 does not reveal the actual machine code address of the target function.
 
 In the MVP, function pointer values are local to a single module. The
-[dynamic linking](FutureFeatures.md#dynamic-linking) feature is necessary for
+[dynamic linking](DynamicLinking.md) feature is necessary for
 two modules to pass function pointers back and forth.
 
 Multiple return value calls will be possible, though possibly not in the
diff --git a/CAndC++.md b/CAndC++.md
index 36d0869..af3a16d 100644
--- a/CAndC++.md
+++ b/CAndC++.md
@@ -63,7 +63,7 @@ libraries. Developers will need to ensure that all code linked into an
 application are compiled with the same compiler and options.
 
 In the future, when WebAssembly is extended to support
-[dynamic linking](FutureFeatures.md#dynamic-linking), stable ABIs are
+[dynamic linking](DynamicLinking.md), stable ABIs are
 expected to be defined in accompaniment.
 
 ### Undefined and Implementation-defined Behavior
diff --git a/DyamicLinking.md b/DyamicLinking.md
new file mode 100644
index 0000000..675471f
--- /dev/null
+++ b/DyamicLinking.md
@@ -0,0 +1,34 @@
+# Dynamic linking
+
+Dynamic loading of code is in [the MVP](MVP.md) in the form of
+[modules](Modules.md), but all loaded modules have their own separate
+[linear memory](AstSemantics.md#linear-memory) and cannot share
+[function pointers](AstSemantics.md#calls). Dynamic linking will allow
+developers to share memory and function pointers between WebAssembly
+dynamic libraries.
+
+WebAssembly will support both load-time and run-time (`dlopen`) dynamic linking
+of libraries.
+
+Dynamic linking is especially useful when combined with a Content Distribution
+Network (CDN) such as [hosted libraries][] because the library is only ever
+downloaded and compiled once per user device. It can also allow for smaller
+differential updates, which could be implemented in collaboration with
+[service workers][].
+
+We would like to standardize a single [ABI][] per source language, allowing for
+WebAssembly libraries to interface with each other regardless of compiler. While
+it is highly recommended for compilers targeting WebAssembly to adhere to the
+specified ABI for interoperability, WebAssembly runtimes will be ABI agnostic,
+so it will be possible to use a non-standard ABI for specialized purposes.
+
+Although dynamic linking is not part of the MVP, it has significant implications
+on many aspects of the design that do impact the MVP, such as the way linear
+memory is managed, how module imports and exports are specified, and how globals
+and function pointers work.  Therefore we want to have some viable ideas to
+ensure we don't standardize a design that unnecessarily complicates the design
+or implementation of dynamic linking.
+
+  [hosted libraries]: https://developers.google.com/speed/libraries/
+  [service workers]: https://www.w3.org/TR/service-workers/
+  [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
diff --git a/FutureFeatures.md b/FutureFeatures.md
index 1604636..cb9b725 100644
--- a/FutureFeatures.md
+++ b/FutureFeatures.md
@@ -13,30 +13,7 @@ This is covered in the [tooling](Tooling.md) section.
 
 ## Dynamic linking
 
-[Dynamic loading](MVP.md#code-loading-and-imports) is in [the MVP](MVP.md), but
-all loaded modules have their own [separate linear memory](MVP.md#linear-memory) and cannot share
-[function pointers](MVP.md#function-pointers). Dynamic linking will allow
-developers to share memory and function pointers between WebAssembly modules.
-
-WebAssembly will support both load-time and run-time (`dlopen`) dynamic linking
-of both WebAssembly modules and non-WebAssembly modules (e.g., on the Web, ES6
-ones containing JavaScript).
-
-Dynamic linking is especially useful when combined with a Content Distribution
-Network (CDN) such as [hosted libraries][] because the library is only ever
-downloaded and compiled once per user device. It can also allow for smaller
-differential updates, which could be implemented in collaboration with
-[service workers][].
-
-Standardize a single [ABI][] per source language, allowing for WebAssembly
-modules to interface with each other regardless of compiler. While it is highly
-recommended for compilers targeting WebAssembly to adhere to the specified ABI
-for interoperability, WebAssembly runtimes will be ABI agnostic, so it will be
-possible to use a non-standard ABI for specialized purposes.
-
-  [hosted libraries]: https://developers.google.com/speed/libraries/
-  [service workers]: https://www.w3.org/TR/service-workers/
-  [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
+This is covered in the [dynamic linking](DynamicLinking.md) section.
 
 ## Finer-grained control over memory
 
diff --git a/Modules.md b/Modules.md
index e07e4b6..1210faf 100644
--- a/Modules.md
+++ b/Modules.md
@@ -102,7 +102,7 @@ scope of "all" is a nuanced question), a single app using multiple
 independent libraries would have to hope that all the WebAssembly modules
 transitively used by those libraries "played well" together (e.g., explicitly
 shared `malloc` and coordinated global address ranges). Instead, the
-[dynamic linking future feature](FutureFeatures.md#dynamic-linking) is intended
+[dynamic linking future feature](DynamicLinking.md) is intended
 to allow *explicitly* sharing linear memory between multiple modules.
 
 ## Initial state of linear memory
diff --git a/NonWeb.md b/NonWeb.md
index f0ca6fb..7f1ad00 100644
--- a/NonWeb.md
+++ b/NonWeb.md
@@ -10,7 +10,7 @@ embedded within larger programs.
 Non-Web environments may provide different APIs than Web
 environments, which
 [feature testing](FeatureTest.md) and
-[dynamic linking](FutureFeatures.md#dynamic-linking) will make discoverable and
+[dynamic linking](DynamicLinking.md) will make discoverable and
 usable.
 
 Non-Web environments may include JavaScript VMs (e.g. node.js), however
diff --git a/Portability.md b/Portability.md
index 63c0e8b..400dfa0 100644
--- a/Portability.md
+++ b/Portability.md
@@ -56,4 +56,4 @@ Portability at the C/C++ level can be achieved by programming to
 a standard API (e.g., POSIX) and relying on the compiler and/or libraries to map
 the standard interface to the host environment's available imports either at
 compile-time (via `#ifdef`) or run-time (via [feature detection](FeatureTest.md)
-and dynamic [loading](MVP.md#modules)/[linking](FutureFeatures.md#dynamic-linking)).
+and dynamic [loading](Modules.md)/[linking](DynamicLinking.md)).
diff --git a/Web.md b/Web.md
index 9cf4b21..86765e3 100644
--- a/Web.md
+++ b/Web.md
@@ -23,7 +23,7 @@ and the rest of the Web platform that have been considered:
 * WebAssembly's security model should depend on [CORS][] and
   [subresource integrity][] to enable distribution, especially through content
   distribution networks and to implement
-  [dynamic linking](FutureFeatures.md#dynamic-linking).
+  [dynamic linking](DynamicLinking.md).
 * Once [threads are supported](PostMVP.md#threads), a WebAssembly module would
   shared (including its heap) between workers via `postMessage()`.
   - This also has the effect of explicitly sharing code so that engines don't