• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1WebAssembly lld port
2====================
3
4The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
5a WebAssembly binary as its output.  For the most part it tries to mimic the
6behaviour of traditional ELF linkers and specifically the ELF lld port.  Where
7possible the command line flags and the semantics should be the same.
8
9
10Object file format
11------------------
12
13The WebAssembly object file format used by LLVM and LLD is specified as part of
14the WebAssembly tool conventions on linking_.
15
16This is the object format that the llvm will produce when run with the
17``wasm32-unknown-unknown`` target.
18
19Usage
20-----
21
22The WebAssembly version of lld is installed as **wasm-ld**.  It shared many
23common linker flags with **ld.lld** but also includes several
24WebAssembly-specific options:
25
26.. option:: --no-entry
27
28  Don't search for the entry point symbol (by default ``_start``).
29
30.. option:: --export-table
31
32  Export the function table to the environment.
33
34.. option:: --import-table
35
36  Import the function table from the environment.
37
38.. option:: --export-all
39
40  Export all symbols (normally combined with --no-gc-sections)
41
42  Note that this will not export linker-generated mutable globals unless
43  the resulting binaryen already includes the 'mutable-globals' features
44  since that would otherwise create and invalid binaryen.
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 as exports (either via the command line
50  or via the `export-name` source attribute) are 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 are 5-bytes wide in order to
67  potentially accommodate the largest LEB128 value.  This option will cause the
68  linker to shrink the code section to remove any padding from the final
69  output.  However because it affects code offset, this option is not
70  compatible with outputting debug information.
71
72.. option:: --allow-undefined
73
74  Allow undefined symbols in linked binary.  This is the legacy
75  flag which corresponds to ``--unresolved-symbols=import-functions``.
76
77.. option:: --unresolved-symbols=<method>
78
79  This is a more full featured version of ``--allow-undefined``.
80  The semanatics of the different methods are as follows:
81
82  report-all:
83
84     Report all unresolved symbols.  This is the default.  Normally the linker
85     will generate an error message for each reported unresolved symbol but the
86     option ``--warn-unresolved-symbols`` can change this to a warning.
87
88  ignore-all:
89
90     Resolve all undefined symbols to zero.  For data and function addresses
91     this is trivial.  For direct function calls, the linker will generate a
92     trapping stub function in place of the undefined function.
93
94  import-functions:
95
96     Generate WebAssembly imports for any undefined functions.  Undefined data
97     symbols are resolved to zero as in ``ignore-all``.  This corresponds to
98     the legacy ``--allow-undefined`` flag.
99
100.. option:: --import-memory
101
102  Import memory from the environment.
103
104.. option:: --initial-memory=<value>
105
106  Initial size of the linear memory. Default: static data size.
107
108.. option:: --max-memory=<value>
109
110  Maximum size of the linear memory. Default: unlimited.
111
112By default the function table is neither imported nor exported, but defined
113for internal use only.
114
115Behaviour
116---------
117
118In general, where possible, the WebAssembly linker attempts to emulate the
119behaviour of a traditional ELF linker, and in particular the ELF port of lld.
120For more specific details on how this is achieved see the tool conventions on
121linking_.
122
123Function Signatures
124~~~~~~~~~~~~~~~~~~~
125
126One way in which the WebAssembly linker differs from traditional native linkers
127is that function signature checking is strict in WebAssembly.  It is a
128validation error for a module to contain a call site that doesn't agree with
129the target signature.  Even though this is undefined behaviour in C/C++, it is not
130uncommon to find this in real-world C/C++ programs.  For example, a call site in
131one compilation unit which calls a function defined in another compilation
132unit but with too many arguments.
133
134In order not to generate such invalid modules, lld has two modes of handling such
135mismatches: it can simply error-out or it can create stub functions that will
136trap at runtime (functions that contain only an ``unreachable`` instruction)
137and use these stub functions at the otherwise invalid call sites.
138
139The default behaviour is to generate these stub function and to produce
140a warning.  The ``--fatal-warnings`` flag can be used to disable this behaviour
141and error out if mismatched are found.
142
143Exports
144~~~~~~~
145
146When building a shared library any symbols marked as ``visibility=default`` will
147be exported.
148
149When building an executable, only the entry point (``_start``) and symbols with
150the ``WASM_SYMBOL_EXPORTED`` flag are exported by default.  In LLVM the
151``WASM_SYMBOL_EXPORTED`` flag is set by the ``wasm-export-name`` attribute which
152in turn can be set using ``__attribute__((export_name))`` clang attribute.
153
154In addition, symbols can be exported via the linker command line using
155``--export``.
156
157Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
158used to export symbols in the executable which are marked as
159``visibility=default``.
160
161Imports
162~~~~~~~
163
164By default no undefined symbols are allowed in the final binary.  The flag
165``--allow-undefined`` results in a WebAssembly import being defined for each
166undefined symbol.  It is then up to the runtime to provide such symbols.
167
168Alternatively symbols can be marked in the source code as with the
169``import_name`` and/or ``import_module`` clang attributes which signals that
170they are expected to be undefined at static link time.
171
172Garbage Collection
173~~~~~~~~~~~~~~~~~~
174
175Since WebAssembly is designed with size in mind the linker defaults to
176``--gc-sections`` which means that all unused functions and data segments will
177be stripped from the binary.
178
179The symbols which are preserved by default are:
180
181- The entry point (by default ``_start``).
182- Any symbol which is to be exported.
183- Any symbol transitively referenced by the above.
184
185Weak Undefined Functions
186~~~~~~~~~~~~~~~~~~~~~~~~
187
188On native platforms, calls to weak undefined functions end up as calls to the
189null function pointer.  With WebAssembly, direct calls must reference a defined
190function (with the correct signature).  In order to handle this case the linker
191will generate function a stub containing only the ``unreachable`` instruction
192and use this for any direct references to an undefined weak function.
193
194For example a runtime call to a weak undefined function ``foo`` will up trapping
195on ``unreachable`` inside and linker-generated function called
196``undefined:foo``.
197
198Missing features
199----------------
200
201- Merging of data section similar to ``SHF_MERGE`` in the ELF world is not
202  supported.
203- No support for creating shared libraries.  The spec for shared libraries in
204  WebAssembly is still in flux:
205  https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
206
207.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md
208