[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
git-svn-id: https://llvm.org/svn/llvm-project/lld/trunk@347830 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/README.txt b/docs/README.txt
index eb09a2d..2ed0166 100644
--- a/docs/README.txt
+++ b/docs/README.txt
@@ -6,7 +6,4 @@
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.
diff --git a/docs/WebAssembly.rst b/docs/WebAssembly.rst
index 541b372..424c1a1 100644
--- a/docs/WebAssembly.rst
+++ b/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 @@
``-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
