[WebAssembly] Update docs

This is an reland of rL343155 which got reverted because
of a sphinx failure on the buildbot.

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

llvm-svn: 347830

lld/docs/README.txt

@@ -6,7 +6,4 @@ currently tested with Sphinx 1.1.3.
 
 We currently use the 'nature' theme and a Beaker inspired structure.
 
-To rebuild documents into html:
-
-   [/lld/docs]> make html
-
+See sphinx_intro.rst for more details.

lld/docs/WebAssembly.rst

@@ -1,13 +1,10 @@
 WebAssembly lld port
 ====================
 
-Note: The WebAssembly port is still a work in progress and is be lacking
-certain features.
-
 The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
-a WebAssembly binary as its output.  For the most part this port tried to mimic
-the behaviour of traditional ELF linkers and specifically the ELF lld port.
-Where possible that command line flags and the semantics should be the same.
+a WebAssembly binary as its output.  For the most part it tries to mimic the
+behaviour of traditional ELF linkers and specifically the ELF lld port.  Where
+possible that command line flags and the semantics should be the same.
 
 
 Object file format
@@ -23,16 +20,95 @@ currently requires enabling the experimental backed using
 ``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
 
 
+Usage
+-----
+
+The WebAssembly version of lld is installed as **wasm-ld**.  It shared many 
+common linker flags with **ld.lld** but also includes several
+WebAssembly-specific options:
+
+.. option:: --no-entry
+
+  Don't search for the entry point symbol (by default ``_start``).
+
+.. option:: --export-table
+
+  Export the function table to the environment.
+
+.. option:: --import-table
+
+  Import the function table from the environment.
+
+.. option:: --export-all
+
+  Export all symbols (normally combined with --no-gc-sections)
+
+.. option:: --export-dynamic
+
+  When building an executable, export any non-hidden symbols.  By default only
+  the entry point and any symbols marked with --export/--export-all are
+  exported.
+
+.. option:: --global-base=<value>
+
+  Address at which to place global data.
+
+.. option:: --no-merge-data-segments
+
+  Disable merging of data segments.
+
+.. option:: --stack-first
+
+  Place stack at start of linear memory rather than after data.
+
+.. option:: --compress-relocations
+
+  Relocation targets in the code section 5-bytes wide in order to potentially
+  occomate the largest LEB128 value.  This option will cause the linker to
+  shirnk the code section to remove any padding from the final output.  However
+  because it effects code offset, this option is not comatible with outputing
+  debug information.
+
+.. option:: --allow-undefined
+
+  Allow undefined symbols in linked binary.
+
+.. option:: --import-memory
+
+  Import memory from the environment.
+
+.. option:: --initial-memory=<value>
+
+  Initial size of the linear memory. Default: static data size.
+
+.. option:: --max-memory=<value>
+
+  Maximum size of the linear memory. Default: unlimited.
+
+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.
+
+Since WebAssembly is designed with size in mind the linker defaults to
+``--gc-sections`` which means that all unused functions and data segments will
+be stripped from the binary.
+
+The symbols which are preserved by default are:
+
+- The entry point (by default ``_start``).
+- Any symbol which is to be exported.
+- Any symbol transitively referenced by the above.
+
+
 Missing features
 ----------------
 
-There are several key features that are not yet implement in the WebAssembly
-ports:
-
-- Support for building shared libraries via ``-shared`` is still as work in
-  progress.
-- COMDAT support.  This means that support for C++ is still very limited.
-- Function stripping.  Currently there is no support for ``--gc-sections`` so
-  functions and data from a given object will linked as a unit.
-- Section start/end symbols.  The synthetic symbols that mark the start and
-  of data regions are not yet created in the output file.
+- Merging of data section similar to ``SHF_MERGE`` in the ELF world is not
+  supported.
+- 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