contrib/llvm/tools/lld/docs/WebAssembly.rst

   1 WebAssembly lld port
   2 ====================
   3
   4 The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
   5 a WebAssembly binary as its output.  For the most part it tries to mimic the
   6 behaviour of traditional ELF linkers and specifically the ELF lld port.  Where
   7 possible that command line flags and the semantics should be the same.
   8
   9
  10 Object file format
  11 ------------------
  12
  13 The format the input object files that lld expects is specified as part of the
  14 the WebAssembly tool conventions
  15 https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md.
  16
  17 This is object format that the llvm will produce when run with the
  18 ``wasm32-unknown-unknown`` target.  To build llvm with WebAssembly support
  19 currently requires enabling the experimental backed using
  20 ``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
  21
  22
  23 Usage
  24 -----
  25
  26 The WebAssembly version of lld is installed as **wasm-ld**.  It shared many
  27 common linker flags with **ld.lld** but also includes several
  28 WebAssembly-specific options:
  29
  30 .. option:: --no-entry
  31
  32   Don't search for the entry point symbol (by default ``_start``).
  33
  34 .. option:: --export-table
  35
  36   Export the function table to the environment.
  37
  38 .. option:: --import-table
  39
  40   Import the function table from the environment.
  41
  42 .. option:: --export-all
  43
  44   Export all symbols (normally combined with --no-gc-sections)
  45
  46 .. option:: --export-dynamic
  47
  48   When building an executable, export any non-hidden symbols.  By default only
  49   the entry point and any symbols marked with --export/--export-all are
  50   exported.
  51
  52 .. option:: --global-base=<value>
  53
  54   Address at which to place global data.
  55
  56 .. option:: --no-merge-data-segments
  57
  58   Disable merging of data segments.
  59
  60 .. option:: --stack-first
  61
  62   Place stack at start of linear memory rather than after data.
  63
  64 .. option:: --compress-relocations
  65
  66   Relocation targets in the code section 5-bytes wide in order to potentially
  67   occomate the largest LEB128 value.  This option will cause the linker to
  68   shirnk the code section to remove any padding from the final output.  However
  69   because it effects code offset, this option is not comatible with outputing
  70   debug information.
  71
  72 .. option:: --allow-undefined
  73
  74   Allow undefined symbols in linked binary.
  75
  76 .. option:: --import-memory
  77
  78   Import memory from the environment.
  79
  80 .. option:: --initial-memory=<value>
  81
  82   Initial size of the linear memory. Default: static data size.
  83
  84 .. option:: --max-memory=<value>
  85
  86   Maximum size of the linear memory. Default: unlimited.
  87
  88 By default the function table is neither imported nor exported, but defined
  89 for internal use only.
  90
  91 When building shared libraries symbols are exported if they are marked
  92 as ``visibility=default``.  When building executables only the entry point is
  93 exported by default.  In addition any symbol included on the command line via
  94 ``--export`` is also exported.
  95
  96 Since WebAssembly is designed with size in mind the linker defaults to
  97 ``--gc-sections`` which means that all unused functions and data segments will
  98 be stripped from the binary.
  99
 100 The symbols which are preserved by default are:
 101
 102 - The entry point (by default ``_start``).
 103 - Any symbol which is to be exported.
 104 - Any symbol transitively referenced by the above.
 105
 106
 107 Missing features
 108 ----------------
 109
 110 - Merging of data section similar to ``SHF_MERGE`` in the ELF world is not
 111   supported.
 112 - No support for creating shared libraries.  The spec for shared libraries in
 113   WebAssembly is still in flux:
 114   https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md