From bd37e09355ecbf2c90cb903f2507504d1e942642 Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Thu, 27 Sep 2018 00:42:49 +0000 Subject: [PATCH] Revert "[WebAssembly] Update docs" This change reverts rL343155. It broke the builtbot, even though it works for me locally: http://lab.llvm.org:8011/builders/lld-sphinx-docs/builds/26336 Must be a sphinx version issue I guess. llvm-svn: 343156 --- lld/docs/README.txt | 5 ++- lld/docs/WebAssembly.rst | 97 +++++++----------------------------------------- 2 files changed, 18 insertions(+), 84 deletions(-) diff --git a/lld/docs/README.txt b/lld/docs/README.txt index 2ed0166..eb09a2d 100644 --- a/lld/docs/README.txt +++ b/lld/docs/README.txt @@ -6,4 +6,7 @@ currently tested with Sphinx 1.1.3. We currently use the 'nature' theme and a Beaker inspired structure. -See sphinx_intro.rst for more details. +To rebuild documents into html: + + [/lld/docs]> make html + diff --git a/lld/docs/WebAssembly.rst b/lld/docs/WebAssembly.rst index 4485e50..264d221 100644 --- a/lld/docs/WebAssembly.rst +++ b/lld/docs/WebAssembly.rst @@ -1,10 +1,13 @@ 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 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. +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. Object file format @@ -20,86 +23,14 @@ currently requires enabling the experimental backed using ``-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:: --[no-]export-default - - Export symbols marked as 'default' visibility. Default: true - -.. option:: --global-base= - - Address at which to place global data - -.. option:: --[no-]merge-data-segments - - Enable/Disble merging of data segments. Default: true - -.. option:: --stack-first - - Place stack at start of linear memory rather than after data - -.. option:: --compress-relocations - - Compress the relocation targets in the code section. - -.. 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. - -Symbols are exported if they are marked as ``visibility=default`` at compile -time or if they are included on the command line via ``--export``. - -Since WebAssembly is designed with size in mind the linker defaults to -``--gc-sections`` which means that all un-used 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 ---------------- -- Merging of data section similiar to ``SHF_MERGE`` in the ELF world is not - supported. -- No support for creating shared libaries. The spec for shared libraries in - WebAssembly is still in flux: - https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md +There are several key features that are not yet implement in the WebAssembly +ports: + +- 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. -- 2.7.4