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 that command line flags and the semantics should be the same.
8
9
10Object file format
11------------------
12
13The format the input object files that lld expects is specified as part of the
14the WebAssembly tool conventions
15https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md.
16
17This is object format that the llvm will produce when run with the
18``wasm32-unknown-unknown`` target.  To build llvm with WebAssembly support
19currently requires enabling the experimental backed using
20``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
21
22
23Usage
24-----
25
26The WebAssembly version of lld is installed as **wasm-ld**.  It shared many
27common linker flags with **ld.lld** but also includes several
28WebAssembly-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
88By default the function table is neither imported nor exported, but defined
89for internal use only.
90
91When building shared libraries symbols are exported if they are marked
92as ``visibility=default``.  When building executables only the entry point is
93exported by default.  In addition any symbol included on the command line via
94``--export`` is also exported.
95
96Since WebAssembly is designed with size in mind the linker defaults to
97``--gc-sections`` which means that all unused functions and data segments will
98be stripped from the binary.
99
100The 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
107Missing 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
115