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 the command line flags and the semantics should be the same.
13 The WebAssembly object file format used by LLVM and LLD is specified as part of
14 the WebAssembly tool conventions on linking_.
16 This is the object format that the llvm will produce when run with the
17 ``wasm32-unknown-unknown`` target.
22 The WebAssembly version of lld is installed as **wasm-ld**. It shared many
23 common linker flags with **ld.lld** but also includes several
24 WebAssembly-specific options:
26 .. option:: --no-entry
28 Don't search for the entry point symbol (by default ``_start``).
30 .. option:: --export-table
32 Export the function table to the environment.
34 .. option:: --import-table
36 Import the function table from the environment.
38 .. option:: --export-all
40 Export all symbols (normally combined with --no-gc-sections)
42 .. option:: --export-dynamic
44 When building an executable, export any non-hidden symbols. By default only
45 the entry point and any symbols marked with --export/--export-all are
48 .. option:: --global-base=<value>
50 Address at which to place global data.
52 .. option:: --no-merge-data-segments
54 Disable merging of data segments.
56 .. option:: --stack-first
58 Place stack at start of linear memory rather than after data.
60 .. option:: --compress-relocations
62 Relocation targets in the code section 5-bytes wide in order to potentially
63 occomate the largest LEB128 value. This option will cause the linker to
64 shirnk the code section to remove any padding from the final output. However
65 because it effects code offset, this option is not comatible with outputing
68 .. option:: --allow-undefined
70 Allow undefined symbols in linked binary.
72 .. option:: --import-memory
74 Import memory from the environment.
76 .. option:: --initial-memory=<value>
78 Initial size of the linear memory. Default: static data size.
80 .. option:: --max-memory=<value>
82 Maximum size of the linear memory. Default: unlimited.
84 By default the function table is neither imported nor exported, but defined
85 for internal use only.
90 In general, where possible, the WebAssembly linker attempts to emulate the
91 behaviour of a traditional ELF linker, and in particular the ELF port of lld.
92 For more specific details on how this is achieved see the tool conventions on
98 One way in which the WebAssembly linker differs from traditional native linkers
99 is that function signature checking is strict in WebAssembly. It is a
100 validation error for a module to contain a call site that doesn't agree with
101 the target signature. Even though this is undefined behaviour in C/C++, it is not
102 uncommon to find this in real-world C/C++ programs. For example, a call site in
103 one compilation unit which calls a function defined in another compilation
104 unit but with too many arguments.
106 In order not to generate such invalid modules, lld has two modes of handling such
107 mismatches: it can simply error-out or it can create stub functions that will
108 trap at runtime (functions that contain only an ``unreachable`` instruction)
109 and use these stub functions at the otherwise invalid call sites.
111 The default behaviour is to generate these stub function and to produce
112 a warning. The ``--falal-warnings`` flag can be used to disable this behaviour
113 and error out if mismatched are found.
118 When building a shared library any symbols marked as ``visibility=default`` will
119 be exported. When building an executable, only the entry point and symbols
120 flagged as ``WASM_SYMBOL_EXPORTED`` are exported by default. In LLVM the
121 ``WASM_SYMBOL_EXPORTED`` flag is applied to any symbol in the ``llvm.used`` list
122 which corresponds to ``__attribute__((used))`` in C/C++ sources.
124 In addition, symbols can be exported via the linker command line using
127 Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
128 used to export symbol in the executable which are marked as
129 ``visibility=default``.
134 Since WebAssembly is designed with size in mind the linker defaults to
135 ``--gc-sections`` which means that all unused functions and data segments will
136 be stripped from the binary.
138 The symbols which are preserved by default are:
140 - The entry point (by default ``_start``).
141 - Any symbol which is to be exported.
142 - Any symbol transitively referenced by the above.
144 Weak Undefined Functions
145 ~~~~~~~~~~~~~~~~~~~~~~~~
147 On native platforms, calls to weak undefined functions end up as calls to the
148 null function pointer. With WebAssembly, direct calls must reference a defined
149 function (with the correct signature). In order to handle this case the linker
150 will generate function a stub containing only the ``unreachable`` instruction
151 and use this for any direct references to an undefined weak function.
153 For example a runtime call to a weak undefined function ``foo`` will up trapping
154 on ``unreachable`` inside and linker-generated function called
160 - Merging of data section similar to ``SHF_MERGE`` in the ELF world is not
162 - No support for creating shared libraries. The spec for shared libraries in
163 WebAssembly is still in flux:
164 https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
166 .. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md