[WebAssembly] Improve docs for wasm linker
Differential Revision: https://reviews.llvm.org/D57913
git-svn-id: https://llvm.org/svn/llvm-project/lld/trunk@353451 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/WebAssembly.rst b/docs/WebAssembly.rst
index 424c1a1..9e4b3a1 100644
--- a/docs/WebAssembly.rst
+++ b/docs/WebAssembly.rst
@@ -11,8 +11,7 @@
------------------
The format the input object files that lld expects is specified as part of the
-the WebAssembly tool conventions
-https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md.
+the WebAssembly tool conventions on linking_.
This is object format that the llvm will produce when run with the
``wasm32-unknown-unknown`` target. To build llvm with WebAssembly support
@@ -88,10 +87,32 @@
By default the function table is neither imported nor exported, but defined
for internal use only.
-When building shared libraries symbols are exported if they are marked
-as ``visibility=default``. When building executables only the entry point is
-exported by default. In addition any symbol included on the command line via
-``--export`` is also exported.
+Bahaviour
+---------
+
+In general, where possible, the WebAssembly linker attempts to emulate the
+behavior of a traditional ELF linker, and in particular the ELF port of lld.
+For more specific details on how this is achieved see the tool conventions on
+linking_.
+
+Imports and Exports
+~~~~~~~~~~~~~~~~~~~
+
+When building a shared library any symbols marked as ``visibility=default`` will
+be exported. When building an executable, only the entry point and symbols
+flagged as ``WASM_SYMBOL_EXPORTED`` are exported by default. In LLVM the
+``WASM_SYMBOL_EXPORTED`` flag is applied to any symbol in the ``llvm.used`` list
+which corresponds to ``__attribute__((used))`` in C/C++ sources.
+
+In addition, symbols can be exported via the linker command line using
+``--export``.
+
+Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
+used to export symbol in the executable which are marked as
+``visibility=default``.
+
+Garbage Collection
+~~~~~~~~~~~~~~~~~~
Since WebAssembly is designed with size in mind the linker defaults to
``--gc-sections`` which means that all unused functions and data segments will
@@ -112,3 +133,5 @@
- No support for creating shared libraries. The spec for shared libraries in
WebAssembly is still in flux:
https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
+
+.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md
