1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
| WebAssembly lld port
====================
The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
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 the command line flags and the semantics should be the same.
Object file format
------------------
The WebAssembly object file format used by LLVM and LLD is specified as part of
the WebAssembly tool conventions on linking_.
This is the object format that the llvm will produce when run with the
``wasm32-unknown-unknown`` target.
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.
Behaviour
---------
In general, where possible, the WebAssembly linker attempts to emulate the
behaviour of a traditional ELF linker, and in particular the ELF port of lld.
For more specific details on how this is achieved see the tool conventions on
linking_.
Function Signatures
~~~~~~~~~~~~~~~~~~~
One way in which the WebAssembly linker differs from traditional native linkers
is that function signature checking is strict in WebAssembly. It is a
validation error for a module to contain a call site that doesn't agree with
the target signature. Even though this is undefined behaviour in C/C++, it is not
uncommon to find this in real-world C/C++ programs. For example, a call site in
one compilation unit which calls a function defined in another compilation
unit but with too many arguments.
In order not to generate such invalid modules, lld has two modes of handling such
mismatches: it can simply error-out or it can create stub functions that will
trap at runtime (functions that contain only an ``unreachable`` instruction)
and use these stub functions at the otherwise invalid call sites.
The default behaviour is to generate these stub function and to produce
a warning. The ``--fatal-warnings`` flag can be used to disable this behaviour
and error out if mismatched are found.
Imports and Exports
~~~~~~~~~~~~~~~~~~~
When building a shared library any symbols marked as ``visibility=default`` will
be exported. When building an executable, only the entry point and symbols
flagged as ``WASM_SYMBOL_EXPORTED`` are exported by default. In LLVM the
``WASM_SYMBOL_EXPORTED`` flag is applied to any symbol in the ``llvm.used`` list
which corresponds to ``__attribute__((used))`` in C/C++ sources.
In addition, symbols can be exported via the linker command line using
``--export``.
Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
used to export symbol in the executable which are marked as
``visibility=default``.
Garbage Collection
~~~~~~~~~~~~~~~~~~
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.
Weak Undefined Functions
~~~~~~~~~~~~~~~~~~~~~~~~
On native platforms, calls to weak undefined functions end up as calls to the
null function pointer. With WebAssembly, direct calls must reference a defined
function (with the correct signature). In order to handle this case the linker
will generate function a stub containing only the ``unreachable`` instruction
and use this for any direct references to an undefined weak function.
For example a runtime call to a weak undefined function ``foo`` will up trapping
on ``unreachable`` inside and linker-generated function called
``undefined:foo``.
Missing features
----------------
- 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
.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md
|