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.. option:: --export-dynamic 43 44 When building an executable, export any non-hidden symbols. By default only 45 the entry point and any symbols marked as exports (either via the command line 46 or via the `export-name` source attribute) are exported. 47 48.. option:: --global-base=<value> 49 50 Address at which to place global data. 51 52.. option:: --no-merge-data-segments 53 54 Disable merging of data segments. 55 56.. option:: --stack-first 57 58 Place stack at start of linear memory rather than after data. 59 60.. option:: --compress-relocations 61 62 Relocation targets in the code section are 5-bytes wide in order to 63 potentially accommodate the largest LEB128 value. This option will cause the 64 linker to shrink the code section to remove any padding from the final 65 output. However because it affects code offset, this option is not 66 compatible with outputting debug information. 67 68.. option:: --allow-undefined 69 70 Allow undefined symbols in linked binary. 71 72.. option:: --import-memory 73 74 Import memory from the environment. 75 76.. option:: --initial-memory=<value> 77 78 Initial size of the linear memory. Default: static data size. 79 80.. option:: --max-memory=<value> 81 82 Maximum size of the linear memory. Default: unlimited. 83 84By default the function table is neither imported nor exported, but defined 85for internal use only. 86 87Behaviour 88--------- 89 90In general, where possible, the WebAssembly linker attempts to emulate the 91behaviour of a traditional ELF linker, and in particular the ELF port of lld. 92For more specific details on how this is achieved see the tool conventions on 93linking_. 94 95Function Signatures 96~~~~~~~~~~~~~~~~~~~ 97 98One way in which the WebAssembly linker differs from traditional native linkers 99is that function signature checking is strict in WebAssembly. It is a 100validation error for a module to contain a call site that doesn't agree with 101the target signature. Even though this is undefined behaviour in C/C++, it is not 102uncommon to find this in real-world C/C++ programs. For example, a call site in 103one compilation unit which calls a function defined in another compilation 104unit but with too many arguments. 105 106In order not to generate such invalid modules, lld has two modes of handling such 107mismatches: it can simply error-out or it can create stub functions that will 108trap at runtime (functions that contain only an ``unreachable`` instruction) 109and use these stub functions at the otherwise invalid call sites. 110 111The default behaviour is to generate these stub function and to produce 112a warning. The ``--fatal-warnings`` flag can be used to disable this behaviour 113and error out if mismatched are found. 114 115Exports 116~~~~~~~ 117 118When building a shared library any symbols marked as ``visibility=default`` will 119be exported. 120 121When building an executable, only the entry point (``_start``) and symbols with 122the ``WASM_SYMBOL_EXPORTED`` flag are exported by default. In LLVM the 123``WASM_SYMBOL_EXPORTED`` flag is set by the ``wasm-export-name`` attribute which 124in turn can be set using ``__attribute__((export_name))`` clang attribute. 125 126In addition, symbols can be exported via the linker command line using 127``--export``. 128 129Finally, just like with native ELF linker the ``--export-dynamic`` flag can be 130used to export symbols in the executable which are marked as 131``visibility=default``. 132 133Imports 134~~~~~~~ 135 136By default no undefined symbols are allowed in the final binary. The flag 137``--allow-undefined`` results in a WebAssembly import being defined for each 138undefined symbol. It is then up to the runtime to provide such symbols. 139 140Alternatively symbols can be marked in the source code as with the 141``import_name`` and/or ``import_module`` clang attributes which signals that 142they are expected to be undefined at static link time. 143 144Garbage Collection 145~~~~~~~~~~~~~~~~~~ 146 147Since WebAssembly is designed with size in mind the linker defaults to 148``--gc-sections`` which means that all unused functions and data segments will 149be stripped from the binary. 150 151The symbols which are preserved by default are: 152 153- The entry point (by default ``_start``). 154- Any symbol which is to be exported. 155- Any symbol transitively referenced by the above. 156 157Weak Undefined Functions 158~~~~~~~~~~~~~~~~~~~~~~~~ 159 160On native platforms, calls to weak undefined functions end up as calls to the 161null function pointer. With WebAssembly, direct calls must reference a defined 162function (with the correct signature). In order to handle this case the linker 163will generate function a stub containing only the ``unreachable`` instruction 164and use this for any direct references to an undefined weak function. 165 166For example a runtime call to a weak undefined function ``foo`` will up trapping 167on ``unreachable`` inside and linker-generated function called 168``undefined:foo``. 169 170Missing features 171---------------- 172 173- Merging of data section similar to ``SHF_MERGE`` in the ELF world is not 174 supported. 175- No support for creating shared libraries. The spec for shared libraries in 176 WebAssembly is still in flux: 177 https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md 178 179.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md 180