Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/reference/cli.md

raw
1 # The `wasm-bindgen` Command Line Interface
2
3 The `wasm-bindgen` command line tool has a number of options available to it to
4 tweak the JavaScript that is generated. The most up-to-date set of flags can
5 always be listed via `wasm-bindgen --help`.
6
7 ## Installation
8
9 ```
10 cargo install -f wasm-bindgen-cli
11 ```
12
13 ## Usage
14
15 ```
16 wasm-bindgen [options] ./target/wasm32-unknown-unknown/release/crate.wasm
17 ```
18
19 ## Options
20
21 ### `--out-dir DIR`
22
23 The target directory to emit the JavaScript bindings, TypeScript definitions,
24 processed `.wasm` binary, etc...
25
26 ### `--target`
27
28 This flag indicates what flavor of output what `wasm-bindgen` should generate.
29 For example it could generate code to be loaded in a bundler like Webpack, a
30 native web page, or Node.js. For a full list of options to pass this flag, see
31 the section on [deployment]
32
33 [deployment]: deployment.html
34
35 ### `--no-modules-global VAR`
36
37 When `--target no-modules` is used this flag can indicate what the name of the
38 global to assign generated bindings to.
39
40 For more information about this see the section on [deployment]
41
42 ### `--typescript`
43
44 Output a TypeScript declaration file for the generated JavaScript bindings. This
45 is on by default.
46
47 ### `--no-typescript`
48
49 By default, a `*.d.ts` TypeScript declaration file is generated for the
50 generated JavaScript bindings, but this flag will disable that.
51
52 ### `--omit-imports`
53
54 When the `module` attribute is used with the `wasm-bindgen` macro, the code
55 generator will emit corresponding `import` or `require` statements in the header
56 section of the generated javascript. This flag causes those import statements to
57 be omitted. This is necessary for some use cases, such as generating javascript
58 which is intended to be used with Electron (with node integration disabled),
59 where the imports are instead handled through a separate preload script.
60
61 ### `--debug`
62
63 Generates a bit more JS and wasm in "debug mode" to help catch programmer
64 errors, but this output isn't intended to be shipped to production.
65
66 ### `--no-demangle`
67
68 When post-processing the `.wasm` binary, do not demangle Rust symbols in the
69 "names" custom section.
70
71 ### `--keep-lld-exports`
72
73 When post-processing the `.wasm` binary, do not remove exports that are
74 synthesized by Rust's linker, LLD.
75
76 ### `--keep-debug`
77
78 When post-processing the `.wasm` binary, do not strip DWARF debug info custom
79 sections.
80
81 ### `--browser`
82
83 When generating bundler-compatible code (see the section on [deployment]) this
84 indicates that the bundled code is always intended to go into a browser so a few
85 checks for Node.js can be elided.
86
87 ### `--reference-types`
88
89 Enables usage of the [WebAssembly References Types
90 proposal](https://github.com/webassembly/reference-types) proposal, meaning that
91 the WebAssembly binary will use `externref` when importing and exporting
92 functions that work with `JsValue`. For more information see the [documentation
93 about reference types](./reference-types.md).
94
95 ### `--omit-default-module-path`
96
97 Don't add WebAssembly fallback imports in generated JavaScript.
98
99 ### `--split-linked-modules`
100
101 Controls whether wasm-bindgen will split linked modules out into their own
102 files. Enabling this is recommended, because it allows lazy-loading the linked
103 modules and setting a stricter Content Security Policy.
104
105 wasm-bindgen uses the `new URL('…', import.meta.url)` syntax to resolve the
106 links to such split out files. This breaks with most bundlers, since the bundler
107 doesn't know to include the linked module in its output. That's why this option
108 is disabled by default. Webpack 5 is an exception, which has special treatment
109 for that syntax.
110
111 For other bundlers, you'll need to take extra steps to get it to work, likely by
112 using a plugin. Alternatively, you can leave the syntax as is and instead
113 manually configure the bundler to copy all files in `snippets/` to the output
114 directory, preserving their paths relative to whichever bundled file ends up
115 containing the JS shim.
116
117 On the no-modules target, `link_to!` won't work if used outside of a document,
118 e.g. inside a worker. This is because it's impossible to figure out what the
119 URL of the linked module is without a reference point like `import.meta.url`.