Skip to content

Commit 7c3a469

Browse files
authored
[Docs] Add docs for wasm-merge export handling flags (#5725)
1 parent 9b34b96 commit 7c3a469

File tree

1 file changed

+32
-0
lines changed

1 file changed

+32
-0
lines changed

README.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -574,6 +574,11 @@ file the calls between the modules become just normal calls inside a module,
574574
which allows them to be inlined, dead code eliminated, and so forth, potentially
575575
improving speed and size.
576576

577+
`wasm-merge` operates on normal wasm files. It differs from `wasm-ld` in that
578+
respect, as `wasm-ld` operates on wasm *object* files. `wasm-merge` can help
579+
in multi-toolchain situations where at least one of the toolchains does not use
580+
wasm object files.
581+
577582
For example, imagine we have these two wasm files:
578583

579584
```wat
@@ -709,6 +714,33 @@ merged.exports.main();
709714
We still need to fetch and compile the merged wasm, and to provide it the JS
710715
import, but the work to connect two wasm modules is not needed any more.
711716

717+
#### Handling exports
718+
719+
By default `wasm-merge` errors if there are overlapping export names. That is,
720+
`wasm-merge` will automatically handle overlapping function names and so forth,
721+
because those are not externally visible (the code still behaves the same), but
722+
if we renamed exports then the outside would need to be modified to expect the
723+
new export names, and so we error instead on such name conflicts.
724+
725+
If you do want exports to be renamed, run `wasm-merge` with
726+
`--rename-export-conflicts`. Later exports will have a suffix appended to them
727+
to ensure they do not overlap with previous exports. The suffixes are
728+
deterministic, so once you see what they are you can call them from the outside.
729+
730+
Another option is to use `--skip-export-conflicts` which will simply skip later
731+
exports that have conflicting names. For example, this can be useful in the
732+
case where the first module is the only one that interacts with the outside and
733+
the later modules just interact with the first module.
734+
735+
#### Features
736+
737+
`wasm-merge` uses the multi-memory and multi-table features. That is, if
738+
multiple input modules each have a memory then the output wasm will have several
739+
memories, and will depend on the multi-memory feature, which means that older
740+
wasm VMs might not be able to run the wasm. (As a workaround for such older VMs
741+
you can run `wasm-opt --multi-memory-lowering` to lower multiple memories into a
742+
single one.)
743+
712744
## Testing
713745

714746
```

0 commit comments

Comments
 (0)