diff options
author | Sam Clegg <sbc@chromium.org> | 2018-11-29 02:55:25 +0000 |
---|---|---|
committer | Sam Clegg <sbc@chromium.org> | 2018-11-29 02:55:25 +0000 |
commit | db8dd23204fbda26f03a04dde65929f09b5e5896 (patch) | |
tree | 065f446173b52680ac2f1e32a343af65311a21e2 /lld/docs/WebAssembly.rst | |
parent | 339af528049aea74295d2447121c5487f9e19301 (diff) | |
download | llvm-db8dd23204fbda26f03a04dde65929f09b5e5896.zip llvm-db8dd23204fbda26f03a04dde65929f09b5e5896.tar.gz llvm-db8dd23204fbda26f03a04dde65929f09b5e5896.tar.bz2 |
[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
Diffstat (limited to 'lld/docs/WebAssembly.rst')
-rw-r--r-- | lld/docs/WebAssembly.rst | 108 |
1 files changed, 92 insertions, 16 deletions
diff --git a/lld/docs/WebAssembly.rst b/lld/docs/WebAssembly.rst index 541b372..424c1a1 100644 --- a/lld/docs/WebAssembly.rst +++ b/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 |