Index: docs/README.txt =================================================================== --- docs/README.txt +++ docs/README.txt @@ -6,7 +6,4 @@ We currently use the 'nature' theme and a Beaker inspired structure. -To rebuild documents into html: - - [/lld/docs]> make html - +See sphinx_intro.rst for more details. Index: docs/WebAssembly.rst =================================================================== --- docs/WebAssembly.rst +++ docs/WebAssembly.rst @@ -1,13 +1,10 @@ WebAssembly lld port ==================== -Note: The WebAssembly port is still a work in progress and is be lacking -certain features. - The WebAssembly version of lld takes WebAssembly binaries as inputs and produces -a WebAssembly binary as its output. For the most part this port tried to mimic -the behaviour of traditional ELF linkers and specifically the ELF lld port. -Where possible that command line flags and the semantics should be the same. +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 that command line flags and the semantics should be the same. Object file format @@ -23,16 +20,95 @@ ``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``. +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= + + Address at which to place global data. + +.. option:: --no-merge-data-segments + + Disble 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= + + Initial size of the linear memory. Default: static data size. + +.. option:: --max-memory= + + Maximum size of the linear memory. Default: unlimited. + +By default the function table is neither imported nor exported, but defined +for internal use only. + +When building shared libraries symbols are exported if they are marked +as ``visibility=default``. When building executables only the entry point is +exported by default. In addition any symbol included on the command line via +``--export`` is also exported. + +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. + + Missing features ---------------- -There are several key features that are not yet implement in the WebAssembly -ports: - -- Support for building shared libraries via ``-shared`` is still as work in - progress. -- COMDAT support. This means that support for C++ is still very limited. -- Function stripping. Currently there is no support for ``--gc-sections`` so - functions and data from a given object will linked as a unit. -- Section start/end symbols. The synthetic symbols that mark the start and - of data regions are not yet created in the output file. +- 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