Please use GitHub pull requests for new patches. Avoid migrating existing patches. Phabricator shutdown timeline
Changeset View
Standalone View
lld/docs/WebAssembly.rst
| Show First 20 Lines • Show All 69 Lines • ▼ Show 20 Lines | .. option:: --compress-relocations | ||||
| compatible with outputting debug information. | compatible with outputting debug information. | ||||
| .. option:: --allow-undefined | .. option:: --allow-undefined | ||||
| Allow undefined symbols in linked binary. This is the legacy | Allow undefined symbols in linked binary. This is the legacy | ||||
| flag which corresponds to ``--unresolve-symbols=ignore`` + | flag which corresponds to ``--unresolve-symbols=ignore`` + | ||||
| ``--import-undefined``. | ``--import-undefined``. | ||||
| .. option:: --allow-undefined-file=<filename> | |||||
dschuff: Can this be split out from the stub support? or is it tightly coupled somehow? | |||||
I just noticed it was missing from the docs. Want me to split it out? sbc100: I just noticed it was missing from the docs. Want me to split it out? | |||||
| Like ``--allow-undefined``, but the filename specified a flat list of | |||||
| symbols, one per line, which are allowed to be undefined. | |||||
typo: s/care/are/ pmatos: typo: s/care/are/ | |||||
| .. option:: --unresolved-symbols=<method> | .. option:: --unresolved-symbols=<method> | ||||
| This is a more full featured version of ``--allow-undefined``. | This is a more full featured version of ``--allow-undefined``. | ||||
| The semanatics of the different methods are as follows: | The semanatics of the different methods are as follows: | ||||
| report-all: | report-all: | ||||
| Report all unresolved symbols. This is the default. Normally the linker | Report all unresolved symbols. This is the default. Normally the linker | ||||
| ▲ Show 20 Lines • Show All 91 Lines • ▼ Show 20 Lines | |||||
| ``visibility=default``. | ``visibility=default``. | ||||
| Imports | Imports | ||||
| ~~~~~~~ | ~~~~~~~ | ||||
| By default no undefined symbols are allowed in the final binary. The flag | By default no undefined symbols are allowed in the final binary. The flag | ||||
| ``--allow-undefined`` results in a WebAssembly import being defined for each | ``--allow-undefined`` results in a WebAssembly import being defined for each | ||||
| undefined symbol. It is then up to the runtime to provide such symbols. | undefined symbol. It is then up to the runtime to provide such symbols. | ||||
| ``--allow-undefined-file`` is the same but allows a list of symbols to be | |||||
| specified. | |||||
| Alternatively symbols can be marked in the source code as with the | Alternatively symbols can be marked in the source code as with the | ||||
| ``import_name`` and/or ``import_module`` clang attributes which signals that | ``import_name`` and/or ``import_module`` clang attributes which signals that | ||||
| they are expected to be undefined at static link time. | they are expected to be undefined at static link time. | ||||
| Stub Libraries | |||||
| ~~~~~~~~~~~~~~ | |||||
| Another way to specify imports and exports is via a "stub library". This | |||||
| feature is inspired by the ELF stub objects which are supported by the Solaris | |||||
typo: s/This features/This feature/ pmatos: typo: s/This features/This feature/ | |||||
| linker. Stub libraries are text files that can be passed as normal linker | |||||
| inputs, similar to how linker scripts can be passed to the ELF linker. The stub | |||||
| library is a stand-in for a set of symbols that will be available at runtime, | |||||
| but doesn't contain any actual code or data. Instead it contains just a list of | |||||
| symbols, one per line. Each symbol can specify zero or more dependencies. | |||||
| These dependencies are symbols that must be defined, and exported, by the output | |||||
| module if the symbol is question is imported/required by the output module. | |||||
| For example, imagine the runtime provides an external symbol ``foo`` that | |||||
| depends on the ``malloc`` and ``free``. This can be expressed simply as:: | |||||
| #STUB | |||||
| foo: malloc,free | |||||
| Here we are saying that ``foo`` is allowed to be imported (undefined) but that | |||||
| if it is imported, then the output module must also export ``malloc`` and | |||||
Not Done ReplyInline ActionsCan you clarify this a little? which module must export malloc and free? The module that imports foo? Any module loaded before foo is loaded at runtime? Why do we need to have this per-symbol dependence rather than just having a list of symbols that the dylib imports and exports? Is our linking model actually that granular at runtime? dschuff: Can you clarify this a little? which module must export malloc and free? The module that… | |||||
Yes it needs to be on a per-symbol basis. For example, imagine I just use one symbol from libemscripten.stub.so... and that symbol has no dependencies. But there are 1000 other symbols in there with various dependencies, including malloc and free. If we just did this on a per-shared-object bases any program that uses any symbol from libemscripten.stub.so would be forced to define and export the superset of all possible dependencies. In that case of my tiny program I don't want to be forces to export anything, just to use emscripten_get_now, for example. sbc100: Yes it needs to be on a per-symbol basis. For example, imagine I just use one symbol from… | |||||
I tried to clarify a little. I use the term "output module" to refer to the module being linked. Perhaps you can think of a more clear way to express that? sbc100: I tried to clarify a little. I use the term "output module" to refer to the module being… | |||||
Not Done ReplyInline ActionsBut isn't it the case that a stub library represents a real DSO that will be loaded at runtime? (I think that's the case with ELF stubs). In which case the real DSO has whatever symbols and dependencies it has. I guess the answer is actually "no", we are depending on the behavior that libemscripten isn't really a DSO, but it acts more like an archive with one function per member, i.e. each function will only be linked if it is needed. I think in that sense, this isn't really a "stub object" at all, and has kind of weird linking behavior. Is there any way we can improve this, to make stub objects behave more like regular objects or DSOs? I don't think we want to create a stub object for every JS function, that would get unwieldy very fast. Maybe a "stub archive" that can define multiple objects (and we'd just have one such object for every JS function). dschuff: But isn't it the case that a stub library represents a real DSO that will be loaded at runtime? | |||||
Yes, I agree. What we really want here is something closer the behaviour of the library. So we should call this "Stub library" or "Stub archive" I guess. SGTM I think this functionality will be useful to anyone wanting to express external runtime imports that come with required exports (malloc and free being the canonical such requirements). sbc100: Yes, I agree. What we really want here is something closer the behaviour of the library. So… | |||||
| ``free`` to the runtime. If ``foo`` is imported (undefined), but the output | |||||
| module does not define ``malloc`` and ``free`` then the link will fail. | |||||
| Stub libraries must begin with ``#STUB`` on a line by itself. | |||||
| Garbage Collection | Garbage Collection | ||||
| ~~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~ | ||||
| Since WebAssembly is designed with size in mind the linker defaults to | Since WebAssembly is designed with size in mind the linker defaults to | ||||
| ``--gc-sections`` which means that all unused functions and data segments will | ``--gc-sections`` which means that all unused functions and data segments will | ||||
| be stripped from the binary. | be stripped from the binary. | ||||
| The symbols which are preserved by default are: | The symbols which are preserved by default are: | ||||
| Show All 28 Lines | |||||
Can this be split out from the stub support? or is it tightly coupled somehow?