[lld] r353451 - [WebAssembly] Improve docs for wasm linker

[Sam Clegg via llvm-commits]

Author: sbc
Date: Thu Feb  7 11:05:26 2019
New Revision: 353451

URL: http://llvm.org/viewvc/llvm-project?rev=353451&view=rev
Log:
[WebAssembly] Improve docs for wasm linker

Differential Revision: https://reviews.llvm.org/D57913

Modified:
    lld/trunk/docs/WebAssembly.rst

Modified: lld/trunk/docs/WebAssembly.rst
URL: http://llvm.org/viewvc/llvm-project/lld/trunk/docs/WebAssembly.rst?rev=353451&r1=353450&r2=353451&view=diff
==============================================================================
--- lld/trunk/docs/WebAssembly.rst (original)
+++ lld/trunk/docs/WebAssembly.rst Thu Feb  7 11:05:26 2019
@@ -11,8 +11,7 @@ Object file format
 ------------------
 
 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 @@ WebAssembly-specific options:
 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 @@ Missing features
 - 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