[WebAssembly] Update docs
Differential Revision: https://reviews.llvm.org/D52048
git-svn-id: https://llvm.org/svn/llvm-project/lld/trunk@343155 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 264d221..4485e50 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,14 +20,86 @@
``-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:: --[no-]export-default
+
+ Export symbols marked as 'default' visibility. Default: true
+
+.. option:: --global-base=<value>
+
+ Address at which to place global data
+
+.. option:: --[no-]merge-data-segments
+
+ Enable/Disble merging of data segments. Default: true
+
+.. option:: --stack-first
+
+ Place stack at start of linear memory rather than after data
+
+.. option:: --compress-relocations
+
+ Compress the relocation targets in the code section.
+
+.. 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.
+
+Symbols are exported if they are marked as ``visibility=default`` at compile
+time or if they are included on the command line via ``--export``.
+
+Since WebAssembly is designed with size in mind the linker defaults to
+``--gc-sections`` which means that all un-used 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:
-
-- 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 similiar to ``SHF_MERGE`` in the ELF world is not
+ supported.
+- No support for creating shared libaries. The spec for shared libraries in
+ WebAssembly is still in flux:
+ https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
