[PATCH] D57913: [WebAssembly] Improve docs for wasm linker

[Sam Clegg via Phabricator via llvm-commits]

sbc100 updated this revision to Diff 185826.
sbc100 added a comment.

- feedback


Repository:
  rLLD LLVM Linker

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D57913/new/

https://reviews.llvm.org/D57913

Files:
  docs/WebAssembly.rst


Index: docs/WebAssembly.rst
===================================================================
--- docs/WebAssembly.rst
+++ 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D57913.185826.patch
Type: text/x-patch
Size: 2400 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20190207/9f972a5b/attachment.bin>