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`` (which will error if the symbol is not found) or 156``--export-if-defined`` (which will not). 157 158Finally, just like with native ELF linker the ``--export-dynamic`` flag can be 159used to export symbols in the executable which are marked as 160``visibility=default``. 161 162Imports 163~~~~~~~ 164 165By default no undefined symbols are allowed in the final binary. The flag 166``--allow-undefined`` results in a WebAssembly import being defined for each 167undefined symbol. It is then up to the runtime to provide such symbols. 168 169Alternatively symbols can be marked in the source code as with the 170``import_name`` and/or ``import_module`` clang attributes which signals that 171they are expected to be undefined at static link time. 172 173Garbage Collection 174~~~~~~~~~~~~~~~~~~ 175 176Since WebAssembly is designed with size in mind the linker defaults to 177``--gc-sections`` which means that all unused functions and data segments will 178be stripped from the binary. 179 180The symbols which are preserved by default are: 181 182- The entry point (by default ``_start``). 183- Any symbol which is to be exported. 184- Any symbol transitively referenced by the above. 185 186Weak Undefined Functions 187~~~~~~~~~~~~~~~~~~~~~~~~ 188 189On native platforms, calls to weak undefined functions end up as calls to the 190null function pointer. With WebAssembly, direct calls must reference a defined 191function (with the correct signature). In order to handle this case the linker 192will generate function a stub containing only the ``unreachable`` instruction 193and use this for any direct references to an undefined weak function. 194 195For example a runtime call to a weak undefined function ``foo`` will up trapping 196on ``unreachable`` inside and linker-generated function called 197``undefined:foo``. 198 199Missing features 200---------------- 201 202- Merging of data section similar to ``SHF_MERGE`` in the ELF world is not 203 supported. 204- No support for creating shared libraries. The spec for shared libraries in 205 WebAssembly is still in flux: 206 https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md 207 208.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md 209