更新libclamav库1.0.0版本
This commit is contained in:
1
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/.cargo-checksum.json
vendored
Normal file
1
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/.cargo-checksum.json
vendored
Normal file
File diff suppressed because one or more lines are too long
1862
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/CHANGELOG.md
vendored
Normal file
1862
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/CHANGELOG.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
4
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/CONTRIBUTING.md
vendored
Normal file
4
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/CONTRIBUTING.md
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
# Contributing
|
||||
|
||||
See the ["Contributing" section of the `wasm-bindgen`
|
||||
guide](https://rustwasm.github.io/docs/wasm-bindgen/contributing/index.html).
|
||||
79
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/Cargo.toml
vendored
Normal file
79
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/Cargo.toml
vendored
Normal file
@@ -0,0 +1,79 @@
|
||||
# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
|
||||
#
|
||||
# When uploading crates to the registry Cargo will automatically
|
||||
# "normalize" Cargo.toml files for maximal compatibility
|
||||
# with all versions of Cargo and also rewrite `path` dependencies
|
||||
# to registry (e.g., crates.io) dependencies.
|
||||
#
|
||||
# If you are reading this file be aware that the original Cargo.toml
|
||||
# will likely look very different (and much more reasonable).
|
||||
# See Cargo.toml.orig for the original contents.
|
||||
|
||||
[package]
|
||||
edition = "2018"
|
||||
name = "wasm-bindgen"
|
||||
version = "0.2.83"
|
||||
authors = ["The wasm-bindgen Developers"]
|
||||
description = """
|
||||
Easy support for interacting between JS and Rust.
|
||||
"""
|
||||
homepage = "https://rustwasm.github.io/"
|
||||
documentation = "https://docs.rs/wasm-bindgen"
|
||||
readme = "README.md"
|
||||
categories = ["wasm"]
|
||||
license = "MIT/Apache-2.0"
|
||||
repository = "https://github.com/rustwasm/wasm-bindgen"
|
||||
|
||||
[package.metadata.docs.rs]
|
||||
features = ["serde-serialize"]
|
||||
|
||||
[lib]
|
||||
test = false
|
||||
|
||||
[dependencies.cfg-if]
|
||||
version = "1.0.0"
|
||||
|
||||
[dependencies.serde]
|
||||
version = "1.0"
|
||||
optional = true
|
||||
|
||||
[dependencies.serde_json]
|
||||
version = "1.0"
|
||||
optional = true
|
||||
|
||||
[dependencies.wasm-bindgen-macro]
|
||||
version = "=0.2.83"
|
||||
|
||||
[features]
|
||||
default = [
|
||||
"spans",
|
||||
"std",
|
||||
]
|
||||
enable-interning = ["std"]
|
||||
serde-serialize = [
|
||||
"serde",
|
||||
"serde_json",
|
||||
"std",
|
||||
]
|
||||
spans = ["wasm-bindgen-macro/spans"]
|
||||
std = []
|
||||
strict-macro = ["wasm-bindgen-macro/strict-macro"]
|
||||
xxx_debug_only_print_generated_code = ["wasm-bindgen-macro/xxx_debug_only_print_generated_code"]
|
||||
|
||||
[target."cfg(target_arch = \"wasm32\")".dev-dependencies.js-sys]
|
||||
version = "0.3.60"
|
||||
|
||||
[target."cfg(target_arch = \"wasm32\")".dev-dependencies.serde_derive]
|
||||
version = "1.0"
|
||||
|
||||
[target."cfg(target_arch = \"wasm32\")".dev-dependencies.wasm-bindgen-futures]
|
||||
version = "=0.4.33"
|
||||
|
||||
[target."cfg(target_arch = \"wasm32\")".dev-dependencies.wasm-bindgen-test]
|
||||
version = "=0.3.33"
|
||||
|
||||
[target."cfg(target_arch = \"wasm32\")".dev-dependencies.wasm-bindgen-test-crate-a]
|
||||
version = "0.1"
|
||||
|
||||
[target."cfg(target_arch = \"wasm32\")".dev-dependencies.wasm-bindgen-test-crate-b]
|
||||
version = "0.1"
|
||||
201
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/LICENSE-APACHE
vendored
Normal file
201
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/LICENSE-APACHE
vendored
Normal file
@@ -0,0 +1,201 @@
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
25
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/LICENSE-MIT
vendored
Normal file
25
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/LICENSE-MIT
vendored
Normal file
@@ -0,0 +1,25 @@
|
||||
Copyright (c) 2014 Alex Crichton
|
||||
|
||||
Permission is hereby granted, free of charge, to any
|
||||
person obtaining a copy of this software and associated
|
||||
documentation files (the "Software"), to deal in the
|
||||
Software without restriction, including without
|
||||
limitation the rights to use, copy, modify, merge,
|
||||
publish, distribute, sublicense, and/or sell copies of
|
||||
the Software, and to permit persons to whom the Software
|
||||
is furnished to do so, subject to the following
|
||||
conditions:
|
||||
|
||||
The above copyright notice and this permission notice
|
||||
shall be included in all copies or substantial portions
|
||||
of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
|
||||
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
|
||||
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
|
||||
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
|
||||
SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
|
||||
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
DEALINGS IN THE SOFTWARE.
|
||||
113
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/README.md
vendored
Normal file
113
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/README.md
vendored
Normal file
@@ -0,0 +1,113 @@
|
||||
<div align="center">
|
||||
|
||||
<h1><code>wasm-bindgen</code></h1>
|
||||
|
||||
<p>
|
||||
<strong>Facilitating high-level interactions between Wasm modules and JavaScript.</strong>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<a href="https://dev.azure.com/rustwasm/wasm-bindgen/_build/latest?definitionId=1&branchName=master"><img src="https://img.shields.io/azure-devops/build/rustwasm/wasm-bindgen/1.svg?style=flat-square" alt="Build Status" /></a>
|
||||
<a href="https://crates.io/crates/wasm-bindgen"><img src="https://img.shields.io/crates/v/wasm-bindgen.svg?style=flat-square" alt="Crates.io version" /></a>
|
||||
<a href="https://crates.io/crates/wasm-bindgen"><img src="https://img.shields.io/crates/d/wasm-bindgen.svg?style=flat-square" alt="Download" /></a>
|
||||
<a href="https://docs.rs/wasm-bindgen"><img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /></a>
|
||||
</p>
|
||||
|
||||
<h3>
|
||||
<a href="https://rustwasm.github.io/docs/wasm-bindgen/">Guide</a>
|
||||
<span> | </span>
|
||||
<a href="https://docs.rs/wasm-bindgen">API Docs</a>
|
||||
<span> | </span>
|
||||
<a href="https://github.com/rustwasm/wasm-bindgen/blob/master/CONTRIBUTING.md">Contributing</a>
|
||||
<span> | </span>
|
||||
<a href="https://discord.gg/xMZ7CCY">Chat</a>
|
||||
</h3>
|
||||
|
||||
<sub>Built with 🦀🕸 by <a href="https://rustwasm.github.io/">The Rust and WebAssembly Working Group</a></sub>
|
||||
</div>
|
||||
|
||||
## Example
|
||||
|
||||
Import JavaScript things into Rust and export Rust things to JavaScript.
|
||||
|
||||
```rust
|
||||
use wasm_bindgen::prelude::*;
|
||||
|
||||
// Import the `window.alert` function from the Web.
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
fn alert(s: &str);
|
||||
}
|
||||
|
||||
// Export a `greet` function from Rust to JavaScript, that alerts a
|
||||
// hello message.
|
||||
#[wasm_bindgen]
|
||||
pub fn greet(name: &str) {
|
||||
alert(&format!("Hello, {}!", name));
|
||||
}
|
||||
```
|
||||
|
||||
Use exported Rust things from JavaScript with ECMAScript modules!
|
||||
|
||||
```js
|
||||
import { greet } from "./hello_world";
|
||||
|
||||
greet("World!");
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
* **Lightweight.** Only pay for what you use. `wasm-bindgen` only generates
|
||||
bindings and glue for the JavaScript imports you actually use and Rust
|
||||
functionality that you export. For example, importing and using the
|
||||
`document.querySelector` method doesn't cause `Node.prototype.appendChild` or
|
||||
`window.alert` to be included in the bindings as well.
|
||||
|
||||
* **ECMAScript modules.** Just import WebAssembly modules the same way you would
|
||||
import JavaScript modules. Future compatible with [WebAssembly modules and
|
||||
ECMAScript modules integration][wasm-es-modules].
|
||||
|
||||
* **Designed with the ["Web IDL bindings" proposal][webidl-bindings] in mind.**
|
||||
Eventually, there won't be any JavaScript shims between Rust-generated wasm
|
||||
functions and native DOM methods. Because the wasm functions are statically
|
||||
type checked, some of those native methods' dynamic type checks should become
|
||||
unnecessary, promising to unlock even-faster-than-JavaScript DOM access.
|
||||
|
||||
[wasm-es-modules]: https://github.com/WebAssembly/esm-integration
|
||||
[webidl-bindings]: https://github.com/WebAssembly/proposals/issues/8
|
||||
|
||||
## Guide
|
||||
|
||||
[**📚 Read the `wasm-bindgen` guide here! 📚**](https://rustwasm.github.io/docs/wasm-bindgen/)
|
||||
|
||||
You can find general documentation about using Rust and WebAssembly together
|
||||
[here](https://rustwasm.github.io/docs).
|
||||
|
||||
## API Docs
|
||||
|
||||
- [wasm-bindgen](https://docs.rs/wasm-bindgen)
|
||||
- [js-sys](https://docs.rs/js-sys)
|
||||
- [web-sys](https://docs.rs/web-sys)
|
||||
- [wasm-bindgen-futures](https://docs.rs/wasm-bindgen-futures)
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under either of
|
||||
|
||||
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
|
||||
http://www.apache.org/licenses/LICENSE-2.0)
|
||||
* MIT license ([LICENSE-MIT](LICENSE-MIT) or
|
||||
http://opensource.org/licenses/MIT)
|
||||
|
||||
at your option.
|
||||
|
||||
## Contribution
|
||||
|
||||
**[See the "Contributing" section of the guide for information on
|
||||
hacking on `wasm-bindgen`!][contributing]**
|
||||
|
||||
Unless you explicitly state otherwise, any contribution intentionally submitted
|
||||
for inclusion in this project by you, as defined in the Apache-2.0 license,
|
||||
shall be dual licensed as above, without any additional terms or conditions.
|
||||
|
||||
[contributing]: https://rustwasm.github.io/docs/wasm-bindgen/contributing/index.html
|
||||
14
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/_package.json
vendored
Normal file
14
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/_package.json
vendored
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"scripts": {
|
||||
"build": "webpack",
|
||||
"serve": "webpack serve"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@wasm-tool/wasm-pack-plugin": "1.5.0",
|
||||
"html-webpack-plugin": "^5.3.2",
|
||||
"text-encoding": "^0.7.0",
|
||||
"webpack": "^5.49.0",
|
||||
"webpack-cli": "^4.7.2",
|
||||
"webpack-dev-server": "^3.11.2"
|
||||
}
|
||||
}
|
||||
4
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/build.rs
vendored
Normal file
4
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/build.rs
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
// Empty `build.rs` so that `[package] links = ...` works in `Cargo.toml`.
|
||||
fn main() {
|
||||
println!("cargo:rerun-if-changed=build.rs");
|
||||
}
|
||||
7
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/README.md
vendored
Normal file
7
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/README.md
vendored
Normal file
@@ -0,0 +1,7 @@
|
||||
# Examples
|
||||
|
||||
This directory contains a number of Cargo projects that are all examples of how
|
||||
to use `wasm-bindgen` in various contexts. More documentation can be [found
|
||||
online][dox]
|
||||
|
||||
[dox]: https://rustwasm.github.io/docs/wasm-bindgen/examples/index.html
|
||||
15
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/README.md
vendored
Normal file
15
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/README.md
vendored
Normal file
@@ -0,0 +1,15 @@
|
||||
# Importing non-browser JS
|
||||
|
||||
[View documentation for this example online][dox] or [View compiled example
|
||||
online][compiled]
|
||||
|
||||
[compiled]: https://rustwasm.github.io/wasm-bindgen/exbuild/import_js/
|
||||
[dox]: https://rustwasm.github.io/docs/wasm-bindgen/examples/import-js.html
|
||||
|
||||
You can build the example locally with:
|
||||
|
||||
```
|
||||
$ npm run serve
|
||||
```
|
||||
|
||||
and then visiting http://localhost:8080 in a browser should run the example!
|
||||
8
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/index.html
vendored
Normal file
8
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/index.html
vendored
Normal file
@@ -0,0 +1,8 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta content="text/html;charset=utf-8" http-equiv="Content-Type"/>
|
||||
</head>
|
||||
<body>
|
||||
<p>Open up the developer console and you should see "Hello from Rust!"</p>
|
||||
</body>
|
||||
</html>
|
||||
4
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/index.js
vendored
Normal file
4
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/index.js
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
// For more comments about what's going on here, check out the `hello_world`
|
||||
// example
|
||||
import('./crate/pkg')
|
||||
.catch(console.error);
|
||||
14
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/package.json
vendored
Normal file
14
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/package.json
vendored
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"scripts": {
|
||||
"build": "webpack",
|
||||
"serve" : "webpack serve"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@wasm-tool/wasm-pack-plugin": "1.5.0",
|
||||
"text-encoding": "^0.7.0",
|
||||
"html-webpack-plugin": "^5.3.2",
|
||||
"webpack": "^5.49.0",
|
||||
"webpack-cli": "^4.7.2",
|
||||
"webpack-dev-server": "^3.11.2"
|
||||
}
|
||||
}
|
||||
30
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/webpack.config.js
vendored
Normal file
30
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/examples/import_js/webpack.config.js
vendored
Normal file
@@ -0,0 +1,30 @@
|
||||
const path = require('path');
|
||||
const HtmlWebpackPlugin = require('html-webpack-plugin');
|
||||
const webpack = require('webpack');
|
||||
const WasmPackPlugin = require("@wasm-tool/wasm-pack-plugin");
|
||||
|
||||
module.exports = {
|
||||
entry: './index.js',
|
||||
output: {
|
||||
path: path.resolve(__dirname, 'dist'),
|
||||
filename: 'index.js',
|
||||
},
|
||||
plugins: [
|
||||
new HtmlWebpackPlugin({
|
||||
template: 'index.html'
|
||||
}),
|
||||
new WasmPackPlugin({
|
||||
crateDirectory: path.resolve(__dirname, "crate")
|
||||
}),
|
||||
// Have this example work in Edge which doesn't ship `TextEncoder` or
|
||||
// `TextDecoder` at this time.
|
||||
new webpack.ProvidePlugin({
|
||||
TextDecoder: ['text-encoding', 'TextDecoder'],
|
||||
TextEncoder: ['text-encoding', 'TextEncoder']
|
||||
})
|
||||
],
|
||||
mode: 'development',
|
||||
experiments: {
|
||||
asyncWebAssembly: true
|
||||
}
|
||||
};
|
||||
10
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/book.toml
vendored
Normal file
10
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/book.toml
vendored
Normal file
@@ -0,0 +1,10 @@
|
||||
[book]
|
||||
authors = ["Nick Fitzgerald"]
|
||||
multilingual = false
|
||||
src = "src"
|
||||
title = "The `wasm-bindgen` Guide"
|
||||
|
||||
[build]
|
||||
build-dir = "book/html"
|
||||
|
||||
[output.html]
|
||||
126
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/SUMMARY.md
vendored
Normal file
126
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/SUMMARY.md
vendored
Normal file
@@ -0,0 +1,126 @@
|
||||
# Summary
|
||||
|
||||
[Introduction](./introduction.md)
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
- [Examples](./examples/index.md)
|
||||
- [Hello, World!](./examples/hello-world.md)
|
||||
- [Using `console.log`](./examples/console-log.md)
|
||||
- [Small wasm files](./examples/add.md)
|
||||
- [Without a Bundler](./examples/without-a-bundler.md)
|
||||
- [Converting WebAssembly to JS](./examples/wasm2js.md)
|
||||
- [Importing functions from JS](./examples/import-js.md)
|
||||
- [Working with `char`](./examples/char.md)
|
||||
- [js-sys: WebAssembly in WebAssembly](./examples/wasm-in-wasm.md)
|
||||
- [web-sys: DOM hello world](./examples/dom.md)
|
||||
- [web-sys: Closures](./examples/closures.md)
|
||||
- [web-sys: `performance.now`](./examples/performance.md)
|
||||
- [web-sys: using `fetch`](./examples/fetch.md)
|
||||
- [web-sys: `canvas` hello world](./examples/2d-canvas.md)
|
||||
- [web-sys: `canvas` Julia set](./examples/julia.md)
|
||||
- [web-sys: WebAudio](./examples/web-audio.md)
|
||||
- [web-sys: WebGL](./examples/webgl.md)
|
||||
- [web-sys: WebSockets](./examples/websockets.md)
|
||||
- [web-sys: WebRTC DataChannel](./examples/webrtc_datachannel.md)
|
||||
- [web-sys: `requestAnimationFrame`](./examples/request-animation-frame.md)
|
||||
- [web-sys: A Simple Paint Program](./examples/paint.md)
|
||||
- [web-sys: WASM in Web Worker](./examples/wasm-in-web-worker.md)
|
||||
- [Parallel Raytracing](./examples/raytrace.md)
|
||||
- [WASM Audio Worklet](./examples/wasm-audio-worklet.md)
|
||||
- [web-sys: A TODO MVC App](./examples/todomvc.md)
|
||||
- [Reference](./reference/index.md)
|
||||
- [Deployment](./reference/deployment.md)
|
||||
- [JS snippets](./reference/js-snippets.md)
|
||||
- [Passing Rust Closures to JS](./reference/passing-rust-closures-to-js.md)
|
||||
- [Receiving JS Closures in Rust](./reference/receiving-js-closures-in-rust.md)
|
||||
- [`Promise`s and `Future`s](./reference/js-promises-and-rust-futures.md)
|
||||
- [Iterating over JS Values](./reference/iterating-over-js-values.md)
|
||||
- [Arbitrary Data with Serde](./reference/arbitrary-data-with-serde.md)
|
||||
- [Accessing Properties of Untyped JS Values](./reference/accessing-properties-of-untyped-js-values.md)
|
||||
- [Working with Duck-Typed Interfaces](./reference/working-with-duck-typed-interfaces.md)
|
||||
- [Command Line Interface](./reference/cli.md)
|
||||
- [Optimizing for Size](./reference/optimize-size.md)
|
||||
- [Supported Rust Targets](./reference/rust-targets.md)
|
||||
- [Supported Browsers](./reference/browser-support.md)
|
||||
- [Support for Weak References](./reference/weak-references.md)
|
||||
- [Support for Reference Types](./reference/reference-types.md)
|
||||
- [Supported Types](./reference/types.md)
|
||||
- [Imported JavaScript Types](./reference/types/imported-js-types.md)
|
||||
- [Exported Rust Types](./reference/types/exported-rust-types.md)
|
||||
- [`JsValue`](./reference/types/jsvalue.md)
|
||||
- [`Box<[JsValue]>`](./reference/types/boxed-jsvalue-slice.md)
|
||||
- [`*const T` and `*mut T`](./reference/types/pointers.md)
|
||||
- [Numbers](./reference/types/numbers.md)
|
||||
- [`bool`](./reference/types/bool.md)
|
||||
- [`char`](./reference/types/char.md)
|
||||
- [`str`](./reference/types/str.md)
|
||||
- [`String`](./reference/types/string.md)
|
||||
- [Number Slices](./reference/types/number-slices.md)
|
||||
- [Boxed Number Slices](./reference/types/boxed-number-slices.md)
|
||||
- [`Result<T, E>`](./reference/types/result.md)
|
||||
- [`#[wasm_bindgen]` Attributes](./reference/attributes/index.md)
|
||||
- [On JavaScript Imports](./reference/attributes/on-js-imports/index.md)
|
||||
- [`catch`](./reference/attributes/on-js-imports/catch.md)
|
||||
- [`constructor`](./reference/attributes/on-js-imports/constructor.md)
|
||||
- [`extends`](./reference/attributes/on-js-imports/extends.md)
|
||||
- [`getter` and `setter`](./reference/attributes/on-js-imports/getter-and-setter.md)
|
||||
- [`final`](./reference/attributes/on-js-imports/final.md)
|
||||
- [`indexing_getter`, `indexing_setter`, and `indexing_deleter`](./reference/attributes/on-js-imports/indexing-getter-setter-deleter.md)
|
||||
- [`js_class = "Blah"`](./reference/attributes/on-js-imports/js_class.md)
|
||||
- [`js_name`](./reference/attributes/on-js-imports/js_name.md)
|
||||
- [`js_namespace`](./reference/attributes/on-js-imports/js_namespace.md)
|
||||
- [`method`](./reference/attributes/on-js-imports/method.md)
|
||||
- [`module = "blah"`](./reference/attributes/on-js-imports/module.md)
|
||||
- [`raw_module = "blah"`](./reference/attributes/on-js-imports/raw_module.md)
|
||||
- [`static_method_of = Blah`](./reference/attributes/on-js-imports/static_method_of.md)
|
||||
- [`structural`](./reference/attributes/on-js-imports/structural.md)
|
||||
- [`variadic`](./reference/attributes/on-js-imports/variadic.md)
|
||||
- [`vendor_prefix`](./reference/attributes/on-js-imports/vendor_prefix.md)
|
||||
- [On Rust Exports](./reference/attributes/on-rust-exports/index.md)
|
||||
- [`constructor`](./reference/attributes/on-rust-exports/constructor.md)
|
||||
- [`js_name = Blah`](./reference/attributes/on-rust-exports/js_name.md)
|
||||
- [`readonly`](./reference/attributes/on-rust-exports/readonly.md)
|
||||
- [`skip`](./reference/attributes/on-rust-exports/skip.md)
|
||||
- [`start`](./reference/attributes/on-rust-exports/start.md)
|
||||
- [`typescript_custom_section`](./reference/attributes/on-rust-exports/typescript_custom_section.md)
|
||||
- [`getter` and `setter`](./reference/attributes/on-rust-exports/getter-and-setter.md)
|
||||
- [`inspectable`](./reference/attributes/on-rust-exports/inspectable.md)
|
||||
- [`skip_typescript`](./reference/attributes/on-rust-exports/skip_typescript.md)
|
||||
- [`typescript_type`](./reference/attributes/on-rust-exports/typescript_type.md)
|
||||
- [`getter_with_clone`](./reference/attributes/on-rust-exports/getter_with_clone.md)
|
||||
|
||||
- [`web-sys`](./web-sys/index.md)
|
||||
- [Using `web-sys`](./web-sys/using-web-sys.md)
|
||||
- [Cargo Features](./web-sys/cargo-features.md)
|
||||
- [Function Overloads](./web-sys/function-overloads.md)
|
||||
- [Type Translations](./web-sys/type-translations.md)
|
||||
- [Inheritance](./web-sys/inheritance.md)
|
||||
- [Unstable APIs](./web-sys/unstable-apis.md)
|
||||
|
||||
- [Testing with `wasm-bindgen-test`](./wasm-bindgen-test/index.md)
|
||||
- [Usage](./wasm-bindgen-test/usage.md)
|
||||
- [Writing Asynchronous Tests](./wasm-bindgen-test/asynchronous-tests.md)
|
||||
- [Testing in Headless Browsers](./wasm-bindgen-test/browsers.md)
|
||||
- [Continuous Integration](./wasm-bindgen-test/continuous-integration.md)
|
||||
|
||||
- [Contributing to `wasm-bindgen`](./contributing/index.md)
|
||||
- [Testing](./contributing/testing.md)
|
||||
- [Internal Design](./contributing/design/index.md)
|
||||
- [JS Objects in Rust](./contributing/design/js-objects-in-rust.md)
|
||||
- [Exporting a function to JS](./contributing/design/exporting-rust.md)
|
||||
- [Exporting a struct to JS](./contributing/design/exporting-rust-struct.md)
|
||||
- [Importing a function from JS](./contributing/design/importing-js.md)
|
||||
- [Importing a class from JS](./contributing/design/importing-js-struct.md)
|
||||
- [Rust Type conversions](./contributing/design/rust-type-conversions.md)
|
||||
- [Types in `wasm-bindgen`](./contributing/design/describe.md)
|
||||
- [`js-sys`](./contributing/js-sys/index.md)
|
||||
- [Testing](./contributing/js-sys/testing.md)
|
||||
- [Adding More APIs](./contributing/js-sys/adding-more-apis.md)
|
||||
- [`web-sys`](./contributing/web-sys/index.md)
|
||||
- [Overview](./contributing/web-sys/overview.md)
|
||||
- [Testing](./contributing/web-sys/testing.md)
|
||||
- [Logging](./contributing/web-sys/logging.md)
|
||||
- [Supporting More Web APIs](./contributing/web-sys/supporting-more-web-apis.md)
|
||||
- [Publishing](./contributing/publishing.md)
|
||||
- [Team](./contributing/team.md)
|
||||
3
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/_headers
vendored
Normal file
3
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/_headers
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
/*
|
||||
Cross-Origin-Opener-Policy: same-origin
|
||||
Cross-Origin-Embedder-Policy: require-corp
|
||||
57
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/describe.md
vendored
Normal file
57
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/describe.md
vendored
Normal file
@@ -0,0 +1,57 @@
|
||||
# Communicating types to `wasm-bindgen`
|
||||
|
||||
The last aspect to talk about when converting Rust/JS types amongst one another
|
||||
is how this information is actually communicated. The `#[wasm_bindgen]` macro is
|
||||
running over the syntactical (unresolved) structure of the Rust code and is then
|
||||
responsible for generating information that `wasm-bindgen` the CLI tool later
|
||||
reads.
|
||||
|
||||
To accomplish this a slightly unconventional approach is taken. Static
|
||||
information about the structure of the Rust code is serialized via JSON
|
||||
(currently) to a custom section of the wasm executable. Other information, like
|
||||
what the types actually are, unfortunately isn't known until later in the
|
||||
compiler due to things like associated type projections and typedefs. It also
|
||||
turns out that we want to convey "rich" types like `FnMut(String, Foo,
|
||||
&JsValue)` to the `wasm-bindgen` CLI, and handling all this is pretty tricky!
|
||||
|
||||
To solve this issue the `#[wasm_bindgen]` macro generates **executable
|
||||
functions** which "describe the type signature of an import or export". These
|
||||
executable functions are what the `WasmDescribe` trait is all about:
|
||||
|
||||
```rust
|
||||
pub trait WasmDescribe {
|
||||
fn describe();
|
||||
}
|
||||
```
|
||||
|
||||
While deceptively simple this trait is actually quite important. When you write,
|
||||
an export like this:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
fn greet(a: &str) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
In addition to the shims we talked about above which JS generates the macro
|
||||
*also* generates something like:
|
||||
|
||||
```
|
||||
#[no_mangle]
|
||||
pub extern "C" fn __wbindgen_describe_greet() {
|
||||
<dyn Fn(&str)>::describe();
|
||||
}
|
||||
```
|
||||
|
||||
Or in other words it generates invocations of `describe` functions. In doing so
|
||||
the `__wbindgen_describe_greet` shim is a programmatic description of the type
|
||||
layouts of an import/export. These are then executed when `wasm-bindgen` runs!
|
||||
These executions rely on an import called `__wbindgen_describe` which passes one
|
||||
`u32` to the host, and when called multiple times gives a `Vec<u32>`
|
||||
effectively. This `Vec<u32>` can then be reparsed into an `enum Descriptor`
|
||||
which fully describes a type.
|
||||
|
||||
All in all this is a bit roundabout but shouldn't have any impact on the
|
||||
generated code or runtime at all. All these descriptor functions are pruned from
|
||||
the emitted wasm file.
|
||||
@@ -0,0 +1,149 @@
|
||||
# Exporting a struct to JS
|
||||
|
||||
So far we've covered JS objects, importing functions, and exporting functions.
|
||||
This has given us quite a rich base to build on so far, and that's great! We
|
||||
sometimes, though, want to go even further and define a JS `class` in Rust. Or
|
||||
in other words, we want to expose an object with methods from Rust to JS rather
|
||||
than just importing/exporting free functions.
|
||||
|
||||
The `#[wasm_bindgen]` attribute can annotate both a `struct` and `impl` blocks
|
||||
to allow:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub struct Foo {
|
||||
internal: i32,
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
impl Foo {
|
||||
#[wasm_bindgen(constructor)]
|
||||
pub fn new(val: i32) -> Foo {
|
||||
Foo { internal: val }
|
||||
}
|
||||
|
||||
pub fn get(&self) -> i32 {
|
||||
self.internal
|
||||
}
|
||||
|
||||
pub fn set(&mut self, val: i32) {
|
||||
self.internal = val;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is a typical Rust `struct` definition for a type with a constructor and a
|
||||
few methods. Annotating the struct with `#[wasm_bindgen]` means that we'll
|
||||
generate necessary trait impls to convert this type to/from the JS boundary. The
|
||||
annotated `impl` block here means that the functions inside will also be made
|
||||
available to JS through generated shims. If we take a look at the generated JS
|
||||
code for this we'll see:
|
||||
|
||||
```js
|
||||
import * as wasm from './js_hello_world_bg';
|
||||
|
||||
export class Foo {
|
||||
static __construct(ptr) {
|
||||
return new Foo(ptr);
|
||||
}
|
||||
|
||||
constructor(ptr) {
|
||||
this.ptr = ptr;
|
||||
}
|
||||
|
||||
free() {
|
||||
const ptr = this.ptr;
|
||||
this.ptr = 0;
|
||||
wasm.__wbg_foo_free(ptr);
|
||||
}
|
||||
|
||||
static new(arg0) {
|
||||
const ret = wasm.foo_new(arg0);
|
||||
return Foo.__construct(ret)
|
||||
}
|
||||
|
||||
get() {
|
||||
const ret = wasm.foo_get(this.ptr);
|
||||
return ret;
|
||||
}
|
||||
|
||||
set(arg0) {
|
||||
const ret = wasm.foo_set(this.ptr, arg0);
|
||||
return ret;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
That's actually not much! We can see here though how we've translated from Rust
|
||||
to JS:
|
||||
|
||||
* Associated functions in Rust (those without `self`) turn into `static`
|
||||
functions in JS.
|
||||
* Methods in Rust turn into methods in wasm.
|
||||
* Manual memory management is exposed in JS as well. The `free` function is
|
||||
required to be invoked to deallocate resources on the Rust side of things.
|
||||
|
||||
To be able to use `new Foo()`, you'd need to annotate `new` as `#[wasm_bindgen(constructor)]`.
|
||||
|
||||
One important aspect to note here, though, is that once `free` is called the JS
|
||||
object is "neutered" in that its internal pointer is nulled out. This means that
|
||||
future usage of this object should trigger a panic in Rust.
|
||||
|
||||
The real trickery with these bindings ends up happening in Rust, however, so
|
||||
let's take a look at that.
|
||||
|
||||
```rust
|
||||
// original input to `#[wasm_bindgen]` omitted ...
|
||||
|
||||
#[export_name = "foo_new"]
|
||||
pub extern "C" fn __wasm_bindgen_generated_Foo_new(arg0: i32) -> u32
|
||||
let ret = Foo::new(arg0);
|
||||
Box::into_raw(Box::new(WasmRefCell::new(ret))) as u32
|
||||
}
|
||||
|
||||
#[export_name = "foo_get"]
|
||||
pub extern "C" fn __wasm_bindgen_generated_Foo_get(me: u32) -> i32 {
|
||||
let me = me as *mut WasmRefCell<Foo>;
|
||||
wasm_bindgen::__rt::assert_not_null(me);
|
||||
let me = unsafe { &*me };
|
||||
return me.borrow().get();
|
||||
}
|
||||
|
||||
#[export_name = "foo_set"]
|
||||
pub extern "C" fn __wasm_bindgen_generated_Foo_set(me: u32, arg1: i32) {
|
||||
let me = me as *mut WasmRefCell<Foo>;
|
||||
wasm_bindgen::__rt::assert_not_null(me);
|
||||
let me = unsafe { &*me };
|
||||
me.borrow_mut().set(arg1);
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn __wbindgen_foo_free(me: u32) {
|
||||
let me = me as *mut WasmRefCell<Foo>;
|
||||
wasm_bindgen::__rt::assert_not_null(me);
|
||||
(*me).borrow_mut(); // ensure no active borrows
|
||||
drop(Box::from_raw(me));
|
||||
}
|
||||
```
|
||||
|
||||
As with before this is cleaned up from the actual output but it's the same idea
|
||||
as to what's going on! Here we can see a shim for each function as well as a
|
||||
shim for deallocating an instance of `Foo`. Recall that the only valid wasm
|
||||
types today are numbers, so we're required to shoehorn all of `Foo` into a
|
||||
`u32`, which is currently done via `Box` (like `std::unique_ptr` in C++).
|
||||
Note, though, that there's an extra layer here, `WasmRefCell`. This type is the
|
||||
same as [`RefCell`] and can be mostly glossed over.
|
||||
|
||||
The purpose for this type, if you're interested though, is to uphold Rust's
|
||||
guarantees about aliasing in a world where aliasing is rampant (JS).
|
||||
Specifically the `&Foo` type means that there can be as much aliasing as you'd
|
||||
like, but crucially `&mut Foo` means that it is the sole pointer to the data
|
||||
(no other `&Foo` to the same instance exists). The [`RefCell`] type in libstd
|
||||
is a way of dynamically enforcing this at runtime (as opposed to compile time
|
||||
where it usually happens). Baking in `WasmRefCell` is the same idea here,
|
||||
adding runtime checks for aliasing which are typically happening at compile
|
||||
time. This is currently a Rust-specific feature which isn't actually in the
|
||||
`wasm-bindgen` tool itself, it's just in the Rust-generated code (aka the
|
||||
`#[wasm_bindgen]` attribute).
|
||||
|
||||
[`RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html
|
||||
120
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/exporting-rust.md
vendored
Normal file
120
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/exporting-rust.md
vendored
Normal file
@@ -0,0 +1,120 @@
|
||||
# Exporting a function to JS
|
||||
|
||||
Alright now that we've got a good grasp on JS objects and how they're working,
|
||||
let's take a look at another feature of `wasm-bindgen`: exporting functionality
|
||||
with types that are richer than just numbers.
|
||||
|
||||
The basic idea around exporting functionality with more flavorful types is that
|
||||
the wasm exports won't actually be called directly. Instead the generated
|
||||
`foo.js` module will have shims for all exported functions in the wasm module.
|
||||
|
||||
The most interesting conversion here happens with strings so let's take a look
|
||||
at that.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub fn greet(a: &str) -> String {
|
||||
format!("Hello, {}!", a)
|
||||
}
|
||||
```
|
||||
|
||||
Here we'd like to define an ES module that looks like
|
||||
|
||||
```ts
|
||||
// foo.d.ts
|
||||
export function greet(a: string): string;
|
||||
```
|
||||
|
||||
To see what's going on, let's take a look at the generated shim
|
||||
|
||||
```js
|
||||
import * as wasm from './foo_bg';
|
||||
|
||||
function passStringToWasm(arg) {
|
||||
const buf = new TextEncoder('utf-8').encode(arg);
|
||||
const len = buf.length;
|
||||
const ptr = wasm.__wbindgen_malloc(len);
|
||||
let array = new Uint8Array(wasm.memory.buffer);
|
||||
array.set(buf, ptr);
|
||||
return [ptr, len];
|
||||
}
|
||||
|
||||
function getStringFromWasm(ptr, len) {
|
||||
const mem = new Uint8Array(wasm.memory.buffer);
|
||||
const slice = mem.slice(ptr, ptr + len);
|
||||
const ret = new TextDecoder('utf-8').decode(slice);
|
||||
return ret;
|
||||
}
|
||||
|
||||
export function greet(arg0) {
|
||||
const [ptr0, len0] = passStringToWasm(arg0);
|
||||
try {
|
||||
const ret = wasm.greet(ptr0, len0);
|
||||
const ptr = wasm.__wbindgen_boxed_str_ptr(ret);
|
||||
const len = wasm.__wbindgen_boxed_str_len(ret);
|
||||
const realRet = getStringFromWasm(ptr, len);
|
||||
wasm.__wbindgen_boxed_str_free(ret);
|
||||
return realRet;
|
||||
} finally {
|
||||
wasm.__wbindgen_free(ptr0, len0);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Phew, that's quite a lot! We can sort of see though if we look closely what's
|
||||
happening:
|
||||
|
||||
* Strings are passed to wasm via two arguments, a pointer and a length. Right
|
||||
now we have to copy the string onto the wasm heap which means we'll be using
|
||||
`TextEncoder` to actually do the encoding. Once this is done we use an
|
||||
internal function in `wasm-bindgen` to allocate space for the string to go,
|
||||
and then we'll pass that ptr/length to wasm later on.
|
||||
|
||||
* Returning strings from wasm is a little tricky as we need to return a ptr/len
|
||||
pair, but wasm currently only supports one return value (multiple return values
|
||||
[is being standardized](https://github.com/WebAssembly/design/issues/1146)).
|
||||
To work around this in the meantime, we're actually returning a pointer to a
|
||||
ptr/len pair, and then using functions to access the various fields.
|
||||
|
||||
* Some cleanup ends up happening in wasm. The `__wbindgen_boxed_str_free`
|
||||
function is used to free the return value of `greet` after it's been decoded
|
||||
onto the JS heap (using `TextDecoder`). The `__wbindgen_free` is then used to
|
||||
free the space we allocated to pass the string argument once the function call
|
||||
is done.
|
||||
|
||||
Next let's take a look at the Rust side of things as well. Here we'll be looking
|
||||
at a mostly abbreviated and/or "simplified" in the sense of this is what it
|
||||
compiles down to:
|
||||
|
||||
```rust
|
||||
pub extern "C" fn greet(a: &str) -> String {
|
||||
format!("Hello, {}!", a)
|
||||
}
|
||||
|
||||
#[export_name = "greet"]
|
||||
pub extern "C" fn __wasm_bindgen_generated_greet(
|
||||
arg0_ptr: *const u8,
|
||||
arg0_len: usize,
|
||||
) -> *mut String {
|
||||
let arg0 = unsafe {
|
||||
let slice = ::std::slice::from_raw_parts(arg0_ptr, arg0_len);
|
||||
::std::str::from_utf8_unchecked(slice)
|
||||
};
|
||||
let _ret = greet(arg0);
|
||||
Box::into_raw(Box::new(_ret))
|
||||
}
|
||||
```
|
||||
|
||||
Here we can see again that our `greet` function is unmodified and has a wrapper
|
||||
to call it. This wrapper will take the ptr/len argument and convert it to a
|
||||
string slice, while the return value is boxed up into just a pointer and is
|
||||
then returned up to was for reading via the `__wbindgen_boxed_str_*` functions.
|
||||
|
||||
So in general exporting a function involves a shim both in JS and in Rust with
|
||||
each side translating to or from wasm arguments to the native types of each
|
||||
language. The `wasm-bindgen` tool manages hooking up all these shims while the
|
||||
`#[wasm_bindgen]` macro takes care of the Rust shim as well.
|
||||
|
||||
Most arguments have a relatively clear way to convert them, bit if you've got
|
||||
any questions just let me know!
|
||||
|
||||
@@ -0,0 +1,206 @@
|
||||
# Importing a class from JS
|
||||
|
||||
Just like with functions after we've started exporting we'll also want to
|
||||
import! Now that we've exported a `class` to JS we'll want to also be able to
|
||||
import classes in Rust as well to invoke methods and such. Since JS classes are
|
||||
in general just JS objects the bindings here will look pretty similar to the JS
|
||||
object bindings describe above.
|
||||
|
||||
As usual though, let's dive into an example!
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(module = "./bar")]
|
||||
extern "C" {
|
||||
type Bar;
|
||||
|
||||
#[wasm_bindgen(constructor)]
|
||||
fn new(arg: i32) -> Bar;
|
||||
|
||||
#[wasm_bindgen(js_namespace = Bar)]
|
||||
fn another_function() -> i32;
|
||||
|
||||
#[wasm_bindgen(method)]
|
||||
fn get(this: &Bar) -> i32;
|
||||
|
||||
#[wasm_bindgen(method)]
|
||||
fn set(this: &Bar, val: i32);
|
||||
|
||||
#[wasm_bindgen(method, getter)]
|
||||
fn property(this: &Bar) -> i32;
|
||||
|
||||
#[wasm_bindgen(method, setter)]
|
||||
fn set_property(this: &Bar, val: i32);
|
||||
}
|
||||
|
||||
fn run() {
|
||||
let bar = Bar::new(Bar::another_function());
|
||||
let x = bar.get();
|
||||
bar.set(x + 3);
|
||||
|
||||
bar.set_property(bar.property() + 6);
|
||||
}
|
||||
```
|
||||
|
||||
Unlike our previous imports, this one's a bit more chatty! Remember that one of
|
||||
the goals of `wasm-bindgen` is to use native Rust syntax wherever possible, so
|
||||
this is mostly intended to use the `#[wasm_bindgen]` attribute to interpret
|
||||
what's written down in Rust. Now there's a few attribute annotations here, so
|
||||
let's go through one-by-one:
|
||||
|
||||
* `#[wasm_bindgen(module = "./bar")]` - seen before with imports this is declare
|
||||
where all the subsequent functionality is imported from. For example the `Bar`
|
||||
type is going to be imported from the `./bar` module.
|
||||
* `type Bar` - this is a declaration of JS class as a new type in Rust. This
|
||||
means that a new type `Bar` is generated which is "opaque" but is represented
|
||||
as internally containing a `JsValue`. We'll see more on this later.
|
||||
* `#[wasm_bindgen(constructor)]` - this indicates that the binding's name isn't
|
||||
actually used in JS but rather translates to `new Bar()`. The return value of
|
||||
this function must be a bare type, like `Bar`.
|
||||
* `#[wasm_bindgen(js_namespace = Bar)]` - this attribute indicates that the
|
||||
function declaration is namespaced through the `Bar` class in JS.
|
||||
* `#[wasm_bindgen(static_method_of = SomeJsClass)]` - this attribute is similar
|
||||
to `js_namespace`, but instead of producing a free function, produces a static
|
||||
method of `SomeJsClass`.
|
||||
* `#[wasm_bindgen(method)]` - and finally, this attribute indicates that a
|
||||
method call is going to happen. The first argument must be a JS struct, like
|
||||
`Bar`, and the call in JS looks like `Bar.prototype.set.call(...)`.
|
||||
|
||||
With all that in mind, let's take a look at the JS generated.
|
||||
|
||||
```js
|
||||
import * as wasm from './foo_bg';
|
||||
|
||||
import { Bar } from './bar';
|
||||
|
||||
// other support functions omitted...
|
||||
|
||||
export function __wbg_s_Bar_new() {
|
||||
return addHeapObject(new Bar());
|
||||
}
|
||||
|
||||
const another_function_shim = Bar.another_function;
|
||||
export function __wbg_s_Bar_another_function() {
|
||||
return another_function_shim();
|
||||
}
|
||||
|
||||
const get_shim = Bar.prototype.get;
|
||||
export function __wbg_s_Bar_get(ptr) {
|
||||
return shim.call(getObject(ptr));
|
||||
}
|
||||
|
||||
const set_shim = Bar.prototype.set;
|
||||
export function __wbg_s_Bar_set(ptr, arg0) {
|
||||
set_shim.call(getObject(ptr), arg0)
|
||||
}
|
||||
|
||||
const property_shim = Object.getOwnPropertyDescriptor(Bar.prototype, 'property').get;
|
||||
export function __wbg_s_Bar_property(ptr) {
|
||||
return property_shim.call(getObject(ptr));
|
||||
}
|
||||
|
||||
const set_property_shim = Object.getOwnPropertyDescriptor(Bar.prototype, 'property').set;
|
||||
export function __wbg_s_Bar_set_property(ptr, arg0) {
|
||||
set_property_shim.call(getObject(ptr), arg0)
|
||||
}
|
||||
```
|
||||
|
||||
Like when importing functions from JS we can see a bunch of shims are generated
|
||||
for all the relevant functions. The `new` static function has the
|
||||
`#[wasm_bindgen(constructor)]` attribute which means that instead of any
|
||||
particular method it should actually invoke the `new` constructor instead (as
|
||||
we see here). The static function `another_function`, however, is dispatched as
|
||||
`Bar.another_function`.
|
||||
|
||||
The `get` and `set` functions are methods so they go through `Bar.prototype`,
|
||||
and otherwise their first argument is implicitly the JS object itself which is
|
||||
loaded through `getObject` like we saw earlier.
|
||||
|
||||
Some real meat starts to show up though on the Rust side of things, so let's
|
||||
take a look:
|
||||
|
||||
```rust
|
||||
pub struct Bar {
|
||||
obj: JsValue,
|
||||
}
|
||||
|
||||
impl Bar {
|
||||
fn new() -> Bar {
|
||||
extern "C" {
|
||||
fn __wbg_s_Bar_new() -> u32;
|
||||
}
|
||||
unsafe {
|
||||
let ret = __wbg_s_Bar_new();
|
||||
Bar { obj: JsValue::__from_idx(ret) }
|
||||
}
|
||||
}
|
||||
|
||||
fn another_function() -> i32 {
|
||||
extern "C" {
|
||||
fn __wbg_s_Bar_another_function() -> i32;
|
||||
}
|
||||
unsafe {
|
||||
__wbg_s_Bar_another_function()
|
||||
}
|
||||
}
|
||||
|
||||
fn get(&self) -> i32 {
|
||||
extern "C" {
|
||||
fn __wbg_s_Bar_get(ptr: u32) -> i32;
|
||||
}
|
||||
unsafe {
|
||||
let ptr = self.obj.__get_idx();
|
||||
let ret = __wbg_s_Bar_get(ptr);
|
||||
return ret
|
||||
}
|
||||
}
|
||||
|
||||
fn set(&self, val: i32) {
|
||||
extern "C" {
|
||||
fn __wbg_s_Bar_set(ptr: u32, val: i32);
|
||||
}
|
||||
unsafe {
|
||||
let ptr = self.obj.__get_idx();
|
||||
__wbg_s_Bar_set(ptr, val);
|
||||
}
|
||||
}
|
||||
|
||||
fn property(&self) -> i32 {
|
||||
extern "C" {
|
||||
fn __wbg_s_Bar_property(ptr: u32) -> i32;
|
||||
}
|
||||
unsafe {
|
||||
let ptr = self.obj.__get_idx();
|
||||
let ret = __wbg_s_Bar_property(ptr);
|
||||
return ret
|
||||
}
|
||||
}
|
||||
|
||||
fn set_property(&self, val: i32) {
|
||||
extern "C" {
|
||||
fn __wbg_s_Bar_set_property(ptr: u32, val: i32);
|
||||
}
|
||||
unsafe {
|
||||
let ptr = self.obj.__get_idx();
|
||||
__wbg_s_Bar_set_property(ptr, val);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl WasmBoundary for Bar {
|
||||
// ...
|
||||
}
|
||||
|
||||
impl ToRefWasmBoundary for Bar {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
In Rust we're seeing that a new type, `Bar`, is generated for this import of a
|
||||
class. The type `Bar` internally contains a `JsValue` as an instance of `Bar`
|
||||
is meant to represent a JS object stored in our module's stack/slab. This then
|
||||
works mostly the same way that we saw JS objects work in the beginning.
|
||||
|
||||
When calling `Bar::new` we'll get an index back which is wrapped up in `Bar`
|
||||
(which is itself just a `u32` in memory when stripped down). Each function then
|
||||
passes the index as the first argument and otherwise forwards everything along
|
||||
in Rust.
|
||||
75
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/importing-js.md
vendored
Normal file
75
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/importing-js.md
vendored
Normal file
@@ -0,0 +1,75 @@
|
||||
# Importing a function from JS
|
||||
|
||||
Now that we've exported some rich functionality to JS it's also time to import
|
||||
some! The goal here is to basically implement JS `import` statements in Rust,
|
||||
with fancy types and all.
|
||||
|
||||
First up, let's say we invert the function above and instead want to generate
|
||||
greetings in JS but call it from Rust. We might have, for example:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(module = "./greet")]
|
||||
extern "C" {
|
||||
fn greet(a: &str) -> String;
|
||||
}
|
||||
|
||||
fn other_code() {
|
||||
let greeting = greet("foo");
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
The basic idea of imports is the same as exports in that we'll have shims in
|
||||
both JS and Rust doing the necessary translation. Let's first see the JS shim in
|
||||
action:
|
||||
|
||||
```js
|
||||
import * as wasm from './foo_bg';
|
||||
|
||||
import { greet } from './greet';
|
||||
|
||||
// ...
|
||||
|
||||
export function __wbg_f_greet(ptr0, len0, wasmretptr) {
|
||||
const [retptr, retlen] = passStringToWasm(greet(getStringFromWasm(ptr0, len0)));
|
||||
(new Uint32Array(wasm.memory.buffer))[wasmretptr / 4] = retlen;
|
||||
return retptr;
|
||||
}
|
||||
```
|
||||
|
||||
The `getStringFromWasm` and `passStringToWasm` are the same as we saw before,
|
||||
and like with `__wbindgen_object_drop_ref` far above we've got this weird export
|
||||
from our module now! The `__wbg_f_greet` function is what's generated by
|
||||
`wasm-bindgen` to actually get imported in the `foo.wasm` module.
|
||||
|
||||
The generated `foo.js` we see imports from the `./greet` module with the `greet`
|
||||
name (was the function import in Rust said) and then the `__wbg_f_greet`
|
||||
function is shimming that import.
|
||||
|
||||
There's some tricky ABI business going on here so let's take a look at the
|
||||
generated Rust as well. Like before this is simplified from what's actually
|
||||
generated.
|
||||
|
||||
```rust
|
||||
extern "C" fn greet(a: &str) -> String {
|
||||
extern "C" {
|
||||
fn __wbg_f_greet(a_ptr: *const u8, a_len: usize, ret_len: *mut usize) -> *mut u8;
|
||||
}
|
||||
unsafe {
|
||||
let a_ptr = a.as_ptr();
|
||||
let a_len = a.len();
|
||||
let mut __ret_strlen = 0;
|
||||
let mut __ret_strlen_ptr = &mut __ret_strlen as *mut usize;
|
||||
let _ret = __wbg_f_greet(a_ptr, a_len, __ret_strlen_ptr);
|
||||
String::from_utf8_unchecked(
|
||||
Vec::from_raw_parts(_ret, __ret_strlen, __ret_strlen)
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Here we can see that the `greet` function was generated but it's largely just a
|
||||
shim around the `__wbg_f_greet` function that we're calling. The ptr/len pair
|
||||
for the argument is passed as two arguments and for the return value we're
|
||||
receiving one value (the length) indirectly while directly receiving the
|
||||
returned pointer.
|
||||
67
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/index.md
vendored
Normal file
67
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/index.md
vendored
Normal file
@@ -0,0 +1,67 @@
|
||||
# Design of `wasm-bindgen`
|
||||
|
||||
This section is intended to be a deep-dive into how `wasm-bindgen` internally
|
||||
works today, specifically for Rust. If you're reading this far in the future it
|
||||
may no longer be up to date, but feel free to open an issue and we can try to
|
||||
answer questions and/or update this!
|
||||
|
||||
## Foundation: ES Modules
|
||||
|
||||
The first thing to know about `wasm-bindgen` is that it's fundamentally built on
|
||||
the idea of ES Modules. In other words this tool takes an opinionated stance
|
||||
that wasm files *should be viewed as ES modules*. This means that you can
|
||||
`import` from a wasm file, use its `export`-ed functionality, etc, from normal
|
||||
JS files.
|
||||
|
||||
Now unfortunately at the time of this writing the interface of wasm interop
|
||||
isn't very rich. Wasm modules can only call functions or export functions that
|
||||
deal exclusively with `i32`, `i64`, `f32`, and `f64`. Bummer!
|
||||
|
||||
That's where this project comes in. The goal of `wasm-bindgen` is to enhance the
|
||||
"ABI" of wasm modules with richer types like classes, JS objects, Rust structs,
|
||||
strings, etc. Keep in mind, though, that everything is based on ES Modules! This
|
||||
means that the compiler is actually producing a "broken" wasm file of sorts. The
|
||||
wasm file emitted by rustc, for example, does not have the interface we would
|
||||
like to have. Instead it requires the `wasm-bindgen` tool to postprocess the
|
||||
file, generating a `foo.js` and `foo_bg.wasm` file. The `foo.js` file is the
|
||||
desired interface expressed in JS (classes, types, strings, etc) and the
|
||||
`foo_bg.wasm` module is simply used as an implementation detail (it was
|
||||
lightly modified from the original `foo.wasm` file).
|
||||
|
||||
As more features are stabilized in WebAssembly over time (like host bindings)
|
||||
the JS file is expected to get smaller and smaller. It's unlikely to ever
|
||||
disappear, but `wasm-bindgen` is designed to follow the WebAssembly spec and
|
||||
proposals closely to optimize JS/Rust as much as possible.
|
||||
|
||||
## Foundation #2: Unintrusive in Rust
|
||||
|
||||
On the more Rust-y side of things the `wasm-bindgen` crate is designed to
|
||||
ideally have as minimal impact on a Rust crate as possible. Ideally a few
|
||||
`#[wasm_bindgen]` attributes are annotated in key locations and otherwise you're
|
||||
off to the races. The attribute strives to both not invent new syntax and work
|
||||
with existing idioms today.
|
||||
|
||||
For example a library might exposed a function in normal Rust that looks like:
|
||||
|
||||
```rust
|
||||
pub fn greet(name: &str) -> String {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
And with `#[wasm_bindgen]` all you need to do in exporting it to JS is:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub fn greet(name: &str) -> String {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Additionally the design here with minimal intervention in Rust should allow us
|
||||
to easily take advantage of the upcoming [host bindings][host] proposal. Ideally
|
||||
you'd simply upgrade `wasm-bindgen`-the-crate as well as your toolchain and
|
||||
you're immediately getting raw access to host bindings! (this is still a bit of
|
||||
a ways off though...)
|
||||
|
||||
[host]: https://github.com/WebAssembly/host-bindings
|
||||
237
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/js-objects-in-rust.md
vendored
Normal file
237
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/design/js-objects-in-rust.md
vendored
Normal file
@@ -0,0 +1,237 @@
|
||||
# Polyfill for "JS objects in wasm"
|
||||
|
||||
One of the main goals of `wasm-bindgen` is to allow working with and passing
|
||||
around JS objects in wasm, but that's not allowed today! While indeed true,
|
||||
that's where the polyfill comes in.
|
||||
|
||||
The question here is how we shoehorn JS objects into a `u32` for wasm to use.
|
||||
The current strategy for this approach is to maintain a module-local variable
|
||||
in the generated `foo.js` file: a `heap`.
|
||||
|
||||
### Temporary JS objects on the "stack"
|
||||
|
||||
The first slots in the `heap` in `foo.js` are considered a stack. This stack,
|
||||
like typical program execution stacks, grows down. JS objects are pushed on the
|
||||
bottom of the stack, and their index in the stack is the identifier that's passed
|
||||
to wasm. A stack pointer is maintained to figure out where the next item is
|
||||
pushed.
|
||||
|
||||
JS objects are then only removed from the bottom of the stack as well. Removal
|
||||
is simply storing null then incrementing a counter. Because of the "stack-y"
|
||||
nature of this scheme it only works for when wasm doesn't hold onto a JS object
|
||||
(aka it only gets a "reference" in Rust parlance).
|
||||
|
||||
Let's take a look at an example.
|
||||
|
||||
```rust
|
||||
// foo.rs
|
||||
#[wasm_bindgen]
|
||||
pub fn foo(a: &JsValue) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Here we're using the special `JsValue` type from the `wasm-bindgen` library
|
||||
itself. Our exported function, `foo`, takes a *reference* to an object. This
|
||||
notably means that it can't persist the object past the lifetime of this
|
||||
function call.
|
||||
|
||||
Now what we actually want to generate is a JS module that looks like (in
|
||||
TypeScript parlance)
|
||||
|
||||
```ts
|
||||
// foo.d.ts
|
||||
export function foo(a: any);
|
||||
```
|
||||
|
||||
and what we actually generate looks something like:
|
||||
|
||||
```js
|
||||
// foo.js
|
||||
import * as wasm from './foo_bg';
|
||||
|
||||
const heap = new Array(32);
|
||||
heap.push(undefined, null, true, false);
|
||||
let stack_pointer = 32;
|
||||
|
||||
function addBorrowedObject(obj) {
|
||||
stack_pointer -= 1;
|
||||
heap[stack_pointer] = obj;
|
||||
return stack_pointer;
|
||||
}
|
||||
|
||||
export function foo(arg0) {
|
||||
const idx0 = addBorrowedObject(arg0);
|
||||
try {
|
||||
wasm.foo(idx0);
|
||||
} finally {
|
||||
heap[stack_pointer++] = undefined;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Here we can see a few notable points of action:
|
||||
|
||||
* The wasm file was renamed to `foo_bg.wasm`, and we can see how the JS module
|
||||
generated here is importing from the wasm file.
|
||||
* Next we can see our `heap` module variable which is to store all JS values
|
||||
reference-able from wasm.
|
||||
* Our exported function `foo`, takes an arbitrary argument, `arg0`, which is
|
||||
converted to an index with the `addBorrowedObject` object function. The index
|
||||
is then passed to wasm so wasm can operate with it.
|
||||
* Finally, we have a `finally` which frees the stack slot as it's no longer
|
||||
used, popping the value that was pushed at the start of the function.
|
||||
|
||||
It's also helpful to dig into the Rust side of things to see what's going on
|
||||
there! Let's take a look at the code that `#[wasm_bindgen]` generates in Rust:
|
||||
|
||||
```rust
|
||||
// what the user wrote
|
||||
pub fn foo(a: &JsValue) {
|
||||
// ...
|
||||
}
|
||||
|
||||
#[export_name = "foo"]
|
||||
pub extern "C" fn __wasm_bindgen_generated_foo(arg0: u32) {
|
||||
let arg0 = unsafe {
|
||||
ManuallyDrop::new(JsValue::__from_idx(arg0))
|
||||
};
|
||||
let arg0 = &*arg0;
|
||||
foo(arg0);
|
||||
}
|
||||
```
|
||||
|
||||
And as with the JS, the notable points here are:
|
||||
|
||||
* The original function, `foo`, is unmodified in the output
|
||||
* A generated function here (with a unique name) is the one that's actually
|
||||
exported from the wasm module
|
||||
* Our generated function takes an integer argument (our index) and then wraps it
|
||||
in a `JsValue`. There's some trickery here that's not worth going into just
|
||||
yet, but we'll see in a bit what's happening under the hood.
|
||||
|
||||
### Long-lived JS objects
|
||||
|
||||
The above strategy is useful when JS objects are only temporarily used in Rust,
|
||||
for example only during one function call. Sometimes, though, objects may have a
|
||||
dynamic lifetime or otherwise need to be stored on Rust's heap. To cope with
|
||||
this there's a second half of management of JS objects, naturally corresponding
|
||||
to the other side of the JS `heap` array.
|
||||
|
||||
JS Objects passed to wasm that are not references are assumed to have a dynamic
|
||||
lifetime inside of the wasm module. As a result the strict push/pop of the stack
|
||||
won't work and we need more permanent storage for the JS objects. To cope with
|
||||
this we build our own "slab allocator" of sorts.
|
||||
|
||||
A picture (or code) is worth a thousand words so let's show what happens with an
|
||||
example.
|
||||
|
||||
```rust
|
||||
// foo.rs
|
||||
#[wasm_bindgen]
|
||||
pub fn foo(a: JsValue) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Note that the `&` is missing in front of the `JsValue` we had before, and in
|
||||
Rust parlance this means it's taking ownership of the JS value. The exported ES
|
||||
module interface is the same as before, but the ownership mechanics are slightly
|
||||
different. Let's see the generated JS's slab in action:
|
||||
|
||||
```js
|
||||
import * as wasm from './foo_bg'; // imports from wasm file
|
||||
|
||||
const heap = new Array(32);
|
||||
heap.push(undefined, null, true, false);
|
||||
let heap_next = 36;
|
||||
|
||||
function addHeapObject(obj) {
|
||||
if (heap_next === heap.length)
|
||||
heap.push(heap.length + 1);
|
||||
const idx = heap_next;
|
||||
heap_next = heap[idx];
|
||||
heap[idx] = obj;
|
||||
return idx;
|
||||
}
|
||||
|
||||
export function foo(arg0) {
|
||||
const idx0 = addHeapObject(arg0);
|
||||
wasm.foo(idx0);
|
||||
}
|
||||
|
||||
export function __wbindgen_object_drop_ref(idx) {
|
||||
heap[idx ] = heap_next;
|
||||
heap_next = idx;
|
||||
}
|
||||
```
|
||||
|
||||
Unlike before we're now calling `addHeapObject` on the argument to `foo` rather
|
||||
than `addBorrowedObject`. This function will use `heap` and `heap_next` as a
|
||||
slab allocator to acquire a slot to store the object, placing a structure there
|
||||
once it's found. Note that this is going on the right-half of the array, unlike
|
||||
the stack which resides on the left half. This discipline mirrors the stack/heap
|
||||
in normal programs, roughly.
|
||||
|
||||
Another curious aspect of this generated module is the
|
||||
`__wbindgen_object_drop_ref` function. This is one that's actually imported to
|
||||
wasm rather than used in this module! This function is used to signal the end of
|
||||
the lifetime of a `JsValue` in Rust, or in other words when it goes out of
|
||||
scope. Otherwise though this function is largely just a general "slab free"
|
||||
implementation.
|
||||
|
||||
And finally, let's take a look at the Rust generated again too:
|
||||
|
||||
```rust
|
||||
// what the user wrote
|
||||
pub fn foo(a: JsValue) {
|
||||
// ...
|
||||
}
|
||||
|
||||
#[export_name = "foo"]
|
||||
pub extern "C" fn __wasm_bindgen_generated_foo(arg0: u32) {
|
||||
let arg0 = unsafe {
|
||||
JsValue::__from_idx(arg0)
|
||||
};
|
||||
foo(arg0);
|
||||
}
|
||||
```
|
||||
|
||||
Ah that looks much more familiar! Not much interesting is happening here, so
|
||||
let's move on to...
|
||||
|
||||
### Anatomy of `JsValue`
|
||||
|
||||
Currently the `JsValue` struct is actually quite simple in Rust, it's:
|
||||
|
||||
```rust
|
||||
pub struct JsValue {
|
||||
idx: u32,
|
||||
}
|
||||
|
||||
// "private" constructors
|
||||
|
||||
impl Drop for JsValue {
|
||||
fn drop(&mut self) {
|
||||
unsafe {
|
||||
__wbindgen_object_drop_ref(self.idx);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or in other words it's a newtype wrapper around a `u32`, the index that we're
|
||||
passed from wasm. The destructor here is where the `__wbindgen_object_drop_ref`
|
||||
function is called to relinquish our reference count of the JS object, freeing
|
||||
up our slot in the `slab` that we saw above.
|
||||
|
||||
If you'll recall as well, when we took `&JsValue` above we generated a wrapper
|
||||
of `ManuallyDrop` around the local binding, and that's because we wanted to
|
||||
avoid invoking this destructor when the object comes from the stack.
|
||||
|
||||
### Working with `heap` in reality
|
||||
|
||||
The above explanations are pretty close to what happens today, but in reality
|
||||
there's a few differences especially around handling constant values like
|
||||
`undefined`, `null`, etc. Be sure to check out the actual generated JS and the
|
||||
generation code for the full details!
|
||||
@@ -0,0 +1,97 @@
|
||||
# Rust Type conversions
|
||||
|
||||
Previously we've been seeing mostly abridged versions of type conversions when
|
||||
values enter Rust. Here we'll go into some more depth about how this is
|
||||
implemented. There are two categories of traits for converting values, traits
|
||||
for converting values from Rust to JS and traits for the other way around.
|
||||
|
||||
## From Rust to JS
|
||||
|
||||
First up let's take a look at going from Rust to JS:
|
||||
|
||||
```rust
|
||||
pub trait IntoWasmAbi: WasmDescribe {
|
||||
type Abi: WasmAbi;
|
||||
fn into_abi(self) -> Self::Abi;
|
||||
}
|
||||
```
|
||||
|
||||
And that's it! This is actually the only trait needed currently for translating
|
||||
a Rust value to a JS one. There's a few points here:
|
||||
|
||||
* We'll get to `WasmDescribe` later in this section.
|
||||
|
||||
* The associated type `Abi` is what will actually be generated as an argument /
|
||||
return type for the `extern "C"` functions used to declare wasm imports/exports.
|
||||
The bound `WasmAbi` is implemented for primitive types like `u32` and `f64`,
|
||||
which can be represented directly as WebAssembly values, as well of a couple
|
||||
of `#[repr(C)]` types like `WasmSlice`:
|
||||
|
||||
```rust
|
||||
#[repr(C)]
|
||||
pub struct WasmSlice {
|
||||
pub ptr: u32,
|
||||
pub len: u32,
|
||||
}
|
||||
```
|
||||
|
||||
This struct, which is how things like strings are represented in FFI, isn't
|
||||
a WebAssembly primitive type and so isn't mapped directly to a WebAssembly
|
||||
parameter / return value; instead, the C ABI flattens it out into two arguments
|
||||
or stores it on the stack.
|
||||
|
||||
* And finally we have the `into_abi` function, returning the `Abi` associated
|
||||
type which will be actually passed to JS.
|
||||
|
||||
This trait is implemented for all types that can be converted to JS and is
|
||||
unconditionally used during codegen. For example you'll often see `IntoWasmAbi
|
||||
for Foo` but also `IntoWasmAbi for &'a Foo`.
|
||||
|
||||
The `IntoWasmAbi` trait is used in two locations. First it's used to convert
|
||||
return values of Rust exported functions to JS. Second it's used to convert the
|
||||
Rust arguments of JS functions imported to Rust.
|
||||
|
||||
## From JS to Rust
|
||||
|
||||
Unfortunately the opposite direction from above, going from JS to Rust, is a bit
|
||||
more complicated. Here we've got three traits:
|
||||
|
||||
```rust
|
||||
pub trait FromWasmAbi: WasmDescribe {
|
||||
type Abi: WasmAbi;
|
||||
unsafe fn from_abi(js: Self::Abi) -> Self;
|
||||
}
|
||||
|
||||
pub trait RefFromWasmAbi: WasmDescribe {
|
||||
type Abi: WasmAbi;
|
||||
type Anchor: Deref<Target=Self>;
|
||||
unsafe fn ref_from_abi(js: Self::Abi) -> Self::Anchor;
|
||||
}
|
||||
|
||||
pub trait RefMutFromWasmAbi: WasmDescribe {
|
||||
type Abi: WasmAbi;
|
||||
type Anchor: DerefMut<Target=Self>;
|
||||
unsafe fn ref_mut_from_abi(js: Self::Abi) -> Self::Anchor;
|
||||
}
|
||||
```
|
||||
|
||||
The `FromWasmAbi` is relatively straightforward, basically the opposite of
|
||||
`IntoWasmAbi`. It takes the ABI argument (typically the same as
|
||||
`IntoWasmAbi::Abi`) to produce an instance of
|
||||
`Self`. This trait is implemented primarily for types that *don't* have internal
|
||||
lifetimes or are references.
|
||||
|
||||
The latter two traits here are mostly the same, and are intended for generating
|
||||
references (both shared and mutable references). They look almost the same as
|
||||
`FromWasmAbi` except that they return an `Anchor` type which implements a
|
||||
`Deref` trait rather than `Self`.
|
||||
|
||||
The `Ref*` traits allow having arguments in functions that are references rather
|
||||
than bare types, for example `&str`, `&JsValue`, or `&[u8]`. The `Anchor` here
|
||||
is required to ensure that the lifetimes don't persist beyond one function call
|
||||
and remain anonymous.
|
||||
|
||||
The `From*` family of traits are used for converting the Rust arguments in Rust
|
||||
exported functions to JS. They are also used for the return value in JS
|
||||
functions imported into Rust.
|
||||
|
||||
26
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/index.md
vendored
Normal file
26
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/index.md
vendored
Normal file
@@ -0,0 +1,26 @@
|
||||
# Contributing to `wasm-bindgen`
|
||||
|
||||
This section contains instructions on how to get this project up and running for
|
||||
development. You may want to browse the [unpublished guide documentation] for
|
||||
`wasm-bindgen` as well as it may have more up-to-date information.
|
||||
|
||||
[unpublished documentation]: https://rustwasm.github.io/wasm-bindgen/
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Rust. [Install Rust]. Once Rust is installed, run
|
||||
|
||||
```shell
|
||||
rustup target add wasm32-unknown-unknown
|
||||
```
|
||||
|
||||
[install Rust]: https://www.rust-lang.org/en-US/install.html
|
||||
|
||||
2. The tests for this project use Node. Make sure you have node >= 10 installed,
|
||||
as that is when WebAssembly support was introduced. [Install Node].
|
||||
|
||||
[Install Node]: https://nodejs.org/en/
|
||||
|
||||
## Code Formatting
|
||||
|
||||
Although formatting rules are not mandatory, it is encouraged to run `cargo run` (`rustfmt`) with its default rules within a PR to maintain a more organized code base. If necessary, a PR with a single commit that formats the entire project is also welcome.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Adding Support for More JavaScript Global APIs
|
||||
|
||||
As of 2018-09-24 we've [added all APIs][issue] in the current ECMAScript
|
||||
standard (yay!). To that end you'll hopefully not find a missing API, but if you
|
||||
do please feel free to file an issue!
|
||||
|
||||
We currently add new APIs added to ECMAScript that are in [TC39 stage 4][tc39]
|
||||
to this crate. If there's a new API in stage 4, feel free to file an issue as
|
||||
well!
|
||||
|
||||
### Instructions for adding an API
|
||||
|
||||
* [ ] Find the `wasm-bindgen` issue for the API you'd like to add. If this
|
||||
doesn't exist, feel free to open one! Afterwards be sure to comment on the
|
||||
issue to avoid duplication of work.
|
||||
|
||||
* [ ] Open the [MDN
|
||||
page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects)
|
||||
for the relevant JS API.
|
||||
|
||||
* [ ] Open `crates/js-sys/src/lib.rs` in your editor; this is the file where we
|
||||
are implementing the bindings.
|
||||
|
||||
* [ ] Follow the instructions in the top of `crates/js-sys/src/lib.rs` about how
|
||||
to add new bindings.
|
||||
|
||||
* [ ] Add a test for the new binding to `crates/js-sys/tests/wasm/MyType.rs`
|
||||
|
||||
* [ ] Run the [JS global API bindings tests][test]
|
||||
|
||||
* [ ] Send a pull request!
|
||||
|
||||
[issue]: https://github.com/rustwasm/wasm-bindgen/issues/275
|
||||
[tc39]: https://tc39.github.io/process-document/
|
||||
[test]: testing.html
|
||||
45
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/js-sys/index.md
vendored
Normal file
45
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/js-sys/index.md
vendored
Normal file
@@ -0,0 +1,45 @@
|
||||
# `js-sys`
|
||||
|
||||
The [`js-sys` crate][js-sys] provides raw bindings to all the global APIs
|
||||
guaranteed to exist in every JavaScript environment by the ECMAScript standard,
|
||||
and its source lives at [`wasm-bindgen/crates/js-sys`][src]. With the `js-sys`
|
||||
crate, we can work with `Object`s, `Array`s, `Function`s, `Map`s, `Set`s,
|
||||
etc... without writing the `#[wasm_bindgen]` imports by hand.
|
||||
|
||||
Documentation for the published version of this crate is available on
|
||||
[docs.rs][docsrs] but you can also check out the [master branch
|
||||
documentation][masterdoc] for the crate.
|
||||
|
||||
[docsrs]: https://docs.rs/js-sys
|
||||
[masterdoc]: https://rustwasm.github.io/wasm-bindgen/api/js_sys/
|
||||
[src]: https://github.com/rustwasm/wasm-bindgen/tree/master/crates/js-sys
|
||||
|
||||
For example, we can invoke JavaScript [`Function`][mdn-function] callbacks and
|
||||
time how long they take to execute with [`Date.now()`][mdn-date-now], and we
|
||||
don't need to write any JS imports ourselves:
|
||||
|
||||
```rust
|
||||
use wasm_bindgen::prelude::*;
|
||||
|
||||
#[wasm_bindgen]
|
||||
pub fn timed(callback: &js_sys::Function) -> f64 {
|
||||
let then = js_sys::Date::now();
|
||||
callback.apply(JsValue::null(), &js_sys::Array::new()).unwrap();
|
||||
let now = js_sys::Date::now();
|
||||
now - then
|
||||
}
|
||||
```
|
||||
|
||||
The `js-sys` crate doesn't contain bindings to any Web APIs like
|
||||
[`document.querySelectorAll`][mdn-qsa]. These will be part of the
|
||||
[`web-sys`][web-sys] crate.
|
||||
|
||||
[MDN]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects
|
||||
[js-sys]: https://crates.io/crates/js-sys
|
||||
[issue]: https://github.com/rustwasm/wasm-bindgen/issues/275
|
||||
[mdn-function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
|
||||
[mdn-qsa]: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll
|
||||
[web-sys]: https://crates.io/crates/web-sys
|
||||
[web-sys-contributing]: https://rustwasm.github.io/wasm-bindgen/web-sys.html
|
||||
[web-sys-issues]: https://github.com/rustwasm/wasm-bindgen/issues?q=is%3Aissue+is%3Aopen+label%3Aweb-sys
|
||||
[mdn-date-now]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now
|
||||
13
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/js-sys/testing.md
vendored
Normal file
13
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/js-sys/testing.md
vendored
Normal file
@@ -0,0 +1,13 @@
|
||||
# Testing
|
||||
|
||||
You can test the `js-sys` crate by running `cargo test --target
|
||||
wasm32-unknown-unknown` within the `crates/js-sys` directory in the
|
||||
`wasm-bindgen` repository:
|
||||
|
||||
```sh
|
||||
cd wasm-bindgen/crates/js-sys
|
||||
cargo test --target wasm32-unknown-unknown
|
||||
```
|
||||
|
||||
These tests are largely executed in Node.js right now via the
|
||||
[`wasm-bindgen-test` framework](../../wasm-bindgen-test/index.html)
|
||||
24
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/publishing.md
vendored
Normal file
24
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/publishing.md
vendored
Normal file
@@ -0,0 +1,24 @@
|
||||
# Publishing New `wasm-bindgen` Releases
|
||||
|
||||
1. <input type="checkbox"/> Compile the `publish.rs` script:
|
||||
|
||||
```
|
||||
rustc publish.rs
|
||||
```
|
||||
|
||||
2. <input type="checkbox"/> Bump every crate's minor version:
|
||||
|
||||
```
|
||||
# Make sure you are in the root of the wasm-bindgen repo!
|
||||
./publish bump
|
||||
```
|
||||
|
||||
3. <input type="checkbox"/> Send a pull request for the version bump.
|
||||
|
||||
4. <input type="checkbox"/> After the pull request's CI is green and it has been
|
||||
merged, publish to cargo:
|
||||
|
||||
```
|
||||
# Make sure you are in the root of the wasm-bindgen repo!
|
||||
./publish publish
|
||||
```
|
||||
36
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/team.md
vendored
Normal file
36
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/team.md
vendored
Normal file
@@ -0,0 +1,36 @@
|
||||
# Team
|
||||
|
||||
`wasm-bindgen` follows the [`rustwasm` organization's governance described
|
||||
here][governance]:
|
||||
|
||||
* All pull requests (including those made by a team member) must be approved by
|
||||
at least one other team member.
|
||||
|
||||
* Larger, more nuanced decisions about design, architecture, breaking changes,
|
||||
trade offs, etc are made by team consensus.
|
||||
|
||||
[governance]: https://github.com/rustwasm/team/blob/master/GOVERNANCE.md#repositories
|
||||
|
||||
## Members
|
||||
|
||||
<style>
|
||||
img {
|
||||
max-width: 117px;
|
||||
max-height: 117px;
|
||||
}
|
||||
</style>
|
||||
|
||||
| [][alexcrichton] | [][fitzgen] | [][spastorino] | [][ohanar] | [][jonathan-s] |
|
||||
|:---:|:---:|:---:|:---:|
|
||||
| [`alexcrichton`][alexcrichton] | [`fitzgen`][fitzgen] | [`spastorino`][spastorino] | [`ohanar`][ohanar] | [`jonathan-s`][jonathan-s] |
|
||||
| [][sendilkumarn] | [][belfz] | [][afdw] | | |
|
||||
| [`sendilkumarn`][sendilkumarn] | [`belfz`][belfz] | [`afdw`][afdw] | | |
|
||||
|
||||
[alexcrichton]: https://github.com/alexcrichton
|
||||
[fitzgen]: https://github.com/fitzgen
|
||||
[spastorino]: https://github.com/spastorino
|
||||
[ohanar]: https://github.com/ohanar
|
||||
[jonathan-s]: https://github.com/jonathan-s
|
||||
[sendilkumarn]: https://github.com/sendilkumarn
|
||||
[belfz]: https://github.com/belfz
|
||||
[afdw]: https://github.com/afdw
|
||||
47
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/testing.md
vendored
Normal file
47
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/testing.md
vendored
Normal file
@@ -0,0 +1,47 @@
|
||||
# Running `wasm-bindgen`'s Tests
|
||||
|
||||
## Wasm Tests on Node and Headless Browsers
|
||||
|
||||
These are the largest test suites, and most common to run in day to day
|
||||
`wasm-bindgen` development. These tests are compiled to Wasm and then run in
|
||||
Node.js or a headless browser via the WebDriver protocol.
|
||||
|
||||
```bash
|
||||
cargo test --target wasm32-unknown-unknown
|
||||
```
|
||||
|
||||
See [the `wasm-bindgen-test` crate's
|
||||
`README.md`](https://github.com/rustwasm/wasm-bindgen/blob/master/crates/test/README.md)
|
||||
for details and configuring which headless browser is used.
|
||||
|
||||
## Sanity Tests for `wasm-bindgen` on the Native Host Target
|
||||
|
||||
This small test suite just verifies that exported `wasm-bindgen` methods can
|
||||
still be used on the native host's target.
|
||||
|
||||
```
|
||||
cargo test
|
||||
```
|
||||
|
||||
## The Web IDL Frontend's Tests
|
||||
|
||||
```
|
||||
cargo test -p webidl-tests --target wasm32-unknown-unknown
|
||||
```
|
||||
|
||||
## The Macro UI Tests
|
||||
|
||||
These tests assert that we have reasonable error messages that point to the
|
||||
right source spans when the `#[wasm_bindgen]` proc-macro is misused.
|
||||
|
||||
```
|
||||
cargo test -p ui-tests
|
||||
```
|
||||
|
||||
## The `js-sys` Tests
|
||||
|
||||
See [the `js-sys` testing page](js-sys/testing.html).
|
||||
|
||||
## The `web-sys` Tests
|
||||
|
||||
See [the `web-sys` testing page](web-sys/testing.html).
|
||||
17
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/web-sys/index.md
vendored
Normal file
17
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/web-sys/index.md
vendored
Normal file
@@ -0,0 +1,17 @@
|
||||
# `web-sys`
|
||||
|
||||
The `web-sys` crate provides raw bindings to all of the Web's APIs, and its
|
||||
source lives at `wasm-bindgen/crates/web-sys`.
|
||||
|
||||
The `web-sys` crate is **entirely** mechanically generated inside `build.rs`
|
||||
using `wasm-bindgen`'s WebIDL frontend and the WebIDL interface definitions for
|
||||
Web APIs. This means that `web-sys` isn't always the most ergonomic crate to
|
||||
use, but it's intended to provide verified and correct bindings to the web
|
||||
platform, and then better interfaces can be iterated on crates.io!
|
||||
|
||||
Documentation for the published version of this crate is available on
|
||||
[docs.rs][docsrs] but you can also check out the [master branch
|
||||
documentation][masterdoc] for the crate.
|
||||
|
||||
[docsrs]: https://docs.rs/web-sys
|
||||
[masterdoc]: https://rustwasm.github.io/wasm-bindgen/api/web_sys/
|
||||
23
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/web-sys/logging.md
vendored
Normal file
23
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/web-sys/logging.md
vendored
Normal file
@@ -0,0 +1,23 @@
|
||||
# Logging
|
||||
|
||||
The `wasm_bindgen_webidl` crate (used by `web-sys`'s `build.rs`) uses
|
||||
[`env_logger`][env_logger] for logging, which can be enabled by setting the
|
||||
`RUST_LOG=wasm_bindgen_webidl` environment variable while building the `web-sys`
|
||||
crate.
|
||||
|
||||
Make sure to enable "very verbose" output during `cargo build` to see these logs
|
||||
within `web-sys`'s build script output.
|
||||
|
||||
```sh
|
||||
cd crates/web-sys
|
||||
RUST_LOG=wasm_bindgen_webidl cargo build -vv
|
||||
```
|
||||
|
||||
If `wasm_bindgen_webidl` encounters WebIDL constructs that it doesn't know how
|
||||
to translate into `wasm-bindgen` AST items, it will emit warn-level logs.
|
||||
|
||||
```
|
||||
WARN 2018-07-06T18:21:49Z: wasm_bindgen_webidl: Unsupported WebIDL interface: ...
|
||||
```
|
||||
|
||||
[env_logger]: https://crates.io/crates/env_logger
|
||||
44
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/web-sys/overview.md
vendored
Normal file
44
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/web-sys/overview.md
vendored
Normal file
@@ -0,0 +1,44 @@
|
||||
# `web-sys` Overview
|
||||
|
||||
The `web-sys` crate has this file and directory layout:
|
||||
|
||||
```text
|
||||
.
|
||||
├── build.rs
|
||||
├── Cargo.toml
|
||||
├── README.md
|
||||
├── src
|
||||
│ └── lib.rs
|
||||
└── webidls
|
||||
└── enabled
|
||||
└── ...
|
||||
```
|
||||
|
||||
### `webidls/enabled/*.webidl`
|
||||
|
||||
These are the WebIDL interfaces that we will actually generate bindings for (or
|
||||
at least bindings for *some* of the things defined in these files).
|
||||
|
||||
### `build.rs`
|
||||
|
||||
The `build.rs` invokes `wasm-bindgen`'s WebIDL frontend on all the WebIDL files
|
||||
in `webidls/enabled`. It writes the resulting bindings into the cargo build's
|
||||
out directory.
|
||||
|
||||
### `src/lib.rs`
|
||||
|
||||
The only thing `src/lib.rs` does is include the bindings generated at compile
|
||||
time in `build.rs`. Here is the whole `src/lib.rs` file:
|
||||
|
||||
```rust
|
||||
{{#include ../../../../crates/web-sys/src/lib.rs}}
|
||||
```
|
||||
|
||||
### Cargo features
|
||||
|
||||
When compiled the crate is almost empty by default, which probably isn't what
|
||||
you want! Due to the very large number of APIs, this crate uses features to
|
||||
enable portions of its API to reduce compile times. The list of features in
|
||||
`Cargo.toml` all correspond to types in the generated functions. Enabling a
|
||||
feature enables that type. All methods should indicate what features need to be
|
||||
activated to use the method.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Supporting More Web APIs in `web-sys`
|
||||
|
||||
1. Ensure that the `.webidl` file describing the
|
||||
interface exists somewhere within the `crates/web-sys/webidls/enabled`
|
||||
directory.
|
||||
|
||||
First, check to see whether we have the WebIDL definition file for
|
||||
your API:
|
||||
|
||||
```sh
|
||||
grep -rn MyWebApi crates/web-sys/webidls
|
||||
```
|
||||
|
||||
* If your interface is defined in a `.webidl` file that is inside the
|
||||
`crates/web-sys/webidls/enabled` directory, skip to step (3).
|
||||
|
||||
* If your interface isn't defined in any file yet, find the WebIDL definition
|
||||
in the relevant standard and add it as a new `.webidl` file in
|
||||
`crates/web-sys/webidls/enabled`. Make sure that it is a standard Web API!
|
||||
We don't want to add non-standard APIs to this crate.
|
||||
|
||||
* If your interface is defined in a `.webidl` file within any of the
|
||||
`crates/web-sys/webidls/unavailable_*` directories, you need to move it into
|
||||
`crates/web-sys/webidls/enabled`, e.g.:
|
||||
|
||||
```sh
|
||||
cd crates/web-sys
|
||||
git mv webidls/unavailable_enum_ident/MyWebApi.webidl webidls/enabled/MyWebApi.webidl
|
||||
```
|
||||
|
||||
2. Regenerate the `web-sys` crate auto-generated bindings, which you can do with
|
||||
the following commands:
|
||||
|
||||
```sh
|
||||
cd crates/web-sys
|
||||
cargo run --release --package wasm-bindgen-webidl -- webidls src/features
|
||||
```
|
||||
|
||||
You can then use `git diff` to ensure the bindings look correct.
|
||||
14
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/web-sys/testing.md
vendored
Normal file
14
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/contributing/web-sys/testing.md
vendored
Normal file
@@ -0,0 +1,14 @@
|
||||
# Testing
|
||||
|
||||
You can test the `web-sys` crate by running `cargo test` within the
|
||||
`crates/web-sys` directory in the `wasm-bindgen` repository:
|
||||
|
||||
```sh
|
||||
cd wasm-bindgen/crates/web-sys
|
||||
cargo test --target wasm32-unknown-unknown --all-features
|
||||
```
|
||||
|
||||
The Wasm tests all run within a headless browser. See [the `wasm-bindgen-test`
|
||||
crate's
|
||||
`README.md`](https://github.com/rustwasm/wasm-bindgen/blob/master/crates/test/README.md)
|
||||
for details and configuring which headless browser is used.
|
||||
31
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/2d-canvas.md
vendored
Normal file
31
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/2d-canvas.md
vendored
Normal file
@@ -0,0 +1,31 @@
|
||||
# 2D Canvas
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/canvas/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/canvas
|
||||
|
||||
Drawing a smiley face with the 2D canvas API. This is a port of part of [this
|
||||
MDN
|
||||
tutorial](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_shapes#Moving_the_pen)
|
||||
to `web-sys`.
|
||||
|
||||
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` enables features necessary to query the DOM and work with 2D
|
||||
canvas.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/canvas/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
Gets the `<canvas>` element, creates a 2D rendering context, and draws the
|
||||
smiley face.
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/canvas/src/lib.rs}}
|
||||
```
|
||||
BIN
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/2d-canvas.png
vendored
Normal file
BIN
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/2d-canvas.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.7 KiB |
66
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/add.md
vendored
Normal file
66
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/add.md
vendored
Normal file
@@ -0,0 +1,66 @@
|
||||
# Small wasm files
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/add/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/add
|
||||
|
||||
One of `wasm-bindgen`'s core goals is a pay-only-for-what-you-use philosophy, so
|
||||
if we don't use much then we shouldn't be paying much! As a result
|
||||
`#[wasm_bindgen]` can generate super-small executables
|
||||
|
||||
Currently this code...
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/add/src/lib.rs}}
|
||||
```
|
||||
|
||||
generates a 710 byte wasm binary:
|
||||
|
||||
```
|
||||
$ ls -l add_bg.wasm
|
||||
-rw-rw-r-- 1 alex alex 710 Sep 19 17:32 add_bg.wasm
|
||||
```
|
||||
|
||||
If you run [wasm-opt], a C++ tool for optimize WebAssembly, you can make it
|
||||
even smaller too!
|
||||
|
||||
```
|
||||
$ wasm-opt -Os add_bg.wasm -o add.wasm
|
||||
$ ls -l add.wasm
|
||||
-rw-rw-r-- 1 alex alex 172 Sep 19 17:33 add.wasm
|
||||
```
|
||||
|
||||
And sure enough, using the [wasm2wat] tool it's quite small!
|
||||
|
||||
```
|
||||
$ wasm2wat add.wasm
|
||||
(module
|
||||
(type (;0;) (func (param i32 i32) (result i32)))
|
||||
(func (;0;) (type 0) (param i32 i32) (result i32)
|
||||
get_local 1
|
||||
get_local 0
|
||||
i32.add)
|
||||
(table (;0;) 1 1 anyfunc)
|
||||
(memory (;0;) 17)
|
||||
(global (;0;) i32 (i32.const 1049118))
|
||||
(global (;1;) i32 (i32.const 1049118))
|
||||
(export "memory" (memory 0))
|
||||
(export "__indirect_function_table" (table 0))
|
||||
(export "__heap_base" (global 0))
|
||||
(export "__data_end" (global 1))
|
||||
(export "add" (func 0))
|
||||
(data (i32.const 1049096) "invalid malloc request"))
|
||||
```
|
||||
|
||||
Also don't forget to compile in release mode for the smallest binaries! For
|
||||
larger applications you'll likely also want to turn on LTO to generate the
|
||||
smallest binaries:
|
||||
|
||||
```toml
|
||||
[profile.release]
|
||||
lto = true
|
||||
```
|
||||
|
||||
[wasm2wat]: https://github.com/webassembly/wabt
|
||||
[wasm-opt]: https://github.com/webassembly/binaryen
|
||||
31
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/char.md
vendored
Normal file
31
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/char.md
vendored
Normal file
@@ -0,0 +1,31 @@
|
||||
# Working with the `char` type
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/char/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/char
|
||||
|
||||
The `#[wasm_bindgen]` macro will convert the rust `char` type to a single
|
||||
code-point js `string`, and this example shows how to work with this.
|
||||
|
||||
Opening this example should display a single counter with a random character
|
||||
for it's `key` and 0 for its `count`. You can click the `+` button to increase a
|
||||
counter's count. By clicking on the "add counter" button you should see a new
|
||||
counter added to the list with a different random character for it's `key`.
|
||||
|
||||
Under the hood javascript is choosing a random character from an Array of
|
||||
characters and passing that to the rust Counter struct's constructor so the
|
||||
character you are seeing on the page has made the full round trip from js to
|
||||
rust and back to js.
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/char/src/lib.rs}}
|
||||
```
|
||||
|
||||
## `index.js`
|
||||
|
||||
```js
|
||||
{{#include ../../../examples/char/index.js}}
|
||||
```
|
||||
16
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/closures.md
vendored
Normal file
16
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/closures.md
vendored
Normal file
@@ -0,0 +1,16 @@
|
||||
# web-sys: Closures
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/closures/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/closures
|
||||
|
||||
One of the features of `#[wasm_bindgen]` is that you can pass closures defined
|
||||
in Rust off to JS. This can be a bit tricky at times, though, so the example
|
||||
here shows how to interact with some standard web APIs with closures.
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/closures/src/lib.rs}}
|
||||
```
|
||||
15
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/console-log.md
vendored
Normal file
15
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/console-log.md
vendored
Normal file
@@ -0,0 +1,15 @@
|
||||
# `console.log`
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/console_log/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/console_log
|
||||
|
||||
This example shows off how to use `console.log` in a variety of ways, all the
|
||||
way from bare-bones usage to a `println!`-like macro with `web_sys`.
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/console_log/src/lib.rs}}
|
||||
```
|
||||
26
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/dom.md
vendored
Normal file
26
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/dom.md
vendored
Normal file
@@ -0,0 +1,26 @@
|
||||
# web-sys: DOM hello world
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/dom/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/dom
|
||||
|
||||
Using `web-sys` we're able to interact with all the standard web platform
|
||||
methods, including those of the DOM! Here we take a look at a simple "Hello,
|
||||
world!" which manufactures a DOM element in Rust, customizes it, and then
|
||||
appends it to the page.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
You can see here how we depend on `web-sys` and activate associated features to
|
||||
enable all the various APIs:
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/dom/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/dom/src/lib.rs}}
|
||||
```
|
||||
24
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/fetch.md
vendored
Normal file
24
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/fetch.md
vendored
Normal file
@@ -0,0 +1,24 @@
|
||||
# The `fetch` API
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/fetch/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/fetch
|
||||
|
||||
This example uses the `fetch` API to make an HTTP request to the GitHub API and
|
||||
then parses the resulting JSON.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` enables a number of features related to the `fetch` API and
|
||||
types used: `Headers`, `Request`, etc.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/fetch/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/fetch/src/lib.rs}}
|
||||
```
|
||||
59
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/hello-world.md
vendored
Normal file
59
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/hello-world.md
vendored
Normal file
@@ -0,0 +1,59 @@
|
||||
# Hello, World!
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/hello_world/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/hello_world
|
||||
|
||||
This is the "Hello, world!" example of `#[wasm_bindgen]` showing how to set up
|
||||
a project, export a function to JS, call it from JS, and then call the `alert`
|
||||
function in Rust.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` lists the `wasm-bindgen` crate as a dependency.
|
||||
|
||||
Also of note is the `crate-type = ["cdylib"]` which is largely used for wasm
|
||||
final artifacts today.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/hello_world/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
Here we define our Rust entry point along with calling the `alert` function.
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/hello_world/src/lib.rs}}
|
||||
```
|
||||
|
||||
## `index.js`
|
||||
|
||||
Our JS entry point is quite small!
|
||||
|
||||
```js
|
||||
{{#include ../../../examples/hello_world/index.js}}
|
||||
```
|
||||
|
||||
## Webpack-specific files
|
||||
|
||||
> **Note**: Webpack is required for this example, and if you're interested
|
||||
> in options that don't use a JS bundler [see other examples][wab].
|
||||
|
||||
[wab]: without-a-bundler.html
|
||||
|
||||
And finally here's the Webpack configuration and `package.json` for this
|
||||
project:
|
||||
|
||||
**webpack.config.js**
|
||||
|
||||
```js
|
||||
{{#include ../../../examples/hello_world/webpack.config.js}}
|
||||
```
|
||||
|
||||
**package.json**
|
||||
|
||||
```json
|
||||
{{#include ../../../examples/hello_world/package.json}}
|
||||
```
|
||||
27
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/import-js.md
vendored
Normal file
27
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/import-js.md
vendored
Normal file
@@ -0,0 +1,27 @@
|
||||
# Importing non-browser JS
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/import_js/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/import_js
|
||||
|
||||
The `#[wasm_bindgen]` attribute can be used on `extern "C" { .. }` blocks to import
|
||||
functionality from JS. This is how the `js-sys` and the `web-sys` crates are
|
||||
built, but you can also use it in your own crate!
|
||||
|
||||
For example if you're working with this JS file:
|
||||
|
||||
```js
|
||||
// defined-in-js.js
|
||||
{{#include ../../../examples/import_js/crate/defined-in-js.js}}
|
||||
```
|
||||
|
||||
you can use it in Rust with:
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/import_js/crate/src/lib.rs}}
|
||||
```
|
||||
|
||||
You can also [explore the full list of ways to configure imports][attr]
|
||||
|
||||
[attr]: ../reference/attributes/on-js-imports/index.html
|
||||
24
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/index.md
vendored
Normal file
24
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/index.md
vendored
Normal file
@@ -0,0 +1,24 @@
|
||||
# Examples of using `wasm-bindgen`, `js-sys`, and `web-sys`
|
||||
|
||||
This subsection contains examples of using the `wasm-bindgen`, `js-sys`, and
|
||||
`web-sys` crates. Each example should have more information about what it's
|
||||
doing.
|
||||
|
||||
These examples all assume familiarity with `wasm-bindgen`, `wasm-pack`, and
|
||||
building a Rust and WebAssembly project. If you're unfamiliar with these check
|
||||
out the [Game of Life tutorial][gol] or [wasm pack tutorials][wpt] to help you
|
||||
get started.
|
||||
|
||||
The source code for all examples can also be [found online][code] to download
|
||||
and run locally. Most examples are configured with Webpack/`wasm-pack` and can
|
||||
be built with `npm run serve`. Other examples which don't use Webpack are
|
||||
accompanied with instructions or a `build.sh` showing how to build it.
|
||||
|
||||
Note that most examples currently use Webpack to assemble the final output
|
||||
artifact, but this is not required! You can review the [deployment
|
||||
documentation][deploy] for other options of how to deploy Rust and WebAssembly.
|
||||
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples
|
||||
[gol]: https://rustwasm.github.io/docs/book/
|
||||
[deploy]: ../reference/deployment.html
|
||||
[wpt]: https://rustwasm.github.io/docs/wasm-pack/tutorials/index.html
|
||||
25
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/julia.md
vendored
Normal file
25
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/julia.md
vendored
Normal file
@@ -0,0 +1,25 @@
|
||||
# Julia Set
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/julia_set/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/julia_set
|
||||
|
||||
While not showing off a lot of `web_sys` API surface area, this example shows a
|
||||
neat fractal that you can make!
|
||||
|
||||
## `index.js`
|
||||
|
||||
A small bit of glue is added for this example
|
||||
|
||||
```js
|
||||
{{#include ../../../examples/julia_set/index.js}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
The bulk of the logic is in the generation of the fractal
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/julia_set/src/lib.rs}}
|
||||
```
|
||||
26
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/paint.md
vendored
Normal file
26
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/paint.md
vendored
Normal file
@@ -0,0 +1,26 @@
|
||||
# Paint Example
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/paint/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/paint
|
||||
|
||||
A simple painting program.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` enables features necessary to work with the DOM, events and
|
||||
2D canvas.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/paint/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
Creates the `<canvas>` element, applies a CSS style to it, adds it to the document,
|
||||
get a 2D rendering context and adds listeners for mouse events.
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/paint/src/lib.rs}}
|
||||
```
|
||||
16
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/performance.md
vendored
Normal file
16
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/performance.md
vendored
Normal file
@@ -0,0 +1,16 @@
|
||||
# web-sys: `performance.now`
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/performance/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/performance
|
||||
|
||||
Want to profile some Rust code in the browser? No problem! You can use the
|
||||
`performance.now()` API and friends to get timing information to see how long
|
||||
things take.
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/performance/src/lib.rs}}
|
||||
```
|
||||
130
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/raytrace.md
vendored
Normal file
130
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/raytrace.md
vendored
Normal file
@@ -0,0 +1,130 @@
|
||||
# Parallel Raytracing
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://wasm-bindgen.netlify.app/exbuild/raytrace-parallel/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/raytrace-parallel
|
||||
|
||||
This is an example of using threads with WebAssembly, Rust, and `wasm-bindgen`,
|
||||
culminating in a parallel raytracer demo. There's a number of moving pieces to
|
||||
this demo and it's unfortunately not the easiest thing to wrangle, but it's
|
||||
hoped that this'll give you a bit of a taste of what it's like to use threads
|
||||
and wasm with Rust on the web.
|
||||
|
||||
### Building the demo
|
||||
|
||||
One of the major gotchas with threaded WebAssembly is that Rust does not ship a
|
||||
precompiled target (e.g. standard library) which has threading support enabled.
|
||||
This means that you'll need to recompile the standard library with the
|
||||
appropriate rustc flags, namely
|
||||
`-C target-feature=+atomics,+bulk-memory,+mutable-globals`.
|
||||
Note that this requires a nightly Rust toolchain.
|
||||
|
||||
To do this you can use the `RUSTFLAGS` environment variable that Cargo reads:
|
||||
|
||||
```sh
|
||||
export RUSTFLAGS='-C target-feature=+atomics,+bulk-memory,+mutable-globals'
|
||||
```
|
||||
|
||||
To recompile the standard library it's recommended to use Cargo's
|
||||
[`-Zbuild-std`](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std)
|
||||
feature:
|
||||
|
||||
```sh
|
||||
cargo build --target wasm32-unknown-unknown -Z build-std=panic_abort,std
|
||||
```
|
||||
|
||||
Note that you can also configure this via `.cargo/config.toml`:
|
||||
|
||||
```toml
|
||||
[unstable]
|
||||
build-std = ['std', 'panic_abort']
|
||||
|
||||
[build]
|
||||
target = "wasm32-unknown-unknown"
|
||||
rustflags = '-Ctarget-feature=+atomics,+bulk-memory,+mutable-globals'
|
||||
```
|
||||
|
||||
After this `cargo build` should produce a WebAssembly file with threading
|
||||
enabled, and the standard library will be appropriately compiled as well.
|
||||
|
||||
The final step in this is to run `wasm-bindgen` as usual, and `wasm-bindgen`
|
||||
needs no extra configuration to work with threads. You can continue to run it
|
||||
through `wasm-pack`, for example.
|
||||
|
||||
### Running the demo
|
||||
|
||||
Currently it's required to use the `--target no-modules` or `--target web` flag
|
||||
with `wasm-bindgen` to run threaded code. This is because the WebAssembly file
|
||||
imports memory instead of exporting it, so we need to hook initialization of the
|
||||
wasm module at this time to provide the appropriate memory object. This demo
|
||||
uses `--target no-modules`, because Firefox does not support modules in workers.
|
||||
|
||||
With `--target no-modules` you'll be able to use `importScripts` inside of each
|
||||
web worker to import the shim JS generated by `wasm-bindgen` as well as calling
|
||||
the `wasm_bindgen` initialization function with the shared memory instance from
|
||||
the main thread. The expected usage is that WebAssembly on the main thread will
|
||||
post its memory object to all other threads to get instantiated with.
|
||||
|
||||
### Caveats
|
||||
|
||||
Unfortunately at this time running wasm on the web with threads has a number of
|
||||
caveats, although some are specific to just `wasm-bindgen`. These are some
|
||||
pieces to consider and watch out for, although we're always looking for
|
||||
improvements to be made so if you have an idea please file an issue!
|
||||
|
||||
* The main thread in a browser cannot block. This means that if you run
|
||||
WebAssembly code on the main thread you can *never* block, meaning you can't
|
||||
do so much as acquire a mutex. This is an extremely difficult limitation to
|
||||
work with on the web, although one workaround is to run wasm exclusively in
|
||||
web workers and run JS on the main thread. It is possible to run the same wasm
|
||||
across all threads, but you need to be extremely vigilant about
|
||||
synchronization with the main thread.
|
||||
|
||||
* Setting up a threaded environment is a bit wonky and doesn't feel smooth
|
||||
today. For example `--target bundler` is unsupported and very specific shims
|
||||
are required on both the main thread and worker threads. These are possible to
|
||||
work with but are somewhat brittle since there's no standard way to spin up
|
||||
web workers as wasm threads.
|
||||
|
||||
* There is no standard notion of a "thread". For example the standard library
|
||||
has no viable route to implement the `std::thread` module. As a consequence
|
||||
there is no concept of thread exit and TLS destructors will never run.
|
||||
We do expose a helper, `__wbindgen_thread_destroy`, that deallocates
|
||||
the thread stack and TLS. If you invoke it, it *must* be the last function
|
||||
you invoke from the wasm module for a given thread.
|
||||
|
||||
* Any thread launched after the first one _might attempt to block_ implicitly
|
||||
in its initialization routine. This is a constraint introduced by the way
|
||||
we set up the space for thread stacks and TLS. This means that if you attempt
|
||||
to run a wasm module in the main thread _after_ you are already running it
|
||||
in a worker, it might fail.
|
||||
|
||||
* Web Workers executing WebAssembly code cannot receive events from JS. A Web
|
||||
Worker has to fully return back to the browser (and ideally should do so
|
||||
occasionally) to receive JS messages and such. This means that common
|
||||
paradigms like a rayon thread pool do not apply straightforward-ly to the web.
|
||||
The intention of the web is that all long-term blocking happens in the browser
|
||||
itself, not in each thread, but many crates in the ecosystem leveraging
|
||||
threading are not necessarily engineered this way.
|
||||
|
||||
These caveats are all largely inherited from the web platform itself, and
|
||||
they're important to consider when designing an application for threading. It's
|
||||
highly unlikely that you can pull a crate off the shelf and "just use it" due to
|
||||
these limitations. You'll need to be sure to carefully plan ahead and ensure
|
||||
that gotchas such as these don't cause issues in the future. As mentioned before
|
||||
though we're always trying to actively develop this support so if folks have
|
||||
ideas about how to improve, or if web standards change, we'll try to update this
|
||||
documentation!
|
||||
|
||||
### Browser Requirements
|
||||
|
||||
This demo should work in the latest Firefox and Chrome versions at this time,
|
||||
and other browsers are likely to follow suit. Note that threads and
|
||||
`SharedArrayBuffer` require HTTP headers to be set to work correctly. For more
|
||||
information see the [documentation on
|
||||
MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer)
|
||||
under "Security requirements" as well as [Firefox's rollout blog
|
||||
post](https://hacks.mozilla.org/2020/07/safely-reviving-shared-memory/). This
|
||||
means that during local development you'll need to configure your web server
|
||||
appropriately or enable a workaround in your browser.
|
||||
26
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/request-animation-frame.md
vendored
Normal file
26
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/request-animation-frame.md
vendored
Normal file
@@ -0,0 +1,26 @@
|
||||
# `web-sys`: A `requestAnimationFrame` Loop
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/request-animation-frame/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/request-animation-frame
|
||||
|
||||
This is an example of a `requestAnimationFrame` loop using the `web-sys` crate!
|
||||
It renders a count of how many times a `requestAnimationFrame` callback has been
|
||||
invoked and then it breaks out of the `requestAnimationFrame` loop after 300
|
||||
iterations.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
You can see here how we depend on `web-sys` and activate associated features to
|
||||
enable all the various APIs:
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/request-animation-frame/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/request-animation-frame/src/lib.rs}}
|
||||
```
|
||||
33
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/synchronous-instantiation.md
vendored
Normal file
33
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/synchronous-instantiation.md
vendored
Normal file
@@ -0,0 +1,33 @@
|
||||
# Synchronous Instantiation
|
||||
|
||||
[View full source code][code]
|
||||
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/synchronous-instantiation
|
||||
|
||||
This example shows how to synchronously initialize a WebAssembly module as opposed to [asynchronously][without-bundler]. In most cases, the default way of asynchronously initializing a module will suffice. However, there might be use cases where you'd like to lazy load a module on demand and synchronously compile and instantiate it. Note that this only works off the main thread and since compilation and instantiation of large modules can be expensive you should only use this method if it's absolutely required in your use case. Otherwise you should use the [default method][without-bundler].
|
||||
|
||||
For this deployment strategy bundlers like Webpack are not required. For more information on deployment see the [dedicated
|
||||
documentation][deployment].
|
||||
|
||||
First let's take a look at our tiny lib:
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/synchronous-instantiation/src/lib.rs}}
|
||||
```
|
||||
|
||||
Next, let's have a look at the `index.html`:
|
||||
|
||||
```html
|
||||
{{#include ../../../examples/synchronous-instantiation/index.html}}
|
||||
```
|
||||
|
||||
Otherwise the rest of the magic happens in `worker.js`:
|
||||
|
||||
```js
|
||||
{{#include ../../../examples/synchronous-instantiation/worker.js}}
|
||||
```
|
||||
|
||||
And that's it! Be sure to read up on the [deployment options][deployment] to see what it means to deploy without a bundler.
|
||||
|
||||
[deployment]: ../reference/deployment.html
|
||||
[without-bundler]: ./without-a-bundler.html
|
||||
25
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/todomvc.md
vendored
Normal file
25
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/todomvc.md
vendored
Normal file
@@ -0,0 +1,25 @@
|
||||
# TODO MVC using wasm-bingen and web-sys
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/todomvc/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/todomvc
|
||||
[element]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/todomvc/src/element.rs
|
||||
[scheduler]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/todomvc/src/scheduler.rs
|
||||
|
||||
[wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) and [web-sys](https://rustwasm.github.io/wasm-bindgen/api/web_sys/) coded [TODO MVC](http://todomvc.com/)
|
||||
|
||||
The code was rewritten from the [ES6 version](http://todomvc.com/examples/vanilla-es6/).
|
||||
|
||||
The core differences are:
|
||||
- Having an [Element wrapper][element] that takes care of dyn and into refs in web-sys,
|
||||
- A [Scheduler][scheduler] that allows Controller and View to communicate to each other by emulating something similar to the JS event loop.
|
||||
|
||||
|
||||
## Size
|
||||
|
||||
The size of the project hasn't undergone much work to make it optimised yet.
|
||||
|
||||
- ~96kb release build
|
||||
- ~76kb optimised with binaryen
|
||||
- ~28kb brotli compressed
|
||||
45
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/wasm-audio-worklet.md
vendored
Normal file
45
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/wasm-audio-worklet.md
vendored
Normal file
@@ -0,0 +1,45 @@
|
||||
# WASM audio worklet
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://wasm-bindgen.netlify.app/exbuild/wasm-audio-worklet/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/wasm-audio-worklet
|
||||
|
||||
This is an example of using threads inside specific worklets with WebAssembly,
|
||||
Rust, and `wasm-bindgen`, culminating in an oscillator demo. This demo should
|
||||
complement the [parallel-raytrace][parallel-raytrace] example by
|
||||
demonstrating an alternative approach using ES modules with on-the-fly module
|
||||
creation.
|
||||
|
||||
[parallel-raytrace]: https://rustwasm.github.io/docs/wasm-bindgen/examples/raytrace.html
|
||||
|
||||
### Building the demo
|
||||
|
||||
One of the major gotchas with threaded WebAssembly is that Rust does not ship a
|
||||
precompiled target (e.g. standard library) which has threading support enabled.
|
||||
This means that you'll need to recompile the standard library with the
|
||||
appropriate rustc flags, namely
|
||||
`-C target-feature=+atomics,+bulk-memory,+mutable-globals`.
|
||||
Note that this requires a nightly Rust toolchain. See the [more detailed
|
||||
instructions][build] of the parallel-raytrace example.
|
||||
|
||||
[build]: https://rustwasm.github.io/docs/wasm-bindgen/examples/raytrace.html#building-the-demo
|
||||
|
||||
### Caveats
|
||||
|
||||
This example shares most of its [caveats][caveats] with the parallel-raytrace
|
||||
example. However, it tries to encapsulate worklet creation in a Rust module, so
|
||||
the application developer does not need to maintain custom JS code.
|
||||
|
||||
[caveats]: https://rustwasm.github.io/docs/wasm-bindgen/examples/raytrace.html#caveats
|
||||
|
||||
### Browser Requirements
|
||||
|
||||
This demo should work in the latest Chrome and Safari versions at this time.
|
||||
Firefox [does not support][firefox-worklet-import] imports in worklet modules,
|
||||
which are difficult to avoid in this example, as `importScripts` is unavailable
|
||||
in worklets. Note that this example requires HTTP headers to be set like in
|
||||
[parallel-raytrace][headers].
|
||||
|
||||
[firefox-worklet-import]: https://bugzilla.mozilla.org/show_bug.cgi?id=1572644
|
||||
[headers]: https://rustwasm.github.io/docs/wasm-bindgen/examples/raytrace.html#browser-requirements
|
||||
15
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/wasm-in-wasm.md
vendored
Normal file
15
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/wasm-in-wasm.md
vendored
Normal file
@@ -0,0 +1,15 @@
|
||||
# js-sys: WebAssembly in WebAssembly
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/wasm-in-wasm/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/wasm-in-wasm
|
||||
|
||||
Using the `js-sys` crate we can get pretty meta and instantiate `WebAssembly`
|
||||
modules from inside `WebAssembly` modules!
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/wasm-in-wasm/src/lib.rs}}
|
||||
```
|
||||
71
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/wasm-in-web-worker.md
vendored
Normal file
71
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/wasm-in-web-worker.md
vendored
Normal file
@@ -0,0 +1,71 @@
|
||||
# WASM in Web Worker
|
||||
|
||||
[View full source code][code]
|
||||
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/wasm-in-web-worker
|
||||
|
||||
A simple example of parallel execution by spawning a web worker with `web_sys`,
|
||||
loading WASM code in the web worker and interacting between the main thread and
|
||||
the worker.
|
||||
|
||||
## Building & compatibility
|
||||
|
||||
At the time of this writing, only Chrome supports modules in web workers, e.g.
|
||||
Firefox does not. To have compatibility across browsers, the whole example is
|
||||
set up without relying on ES modules as target. Therefore we have to build
|
||||
with `--target no-modules`. The full command can be found in `build.sh`.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` enables features necessary to work with the DOM, log output to
|
||||
the JS console, creating a worker and reacting to message events.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/wasm-in-web-worker/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
Creates a struct `NumberEval` with methods to act as stateful object in the
|
||||
worker and function `startup` to be launched in the main thread. Also includes
|
||||
internal helper functions `setup_input_oninput_callback` to attach a
|
||||
`wasm_bindgen::Closure` as callback to the `oninput` event of the input field
|
||||
and `get_on_msg_callback` to create a `wasm_bindgen::Closure` which is triggered
|
||||
when the worker returns a message.
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/wasm-in-web-worker/src/lib.rs}}
|
||||
```
|
||||
|
||||
## `index.html`
|
||||
|
||||
Includes the input element `#inputNumber` to type a number into and a HTML
|
||||
element `#resultField` were the result of the evaluation even/odd is written to.
|
||||
Since we require to build with `--target no-modules` to be able to load WASM
|
||||
code in in the worker across browsers, the `index.html` also includes loading
|
||||
both `wasm_in_web_worker.js` and `index.js`.
|
||||
|
||||
```html
|
||||
{{#include ../../../examples/wasm-in-web-worker/index.html}}
|
||||
```
|
||||
|
||||
## `index.js`
|
||||
|
||||
Loads our WASM file asynchronously and calls the entry point `startup` of the
|
||||
main thread which will create a worker.
|
||||
|
||||
```js
|
||||
{{#include ../../../examples/wasm-in-web-worker/index.js}}
|
||||
```
|
||||
|
||||
## `worker.js`
|
||||
|
||||
Loads our WASM file by first importing `wasm_bindgen` via
|
||||
`importScripts('./pkg/wasm_in_web_worker.js')` and then awaiting the Promise
|
||||
returned by `wasm_bindgen(...)`. Creates a new object to do the background
|
||||
calculation and bind a method of the object to the `onmessage` callback of the
|
||||
worker.
|
||||
|
||||
```js
|
||||
{{#include ../../../examples/wasm-in-web-worker/worker.js}}
|
||||
```
|
||||
38
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/wasm2js.md
vendored
Normal file
38
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/wasm2js.md
vendored
Normal file
@@ -0,0 +1,38 @@
|
||||
# Converting WebAssembly to JS
|
||||
|
||||
[View full source code][code]
|
||||
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/wasm2js
|
||||
|
||||
Not all browsers have support for `WebAssembly` at this time (although all major
|
||||
ones do). If you'd like to support older browsers, you probably want a method
|
||||
that doesn't involve keeping two codebases in sync!
|
||||
|
||||
Thankfully there's a tool from [binaryen] called `wasm2js` to convert a wasm
|
||||
file to JS. This JS file, if successfully produced, is equivalent to the wasm
|
||||
file (albeit a little bit larger and slower), and can be loaded into practically
|
||||
any browser.
|
||||
|
||||
This example is relatively simple (cribbing from the [`console.log`
|
||||
example](console-log.md)):
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/wasm2js/src/lib.rs}}
|
||||
```
|
||||
|
||||
The real magic happens when you actually build the app. Just after
|
||||
`wasm-bindgen` we see here how we execute `wasm2js` in our build script:
|
||||
|
||||
```sh
|
||||
{{#include ../../../examples/wasm2js/build.sh}}
|
||||
```
|
||||
|
||||
Note that the `wasm2js` tool is still pretty early days so there's likely to be
|
||||
a number of bugs to run into or work around. If any are encountered though
|
||||
please feel free to report them upstream!
|
||||
|
||||
Also note that eventually this will ideally be automatically done by your
|
||||
bundler and no action would be needed from you to work in older browsers via
|
||||
`wasm2js`!
|
||||
|
||||
[binaryen]: https://github.com/WebAssembly/binaryen
|
||||
18
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/weather_report.md
vendored
Normal file
18
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/weather_report.md
vendored
Normal file
@@ -0,0 +1,18 @@
|
||||
# web-sys: Weather report
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/weather_report/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/weather_report
|
||||
|
||||
This example makes an HTTP request to [OpenWeather API](https://openweathermap.org/),
|
||||
parses response in JSON and render UI from that JSON. It also shows the usage of
|
||||
`spawn_local` function for handling asynchronous tasks.
|
||||
|
||||
Please add your api key in *get_response()* before running this application.
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/weather_report/src/lib.rs}}
|
||||
```
|
||||
38
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/web-audio.md
vendored
Normal file
38
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/web-audio.md
vendored
Normal file
@@ -0,0 +1,38 @@
|
||||
# WebAudio
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/webaudio/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/webaudio
|
||||
|
||||
This example creates an [FM
|
||||
oscillator](https://en.wikipedia.org/wiki/Frequency_modulation_synthesis) using
|
||||
the [WebAudio
|
||||
API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) and
|
||||
`web-sys`.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` enables the types needed to use the relevant bits of the
|
||||
WebAudio API.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/webaudio/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
The Rust code implements the FM oscillator.
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/webaudio/src/lib.rs}}
|
||||
```
|
||||
|
||||
## `index.js`
|
||||
|
||||
A small bit of JavaScript glues the rust module to input widgets and translates
|
||||
events into calls into wasm code.
|
||||
|
||||
```js
|
||||
{{#include ../../../examples/webaudio/index.js}}
|
||||
```
|
||||
27
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/webgl.md
vendored
Normal file
27
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/webgl.md
vendored
Normal file
@@ -0,0 +1,27 @@
|
||||
# WebGL Example
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/webgl/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/webgl
|
||||
|
||||
This example draws a triangle to the screen using the WebGL API.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` enables features necessary to obtain and use a WebGL
|
||||
rendering context.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/webgl/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
This source file handles all of the necessary logic to obtain a rendering
|
||||
context, compile shaders, fill a buffer with vertex coordinates, and draw a
|
||||
triangle to the screen.
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/webgl/src/lib.rs}}
|
||||
```
|
||||
25
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/webrtc_datachannel.md
vendored
Normal file
25
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/webrtc_datachannel.md
vendored
Normal file
@@ -0,0 +1,25 @@
|
||||
# WebRTC DataChannel Example
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/webrtc_datachannel/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/webrtc_datachannel/
|
||||
|
||||
This example creates 2 peer connections and 2 data channels in single browser tab.
|
||||
Send ping/pong between `peer1.dc` and `peer2.dc`.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` enables features necessary to use WebRTC DataChannel and its negotiation.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/webrtc_datachannel/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
The Rust code connects WebRTC data channel.
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/webrtc_datachannel/src/lib.rs}}
|
||||
```
|
||||
29
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/websockets.md
vendored
Normal file
29
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/websockets.md
vendored
Normal file
@@ -0,0 +1,29 @@
|
||||
# WebSockets Example
|
||||
|
||||
[View full source code][code] or [view the compiled example online][online]
|
||||
|
||||
[online]: https://rustwasm.github.io/wasm-bindgen/exbuild/websockets/
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/websockets/
|
||||
|
||||
This example connects to an echo server on `wss://echo.websocket.org`,
|
||||
sends a `ping` message, and receives the response.
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
The `Cargo.toml` enables features necessary to create a `WebSocket` object and
|
||||
to access events such as `MessageEvent` or `ErrorEvent`.
|
||||
|
||||
```toml
|
||||
{{#include ../../../examples/websockets/Cargo.toml}}
|
||||
```
|
||||
|
||||
## `src/lib.rs`
|
||||
|
||||
This code shows the basic steps required to work with a `WebSocket`.
|
||||
At first it opens the connection, then subscribes to events `onmessage`, `onerror`, `onopen`.
|
||||
After the socket is opened it sends a `ping` message, receives an echoed response
|
||||
and prints it to the browser console.
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/websockets/src/lib.rs}}
|
||||
```
|
||||
66
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/without-a-bundler.md
vendored
Normal file
66
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/examples/without-a-bundler.md
vendored
Normal file
@@ -0,0 +1,66 @@
|
||||
# Without a Bundler
|
||||
|
||||
[View full source code][code]
|
||||
|
||||
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler
|
||||
|
||||
This example shows how the `--target web` flag can be used load code in a
|
||||
browser directly. For this deployment strategy bundlers like Webpack are not
|
||||
required. For more information on deployment see the [dedicated
|
||||
documentation][deployment].
|
||||
|
||||
First, you'll need to add `web-sys` to your Cargo.toml.
|
||||
```toml
|
||||
[dependencies.web-sys]
|
||||
version = "0.3.4"
|
||||
features = [
|
||||
'Document',
|
||||
'Element',
|
||||
'HtmlElement',
|
||||
'Node',
|
||||
'Window',
|
||||
]
|
||||
```
|
||||
|
||||
Then, let's take a look at the code and see how when we're using `--target web`
|
||||
we're not actually losing any functionality!
|
||||
|
||||
```rust
|
||||
{{#include ../../../examples/without-a-bundler/src/lib.rs}}
|
||||
```
|
||||
|
||||
Otherwise the rest of the deployment magic happens in `index.html`:
|
||||
|
||||
```html
|
||||
{{#include ../../../examples/without-a-bundler/index.html}}
|
||||
```
|
||||
|
||||
And that's it! Be sure to read up on the [deployment options][deployment] to see
|
||||
what it means to deploy without a bundler.
|
||||
|
||||
[deployment]: ../reference/deployment.html
|
||||
|
||||
## Using the older `--target no-modules`
|
||||
|
||||
[View full source code][code-no-modules]
|
||||
|
||||
[code-no-modules]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler-no-modules
|
||||
|
||||
The older version of using `wasm-bindgen` without a bundler is to use the
|
||||
`--target no-modules` flag to the `wasm-bindgen` CLI.
|
||||
|
||||
While similar to the newer `--target web`, the `--target no-modules` flag has a
|
||||
few caveats:
|
||||
|
||||
* It does not support [local JS snippets][snippets]
|
||||
* It does not generate an ES module
|
||||
|
||||
With that in mind the main difference is how the wasm/JS code is loaded, and
|
||||
here's an example of loading the output of `wasm-pack` for the same module as
|
||||
above.
|
||||
|
||||
```html
|
||||
{{#include ../../../examples/without-a-bundler-no-modules/index.html}}
|
||||
```
|
||||
|
||||
[snippets]: ../reference/js-snippets.html
|
||||
43
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/introduction.md
vendored
Normal file
43
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/introduction.md
vendored
Normal file
@@ -0,0 +1,43 @@
|
||||
# Introduction
|
||||
|
||||
This book is about `wasm-bindgen`, a Rust library and CLI tool that facilitate
|
||||
high-level interactions between wasm modules and JavaScript. The `wasm-bindgen`
|
||||
tool and crate are only one part of the [Rust and WebAssembly
|
||||
ecosystem][rustwasm]. If you're not familiar already with `wasm-bindgen` it's
|
||||
recommended to start by reading the [Game of Life tutorial][gol]. If you're
|
||||
curious about `wasm-pack`, you can find that [documentation here][wasm-pack].
|
||||
|
||||
The `wasm-bindgen` tool is sort of half polyfill for features like the [host
|
||||
bindings proposal][host] and half features for empowering high-level
|
||||
interactions between JS and wasm-compiled code (currently mostly from Rust).
|
||||
More specifically this project allows JS/wasm to communicate with strings, JS
|
||||
objects, classes, etc, as opposed to purely integers and floats. Using
|
||||
`wasm-bindgen` for example you can define a JS class in Rust or take a string
|
||||
from JS or return one. The functionality is growing as well!
|
||||
|
||||
Currently this tool is Rust-focused but the underlying foundation is
|
||||
language-independent, and it's hoping that over time as this tool stabilizes
|
||||
that it can be used for languages like C/C++!
|
||||
|
||||
Notable features of this project includes:
|
||||
|
||||
* Importing JS functionality in to Rust such as [DOM manipulation][dom-ex],
|
||||
[console logging][console-log], or [performance monitoring][perf-ex].
|
||||
* Exporting Rust functionality to JS such as classes, functions, etc.
|
||||
* Working with rich types like strings, numbers, classes, closures, and objects
|
||||
rather than simply `u32` and floats.
|
||||
* Automatically generating TypeScript bindings for Rust code being consumed by
|
||||
JS.
|
||||
|
||||
With the addition of [`wasm-pack`][wasm-pack] you can run the gamut from running Rust on
|
||||
the web locally, publishing it as part of a larger application, or even
|
||||
publishing Rust-compiled-to-WebAssembly on NPM!
|
||||
|
||||
[host]: https://github.com/WebAssembly/host-bindings
|
||||
[dom-ex]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/dom
|
||||
[console-log]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/console_log
|
||||
[perf-ex]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/performance
|
||||
[hello-online]: https://webassembly.studio/?f=gzubao6tg3
|
||||
[rustwasm]: https://rustwasm.github.io/
|
||||
[gol]: https://rustwasm.github.io/docs/book/
|
||||
[wasm-pack]: https://rustwasm.github.io/docs/wasm-pack/
|
||||
@@ -0,0 +1,82 @@
|
||||
# Accessing Properties of Untyped JavaScript Values
|
||||
|
||||
To read and write arbitrary properties from any untyped JavaScript value
|
||||
regardless if it is an `instanceof` some JavaScript class or not, use [the
|
||||
`js_sys::Reflect` APIs][js-sys-reflect]. These APIs are bindings to the
|
||||
[JavaScript builtin `Reflect` object][mdn-reflect] and its methods.
|
||||
|
||||
You might also benefit from [using duck-typed
|
||||
interfaces](./working-with-duck-typed-interfaces.html) instead of working with
|
||||
untyped values.
|
||||
|
||||
## Reading Properties with `js_sys::Reflect::get`
|
||||
|
||||
[API documentation for `js_sys::Reflect::get`.](https://docs.rs/js-sys/0.3.39/js_sys/Reflect/fn.get.html)
|
||||
|
||||
A function that returns the value of a property.
|
||||
|
||||
#### Rust Usage
|
||||
|
||||
```rust
|
||||
let value = js_sys::Reflect::get(&target, &property_key)?;
|
||||
```
|
||||
|
||||
#### JavaScript Equivalent
|
||||
|
||||
```js
|
||||
let value = target[property_key];
|
||||
```
|
||||
|
||||
## Writing Properties with `js_sys::Reflect::set`
|
||||
|
||||
[API documentation for `js_sys::Reflect::set`.](https://docs.rs/js-sys/0.3.39/js_sys/Reflect/fn.set.html)
|
||||
|
||||
A function that assigns a value to a property. Returns a boolean that is true if
|
||||
the update was successful.
|
||||
|
||||
#### Rust Usage
|
||||
|
||||
```rust
|
||||
js_sys::Reflect::set(&target, &property_key, &value)?;
|
||||
```
|
||||
|
||||
#### JavaScript Equivalent
|
||||
|
||||
```js
|
||||
target[property_key] = value;
|
||||
```
|
||||
|
||||
## Determining if a Property Exists with `js_sys::Reflect::has`
|
||||
|
||||
[API documentation for `js_sys::Reflect::has`.](https://docs.rs/js-sys/0.3.39/js_sys/Reflect/fn.has.html)
|
||||
|
||||
The JavaScript `in` operator as function. Returns a boolean indicating whether
|
||||
an own or inherited property exists on the target.
|
||||
|
||||
#### Rust Usage
|
||||
|
||||
```rust
|
||||
if js_sys::Reflect::has(&target, &property_key)? {
|
||||
// ...
|
||||
} else {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### JavaScript Equivalent
|
||||
|
||||
```js
|
||||
if (property_key in target) {
|
||||
// ...
|
||||
} else {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## But wait — there's more!
|
||||
|
||||
See [the `js_sys::Reflect` API documentation][js-sys-reflect] for the full
|
||||
listing of JavaScript value reflection and introspection capabilities.
|
||||
|
||||
[js-sys-reflect]: https://docs.rs/js-sys/latest/js_sys/Reflect/index.html
|
||||
[mdn-reflect]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect
|
||||
154
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/reference/arbitrary-data-with-serde.md
vendored
Normal file
154
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/reference/arbitrary-data-with-serde.md
vendored
Normal file
@@ -0,0 +1,154 @@
|
||||
# Serializing and Deserializing Arbitrary Data Into and From `JsValue` with Serde
|
||||
|
||||
It's possible to pass arbitrary data from Rust to JavaScript by serializing it
|
||||
with [Serde](https://github.com/serde-rs/serde). This can be done through the
|
||||
[`serde-wasm-bindgen`](https://docs.rs/serde-wasm-bindgen) crate.
|
||||
|
||||
## Add dependencies
|
||||
|
||||
To use `serde-wasm-bindgen`, you first have to add it as a dependency in your
|
||||
`Cargo.toml`. You also need the `serde` crate, with the `derive` feature
|
||||
enabled, to allow your types to be serialized and deserialized with Serde.
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
serde-wasm-bindgen = "0.4"
|
||||
```
|
||||
|
||||
## Derive the `Serialize` and `Deserialize` Traits
|
||||
|
||||
Add `#[derive(Serialize, Deserialize)]` to your type. All of your type's
|
||||
members must also be supported by Serde, i.e. their types must also implement
|
||||
the `Serialize` and `Deserialize` traits.
|
||||
|
||||
For example, let's say we'd like to pass this `struct` to JavaScript; doing so
|
||||
is not possible in `wasm-bindgen` normally due to the use of `HashMap`s, arrays,
|
||||
and nested `Vec`s. None of those types are supported for sending across the wasm
|
||||
ABI naively, but all of them implement Serde's `Serialize` and `Deserialize`.
|
||||
|
||||
Note that we do not need to use the `#[wasm_bindgen]` macro.
|
||||
|
||||
```rust
|
||||
use serde::{Serialize, Deserialize};
|
||||
|
||||
#[derive(Serialize, Deserialize)]
|
||||
pub struct Example {
|
||||
pub field1: HashMap<u32, String>,
|
||||
pub field2: Vec<Vec<f32>>,
|
||||
pub field3: [f32; 4],
|
||||
}
|
||||
```
|
||||
|
||||
## Send it to JavaScript with `serde_wasm_bindgen::to_value`
|
||||
|
||||
Here's a function that will pass an `Example` to JavaScript by serializing it to
|
||||
`JsValue`:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub fn send_example_to_js() -> JsValue {
|
||||
let mut field1 = HashMap::new();
|
||||
field1.insert(0, String::from("ex"));
|
||||
let example = Example {
|
||||
field1,
|
||||
field2: vec![vec![1., 2.], vec![3., 4.]],
|
||||
field3: [1., 2., 3., 4.]
|
||||
};
|
||||
|
||||
serde_wasm_bindgen::to_value(&example).unwrap()
|
||||
}
|
||||
```
|
||||
|
||||
## Receive it from JavaScript with `serde_wasm_bindgen::from_value`
|
||||
|
||||
Here's a function that will receive a `JsValue` parameter from JavaScript and
|
||||
then deserialize an `Example` from it:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub fn receive_example_from_js(val: JsValue) {
|
||||
let example: Example = serde_wasm_bindgen::from_value(val).unwrap();
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## JavaScript Usage
|
||||
|
||||
In the `JsValue` that JavaScript gets, `field1` will be a `Map`, `field2` will
|
||||
be a JavaScript `Array` whose members are `Array`s of numbers, and `field3`
|
||||
will be an `Array` of numbers.
|
||||
|
||||
```js
|
||||
import { send_example_to_js, receive_example_from_js } from "example";
|
||||
|
||||
// Get the example object from wasm.
|
||||
let example = send_example_to_js();
|
||||
|
||||
// Add another "Vec" element to the end of the "Vec<Vec<f32>>"
|
||||
example.field2.push([5, 6]);
|
||||
|
||||
// Send the example object back to wasm.
|
||||
receive_example_from_js(example);
|
||||
```
|
||||
|
||||
## An alternative approach - using JSON
|
||||
|
||||
`serde-wasm-bindgen` works by directly manipulating JavaScript values. This
|
||||
requires a lot of calls back and forth between Rust and JavaScript, which can
|
||||
sometimes be slow. An alternative way of doing this is to serialize values to
|
||||
JSON, and then parse them on the other end. Browsers' JSON implementations are
|
||||
usually quite fast, and so this approach can outstrip `serde-wasm-bindgen`'s
|
||||
performance in some cases. But this approach supports only types that can be
|
||||
serialized as JSON, leaving out some important types that `serde-wasm-bindgen`
|
||||
supports such as `Map`, `Set`, and array buffers.
|
||||
|
||||
That's not to say that using JSON is always faster, though - the JSON approach
|
||||
can be anywhere from 2x to 0.2x the speed of `serde-wasm-bindgen`, depending on
|
||||
the JS runtime and the values being passed. It also leads to larger code size
|
||||
than `serde-wasm-bindgen`. So, make sure to profile each for your own use
|
||||
cases.
|
||||
|
||||
This approach is implemented in [`gloo_utils::format::JsValueSerdeExt`]:
|
||||
|
||||
```toml
|
||||
# Cargo.toml
|
||||
[dependencies]
|
||||
gloo-utils = { version = "0.1", features = ["serde"] }
|
||||
```
|
||||
|
||||
```rust
|
||||
use gloo_utils::format::JsValueSerdeExt;
|
||||
|
||||
#[wasm_bindgen]
|
||||
pub fn send_example_to_js() -> JsValue {
|
||||
let mut field1 = HashMap::new();
|
||||
field1.insert(0, String::from("ex"));
|
||||
let example = Example {
|
||||
field1,
|
||||
field2: vec![vec![1., 2.], vec![3., 4.]],
|
||||
field3: [1., 2., 3., 4.]
|
||||
};
|
||||
|
||||
JsValue::from_serde(&example).unwrap()
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
pub fn receive_example_from_js(val: JsValue) {
|
||||
let example: Example = val.into_serde().unwrap();
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
[`gloo_utils::format::JsValueSerdeExt`]: https://docs.rs/gloo-utils/latest/gloo_utils/format/trait.JsValueSerdeExt.html
|
||||
|
||||
## History
|
||||
|
||||
In previous versions of `wasm-bindgen`, `gloo-utils`'s JSON-based Serde support
|
||||
(`JsValue::from_serde` and `JsValue::into_serde`) was built into `wasm-bindgen`
|
||||
itself. However, this required a dependency on `serde_json`, which had a
|
||||
problem: with certain features of `serde_json` and other crates enabled,
|
||||
`serde_json` would end up with a circular dependency on `wasm-bindgen`, which
|
||||
is illegal in Rust and caused people's code to fail to compile. So, these
|
||||
methods were extracted out into `gloo-utils` with an extension trait and the
|
||||
originals were deprecated.
|
||||
6
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/reference/attributes/index.md
vendored
Normal file
6
clamav/libclamav_rust/.cargo/vendor/wasm-bindgen/guide/src/reference/attributes/index.md
vendored
Normal file
@@ -0,0 +1,6 @@
|
||||
# `#[wasm_bindgen]` Attributes
|
||||
|
||||
The `#[wasm_bindgen]` macro supports a good amount of configuration for
|
||||
controlling precisely how exports are exported, how imports are imported, and
|
||||
what the generated JavaScript glue ends up looking like. This section is an
|
||||
exhaustive reference of the possibilities!
|
||||
@@ -0,0 +1,29 @@
|
||||
# `catch`
|
||||
|
||||
The `catch` attribute allows catching a JavaScript exception. This can be
|
||||
attached to any imported function or method, and the function must return a
|
||||
`Result` where the `Err` payload is a `JsValue`:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
// `catch` on a standalone function.
|
||||
#[wasm_bindgen(catch)]
|
||||
fn foo() -> Result<(), JsValue>;
|
||||
|
||||
// `catch` on a method.
|
||||
type Zoidberg;
|
||||
#[wasm_bindgen(catch, method)]
|
||||
fn woop_woop_woop(this: &Zoidberg) -> Result<u32, JsValue>;
|
||||
}
|
||||
```
|
||||
|
||||
If calling the imported function throws an exception, then `Err` will be
|
||||
returned with the exception that was raised. Otherwise, `Ok` is returned with
|
||||
the result of the function.
|
||||
|
||||
> By default `wasm-bindgen` will take no action when wasm calls a JS function
|
||||
> which ends up throwing an exception. The wasm spec right now doesn't support
|
||||
> stack unwinding and as a result Rust code **will not execute destructors**.
|
||||
> This can unfortunately cause memory leaks in Rust right now, but as soon as
|
||||
> wasm implements catching exceptions we'll be sure to add support as well!
|
||||
@@ -0,0 +1,24 @@
|
||||
# `constructor`
|
||||
|
||||
The `constructor` attribute is used to indicate that the function being bound
|
||||
should actually translate to calling the `new` operator in JavaScript. The final
|
||||
argument must be a type that's imported from JavaScript, and it's what will get
|
||||
used in the generated glue:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Shoes;
|
||||
|
||||
#[wasm_bindgen(constructor)]
|
||||
fn new() -> Shoes;
|
||||
}
|
||||
```
|
||||
|
||||
This will attach a `new` static method to the `Shoes` type, and in JavaScript
|
||||
when this method is called, it will be equivalent to `new Shoes()`.
|
||||
|
||||
```rust
|
||||
// Become a cobbler; construct `new Shoes()`
|
||||
let shoes = Shoes::new();
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
# `extends = Class`
|
||||
|
||||
The `extends` attribute can be used to say that an imported type extends (in the
|
||||
JS class hierarchy sense) another type. This will generate `AsRef`, `AsMut`, and
|
||||
`From` impls for converting a type into another given that we statically know
|
||||
the inheritance hierarchy:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Foo;
|
||||
|
||||
#[wasm_bindgen(extends = Foo)]
|
||||
type Bar;
|
||||
}
|
||||
|
||||
let x: &Bar = ...;
|
||||
let y: &Foo = x.as_ref(); // zero cost cast
|
||||
```
|
||||
|
||||
The trait implementations generated for the above block are:
|
||||
|
||||
```rust
|
||||
impl From<Bar> for Foo { ... }
|
||||
impl AsRef<Foo> for Bar { ... }
|
||||
impl AsMut<Foo> for Bar { ... }
|
||||
```
|
||||
|
||||
|
||||
The `extends = ...` attribute can be specified multiple times for longer
|
||||
inheritance chains, and `AsRef` and such impls will be generated for each of
|
||||
the types.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Foo;
|
||||
|
||||
#[wasm_bindgen(extends = Foo)]
|
||||
type Bar;
|
||||
|
||||
#[wasm_bindgen(extends = Foo, extends = Bar)]
|
||||
type Baz;
|
||||
}
|
||||
|
||||
let x: &Baz = ...;
|
||||
let y1: &Bar = x.as_ref();
|
||||
let y2: &Foo = y1.as_ref();
|
||||
```
|
||||
@@ -0,0 +1,156 @@
|
||||
# `final`
|
||||
|
||||
The `final` attribute is the converse of the [`structural`
|
||||
attribute](structural.html). It configures how `wasm-bindgen` will generate JS
|
||||
imports to call the imported function. Notably a function imported by `final`
|
||||
never changes after it was imported, whereas a function imported by default (or
|
||||
with `structural`) is subject to runtime lookup rules such as walking the
|
||||
prototype chain of an object. Note that `final` is not suitable for accessing
|
||||
data descriptor properties of JS objects; to accomplish this, use the `structural`
|
||||
attribute.
|
||||
|
||||
[host-bindings]: https://github.com/WebAssembly/host-bindings
|
||||
[reference-types]: https://github.com/WebAssembly/reference-types
|
||||
|
||||
The `final` attribute is intended to be purely related to performance. It
|
||||
ideally has no user-visible effect, and `structural` imports (the default)
|
||||
should be able to transparently switch to `final` eventually.
|
||||
|
||||
The eventual performance aspect is that with the [host bindings
|
||||
proposal][host-bindings] then `wasm-bindgen` will need to generate far fewer JS
|
||||
function shims to import than it does today. For example, consider this import
|
||||
today:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Foo;
|
||||
#[wasm_bindgen(method)]
|
||||
fn bar(this: &Foo, argument: &str) -> JsValue;
|
||||
}
|
||||
```
|
||||
|
||||
**Without the `final` attribute** the generated JS looks like this:
|
||||
|
||||
```js
|
||||
// without `final`
|
||||
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
|
||||
let varg1 = getStringFromWasm(arg1, arg2);
|
||||
return addHeapObject(getObject(arg0).bar(varg1));
|
||||
}
|
||||
```
|
||||
|
||||
We can see here that this JS function shim is required, but it's all relatively
|
||||
self-contained. It does, however, execute the `bar` method in a duck-type-y
|
||||
fashion in the sense that it never validates `getObject(arg0)` is of type `Foo`
|
||||
to actually call the `Foo.prototype.bar` method.
|
||||
|
||||
If we instead, however, write this:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Foo;
|
||||
#[wasm_bindgen(method, final)] // note the change here
|
||||
fn bar(this: &Foo, argument: &str) -> JsValue;
|
||||
}
|
||||
```
|
||||
|
||||
it generates this JS glue (roughly):
|
||||
|
||||
```js
|
||||
const __wbg_bar_target = Foo.prototype.bar;
|
||||
|
||||
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
|
||||
let varg1 = getStringFromWasm(arg1, arg2);
|
||||
return addHeapObject(__wbg_bar_target.call(getObject(arg0), varg1));
|
||||
}
|
||||
```
|
||||
|
||||
The difference here is pretty subtle, but we can see how the function being
|
||||
called is hoisted out of the generated shim and is bound to always be
|
||||
`Foo.prototype.bar`. This then uses the `Function.call` method to invoke that
|
||||
function with `getObject(arg0)` as the receiver.
|
||||
|
||||
But wait, there's still a JS function shim here even with `final`! That's true,
|
||||
and this is simply a fact of future WebAssembly proposals not being implemented
|
||||
yet. The semantics, though, match the future [host bindings
|
||||
proposal][host-bindings] because the method being called is determined exactly
|
||||
once, and it's located on the prototype chain rather than being resolved at
|
||||
runtime when the function is called.
|
||||
|
||||
## Interaction with future proposals
|
||||
|
||||
If you're curious to see how our JS function shim will be eliminated entirely,
|
||||
let's take a look at the generated bindings. We're starting off with this:
|
||||
|
||||
```js
|
||||
const __wbg_bar_target = Foo.prototype.bar;
|
||||
|
||||
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
|
||||
let varg1 = getStringFromWasm(arg1, arg2);
|
||||
return addHeapObject(__wbg_bar_target.call(getObject(arg0), varg1));
|
||||
}
|
||||
```
|
||||
|
||||
... and once the [reference types proposal][reference-types] is implemented then
|
||||
we won't need some of these pesky functions. That'll transform our generated JS
|
||||
shim to look like:
|
||||
|
||||
```js
|
||||
const __wbg_bar_target = Foo.prototype.bar;
|
||||
|
||||
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
|
||||
let varg1 = getStringFromWasm(arg1, arg2);
|
||||
return __wbg_bar_target.call(arg0, varg1);
|
||||
}
|
||||
```
|
||||
|
||||
Getting better! Next up we need the host bindings proposal. Note that the
|
||||
proposal is undergoing some changes right now so it's tough to link to reference
|
||||
documentation, but it suffices to say that it'll empower us with at least two
|
||||
different features.
|
||||
|
||||
First, host bindings promises to provide the concept of "argument conversions".
|
||||
The `arg1` and `arg2` values here are actually a pointer and a length to a utf-8
|
||||
encoded string, and with host bindings we'll be able to annotate that this
|
||||
import should take those two arguments and convert them to a JS string (that is,
|
||||
the *host* should do this, the WebAssembly engine). Using that feature we can
|
||||
futher trim this down to:
|
||||
|
||||
```js
|
||||
const __wbg_bar_target = Foo.prototype.bar;
|
||||
|
||||
export function __wbg_bar_a81456386e6b526f(arg0, varg1) {
|
||||
return __wbg_bar_target.call(arg0, varg1);
|
||||
}
|
||||
```
|
||||
|
||||
And finally, the second promise of the host bindings proposal is that we can
|
||||
flag a function call to indicate the first argument is the `this` binding of the
|
||||
function call. Today the `this` value of all called imported functions is
|
||||
`undefined`, and this flag (configured with host bindings) will indicate the
|
||||
first argument here is actually the `this`.
|
||||
|
||||
With that in mind we can further transform this to:
|
||||
|
||||
```js
|
||||
export const __wbg_bar_a81456386e6b526f = Foo.prototype.bar;
|
||||
```
|
||||
|
||||
and voila! We, with [reference types][reference-types] and [host
|
||||
bindings][host-bindings], now have no JS function shim at all necessary to call
|
||||
the imported function. Additionally future wasm proposals to the ES module
|
||||
system may also mean that don't even need the `export const ...` here too.
|
||||
|
||||
It's also worth pointing out that with all these wasm proposals implemented the
|
||||
default way to import the `bar` function (aka `structural`) would generate a JS
|
||||
function shim that looks like:
|
||||
|
||||
```js
|
||||
export function __wbg_bar_a81456386e6b526f(varg1) {
|
||||
return this.bar(varg1);
|
||||
}
|
||||
```
|
||||
|
||||
where this import is still subject to runtime prototype chain lookups and such.
|
||||
@@ -0,0 +1,78 @@
|
||||
# `getter` and `setter`
|
||||
|
||||
These two attributes can be combined with `method` to indicate that this is a
|
||||
getter or setter method. A `getter`-tagged function by default accesses the
|
||||
JavaScript property with the same name as the getter function. A `setter`'s
|
||||
function name is currently required to start with `set_` and the property it
|
||||
accesses is the suffix after `set\_`.
|
||||
|
||||
Consider the following JavaScript class that has a getter and setter for the
|
||||
`white_russians` property:
|
||||
|
||||
```js
|
||||
class TheDude {
|
||||
get white_russians() {
|
||||
...
|
||||
}
|
||||
set white_russians(val) {
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
We would import this with the following `#[wasm_bindgen]` attributes:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type TheDude;
|
||||
|
||||
#[wasm_bindgen(method, getter)]
|
||||
fn white_russians(this: &TheDude) -> u32;
|
||||
|
||||
#[wasm_bindgen(method, setter)]
|
||||
fn set_white_russians(this: &TheDude, val: u32);
|
||||
}
|
||||
```
|
||||
|
||||
Here we're importing the `TheDude` type and defining the ability to access each
|
||||
object's `white_russians` property. The first function here is a getter and will
|
||||
be available in Rust as `the_dude.white_russians()`, and the latter is the
|
||||
setter which is accessible as `the_dude.set_white_russians(2)`. Note that both
|
||||
functions have a `this` argument as they're tagged with `method`.
|
||||
|
||||
Finally, you can also pass an argument to the `getter` and `setter`
|
||||
properties to configure what property is accessed. When the property is
|
||||
explicitly specified then there is no restriction on the method name. For
|
||||
example the below is equivalent to the above:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type TheDude;
|
||||
|
||||
#[wasm_bindgen(method, getter = white_russians)]
|
||||
fn my_custom_getter_name(this: &TheDude) -> u32;
|
||||
|
||||
#[wasm_bindgen(method, setter = white_russians)]
|
||||
fn my_custom_setter_name(this: &TheDude, val: u32);
|
||||
}
|
||||
```
|
||||
|
||||
Heads up! `getter` and `setter` functions are found on the constructor's
|
||||
prototype chain once at load time, cached, and then the cached accessor is
|
||||
invoked on each access. If you need to dynamically walk the prototype chain on
|
||||
every access, add the `structural` attribute!
|
||||
|
||||
```js
|
||||
// This is the default function Rust will invoke on `the_dude.white_russians()`:
|
||||
const white_russians = Object.getOwnPropertyDescriptor(
|
||||
TheDude.prototype,
|
||||
"white_russians"
|
||||
).get;
|
||||
|
||||
// This is what you get by adding `structural`:
|
||||
const white_russians = function(the_dude) {
|
||||
return the_dude.white_russians;
|
||||
};
|
||||
```
|
||||
@@ -0,0 +1,5 @@
|
||||
# `#[wasm_bindgen]` on JavaScript Imports
|
||||
|
||||
This section enumerates the attributes available for customizing bindings for
|
||||
JavaScript functions and classes imported into Rust within an `extern "C" { ... }`
|
||||
block.
|
||||
@@ -0,0 +1,82 @@
|
||||
# `indexing_getter`, `indexing_setter`, and `indexing_deleter`
|
||||
|
||||
These three attributes indicate that a method is an dynamically intercepted
|
||||
getter, setter, or deleter on the receiver object itself, rather than a direct
|
||||
access of the receiver's properties. It is equivalent calling the Proxy handler
|
||||
for the `obj[prop]` operation with some dynamic `prop` variable in JavaScript,
|
||||
rather than a normal static property access like `obj.prop` on a normal
|
||||
JavaScript `Object`.
|
||||
|
||||
This is useful for binding to `Proxy`s and some builtin DOM types that
|
||||
dynamically intercept property accesses.
|
||||
|
||||
* `indexing_getter` corresponds to `obj[prop]` operation in JavaScript. The
|
||||
function annotated must have a `this` receiver parameter, a single parameter
|
||||
that is used for indexing into the receiver (`prop`), and a return type.
|
||||
|
||||
* `indexing_setter` corresponds to the `obj[prop] = val` operation in
|
||||
JavaScript. The function annotated must have a `this` receiver parameter, a
|
||||
parameter for indexing into the receiver (`prop`), and a value parameter
|
||||
(`val`).
|
||||
|
||||
* `indexing_deleter` corresponds to `delete obj[prop]` operation in
|
||||
JavaScript. The function annotated must have a `this` receiver and a single
|
||||
parameter for indexing into the receiver (`prop`).
|
||||
|
||||
These must always be used in conjunction with the `structural` and `method`
|
||||
flags.
|
||||
|
||||
For example, consider this JavaScript snippet that uses `Proxy`:
|
||||
|
||||
```js
|
||||
const foo = new Proxy({}, {
|
||||
get(obj, prop) {
|
||||
return prop in obj ? obj[prop] : prop.length;
|
||||
},
|
||||
set(obj, prop, value) {
|
||||
obj[prop] = value;
|
||||
},
|
||||
deleteProperty(obj, prop) {
|
||||
delete obj[prop];
|
||||
},
|
||||
});
|
||||
|
||||
foo.ten;
|
||||
// 3
|
||||
|
||||
foo.ten = 10;
|
||||
foo.ten;
|
||||
// 10
|
||||
|
||||
delete foo.ten;
|
||||
foo.ten;
|
||||
// 3
|
||||
```
|
||||
|
||||
To bind that in `wasm-bindgen` in Rust, we would use the `indexing_*` attributes
|
||||
on methods:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Foo;
|
||||
static foo: Foo;
|
||||
|
||||
#[wasm_bindgen(method, structural, indexing_getter)]
|
||||
fn get(this: &Foo, prop: &str) -> u32;
|
||||
|
||||
#[wasm_bindgen(method, structural, indexing_setter)]
|
||||
fn set(this: &Foo, prop: &str, val: u32);
|
||||
|
||||
#[wasm_bindgen(method, structural, indexing_deleter)]
|
||||
fn delete(this: &Foo, prop: &str);
|
||||
}
|
||||
|
||||
assert_eq!(foo.get("ten"), 3);
|
||||
|
||||
foo.set("ten", 10);
|
||||
assert_eq!(foo.get("ten"), 10);
|
||||
|
||||
foo.delete("ten");
|
||||
assert_eq!(foo.get("ten"), 3);
|
||||
```
|
||||
@@ -0,0 +1,20 @@
|
||||
# `js_class = "Blah"`
|
||||
|
||||
The `js_class` attribute can be used in conjunction with the `method` attribute
|
||||
to bind methods of imported JavaScript classes that have been renamed on the
|
||||
Rust side.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
// We don't want to import JS strings as `String`, since Rust already has a
|
||||
// `String` type in its prelude, so rename it as `JsString`.
|
||||
#[wasm_bindgen(js_name = String)]
|
||||
type JsString;
|
||||
|
||||
// This is a method on the JavaScript "String" class, so specify that with
|
||||
// the `js_class` attribute.
|
||||
#[wasm_bindgen(method, js_class = "String", js_name = charAt)]
|
||||
fn char_at(this: &JsString, index: u32) -> JsString;
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,87 @@
|
||||
# `js_name = blah`
|
||||
|
||||
The `js_name` attribute can be used to bind to a different function in
|
||||
JavaScript than the identifier that's defined in Rust.
|
||||
|
||||
Most often, this is used to convert a camel-cased JavaScript identifier into a
|
||||
snake-cased Rust identifier:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(js_name = jsOftenUsesCamelCase)]
|
||||
fn js_often_uses_camel_case() -> u32;
|
||||
}
|
||||
```
|
||||
|
||||
Sometimes, it is used to bind to JavaScript identifiers that are not valid Rust
|
||||
identifiers, in which case `js_name = "some string"` is used instead of `js_name
|
||||
= ident`:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(js_name = "$$$")]
|
||||
fn cash_money() -> u32;
|
||||
}
|
||||
```
|
||||
However, you can also use `js_name` to define multiple signatures for
|
||||
polymorphic JavaScript functions:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(js_namespace = console, js_name = log)]
|
||||
fn console_log_str(s: &str);
|
||||
|
||||
#[wasm_bindgen(js_namespace = console, js_name = log)]
|
||||
fn console_log_u32(n: u32);
|
||||
|
||||
#[wasm_bindgen(js_namespace = console, js_name = log)]
|
||||
fn console_log_many(a: u32, b: &JsValue);
|
||||
}
|
||||
```
|
||||
|
||||
All of these functions will call `console.log` in JavaScript, but each
|
||||
identifier will have only one signature in Rust.
|
||||
|
||||
Note that if you use `js_name` when importing a type you'll also need to use the
|
||||
[`js_class` attribute][jsclass] when defining methods on the type:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(js_name = String)]
|
||||
type JsString;
|
||||
#[wasm_bindgen(method, getter, js_class = "String")]
|
||||
pub fn length(this: &JsString) -> u32;
|
||||
}
|
||||
```
|
||||
|
||||
The `js_name` attribute can also be used in situations where a JavaScript module uses
|
||||
`export default`. In this case, setting the `js_name` attribute to "default" on the
|
||||
`type` declaration, and the [`js_class` attribute][jsclass] to "default" on any methods
|
||||
on the exported object will generate the correct imports.
|
||||
|
||||
|
||||
For example, a module that would be imported directly in JavaScript:
|
||||
|
||||
```javascript
|
||||
import Foo from "bar";
|
||||
|
||||
let f = new Foo();
|
||||
```
|
||||
|
||||
Could be accessed using this definition in Rust:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(module = "bar")]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(js_name = default)]
|
||||
type Foo;
|
||||
#[wasm_bindgen(constructor, js_class = default)]
|
||||
pub fn new() -> Foo;
|
||||
}
|
||||
```
|
||||
|
||||
[jsclass]: js_class.html
|
||||
@@ -0,0 +1,41 @@
|
||||
# `js_namespace = blah`
|
||||
|
||||
This attribute indicates that the JavaScript type is accessed through the given
|
||||
namespace. For example, the `WebAssembly.Module` APIs are all accessed through
|
||||
the `WebAssembly` namespace. `js_namespace` can be applied to any import
|
||||
(function or type) and whenever the generated JavaScript attempts to reference a
|
||||
name (like a class or function name) it'll be accessed through this namespace.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(js_namespace = console)]
|
||||
fn log(s: &str);
|
||||
|
||||
type Foo;
|
||||
#[wasm_bindgen(constructor, js_namespace = Bar)]
|
||||
fn new() -> Foo;
|
||||
}
|
||||
|
||||
log("hello, console!");
|
||||
Foo::new();
|
||||
```
|
||||
|
||||
This is an example of how to bind namespaced items in Rust. The `log` and `Foo::new` functions will
|
||||
be available in the Rust module and will be invoked as `console.log` and `new Bar.Foo` in
|
||||
JavaScript.
|
||||
|
||||
It is also possible to access the JavaScript object under the nested namespace.
|
||||
`js_namespace` also accepts the array of the string to specify the namespace.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(js_namespace = ["window", "document"])]
|
||||
fn write(s: &str);
|
||||
}
|
||||
|
||||
write("hello, document!");
|
||||
```
|
||||
|
||||
This example shows how to bind `window.document.write` in Rust.
|
||||
@@ -0,0 +1,26 @@
|
||||
# `method`
|
||||
|
||||
The `method` attribute allows you to describe methods of imported JavaScript
|
||||
objects. It is applied on a function that has `this` as its first parameter,
|
||||
which is a shared reference to an imported JavaScript type.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Set;
|
||||
|
||||
#[wasm_bindgen(method)]
|
||||
fn has(this: &Set, element: &JsValue) -> bool;
|
||||
}
|
||||
```
|
||||
|
||||
This generates a `has` method on `Set` in Rust, which invokes the
|
||||
`Set.prototype.has` method in JavaScript.
|
||||
|
||||
```rust
|
||||
let set: Set = ...;
|
||||
let elem: JsValue = ...;
|
||||
if set.has(&elem) {
|
||||
...
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,38 @@
|
||||
# `module = "blah"`
|
||||
|
||||
The `module` attributes configures the module from which items are imported. For
|
||||
example,
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(module = "wu/tang/clan")]
|
||||
extern "C" {
|
||||
type ThirtySixChambers;
|
||||
}
|
||||
```
|
||||
|
||||
generates JavaScript import glue like:
|
||||
|
||||
```js
|
||||
import { ThirtySixChambers } from "wu/tang/clan";
|
||||
```
|
||||
|
||||
If a `module` attribute is not present, then the global scope is used
|
||||
instead. For example,
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
fn illmatic() -> u32;
|
||||
}
|
||||
```
|
||||
|
||||
generates JavaScript import glue like:
|
||||
|
||||
```js
|
||||
let illmatic = this.illmatic;
|
||||
```
|
||||
|
||||
Note that if the string specified with `module` starts with `./`, `../`, or `/`
|
||||
then it's interpreted as a path to a [local JS snippet](../../js-snippets.html).
|
||||
If this doesn't work for your use case you might be interested in the
|
||||
[`raw_module` attribute](raw_module.html)
|
||||
@@ -0,0 +1,24 @@
|
||||
# `no_deref`
|
||||
|
||||
The `no_deref` attribute can be used to say that no `Deref` impl should be
|
||||
generated for an imported type. If this attribute is not present, a `Deref` impl
|
||||
will be generated with a `Target` of the type's first `extends` attribute, or
|
||||
`Target = JsValue` if there are no `extends` attributes.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Foo;
|
||||
|
||||
#[wasm_bindgen(method)]
|
||||
fn baz(this: &Foo)
|
||||
|
||||
#[wasm_bindgen(extends = Foo, no_deref)]
|
||||
type Bar;
|
||||
}
|
||||
|
||||
fn do_stuff(bar: &Bar) {
|
||||
bar.baz() // Does not compile
|
||||
}
|
||||
|
||||
```
|
||||
@@ -0,0 +1,19 @@
|
||||
# `raw_module = "blah"`
|
||||
|
||||
This attribute performs exactly the same purpose as the [`module`
|
||||
attribute](module.html) on JS imports, but it does not attempt to interpret
|
||||
paths starting with `./`, `../`, or `/` as JS snippets. For example:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(raw_module = "./some/js/file.js")]
|
||||
extern "C" {
|
||||
fn the_function();
|
||||
}
|
||||
```
|
||||
|
||||
Note that if you use this attribute with a relative or absolute path, it's
|
||||
likely up to the final bundler or project to assign meaning to that path. This
|
||||
typically means that the JS file or module will be resolved relative to the
|
||||
final location of the wasm file itself. That means that `raw_module` is likely
|
||||
unsuitable for libraries on crates.io, but may be usable within end-user
|
||||
applications.
|
||||
@@ -0,0 +1,28 @@
|
||||
# `static_method_of = Blah`
|
||||
|
||||
The `static_method_of` attribute allows one to specify that an imported function
|
||||
is a static method of the given imported JavaScript class. For example, to bind
|
||||
to JavaScript's `Date.now()` static method, one would use this attribute:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Date;
|
||||
|
||||
#[wasm_bindgen(static_method_of = Date)]
|
||||
pub fn now() -> f64;
|
||||
}
|
||||
```
|
||||
|
||||
The `now` function becomes a static method of the imported type in the Rust
|
||||
bindings as well:
|
||||
|
||||
```rust
|
||||
let instant = Date::now();
|
||||
```
|
||||
|
||||
This is similar to the `js_namespace` attribute, but the usage from within Rust
|
||||
is different since the method also becomes a static method of the imported type.
|
||||
Additionally this attribute also specifies that the `this` parameter when
|
||||
invoking the method is expected to be the JS class, e.g. always invoked as
|
||||
`Date.now()` instead of `const x = Date.now; x()`.
|
||||
@@ -0,0 +1,48 @@
|
||||
# `structural`
|
||||
|
||||
> **Note**: As of [RFC 5] this attribute is the default for all imported
|
||||
> functions. This attribute is largely ignored today and is only retained for
|
||||
> backwards compatibility and learning purposes.
|
||||
>
|
||||
> The inverse of this attribute, [the `final`
|
||||
> attribute](final.html) is more functionally interesting than
|
||||
> `structural` (as `structural` is simply the default)
|
||||
|
||||
[RFC 5]: https://rustwasm.github.io/rfcs/005-structural-and-deref.html
|
||||
|
||||
The `structural` flag can be added to `method` annotations, indicating that the
|
||||
method being accessed (or property with getters/setters) should be accessed in a
|
||||
structural, duck-type-y fashion. Rather than walking the constructor's prototype
|
||||
chain once at load time and caching the property result, the prototype chain is
|
||||
dynamically walked on every access.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
type Duck;
|
||||
|
||||
#[wasm_bindgen(method, structural)]
|
||||
fn quack(this: &Duck);
|
||||
|
||||
#[wasm_bindgen(method, getter, structural)]
|
||||
fn is_swimming(this: &Duck) -> bool;
|
||||
}
|
||||
```
|
||||
|
||||
The constructor for the type here, `Duck`, is not required to exist in
|
||||
JavaScript (it's not referenced). Instead `wasm-bindgen` will generate shims
|
||||
that will access the passed in JavaScript value's `quack` method or its
|
||||
`is_swimming` property.
|
||||
|
||||
```js
|
||||
// Without `structural`, get the method directly off the prototype at load time:
|
||||
const Duck_prototype_quack = Duck.prototype.quack;
|
||||
function quack(duck) {
|
||||
Duck_prototype_quack.call(duck);
|
||||
}
|
||||
|
||||
// With `structural`, walk the prototype chain on every access:
|
||||
function quack(duck) {
|
||||
duck.quack();
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,15 @@
|
||||
# `typescript_type = "Blah"`
|
||||
|
||||
The `typescript_type` attribute is used to specify the TypeScript type for an
|
||||
imported type. This type will be used in the generated `.d.ts`.
|
||||
|
||||
Right now only identifiers are supported, but eventually we'd like to support
|
||||
all TypeScript types.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(typescript_type = "Foo")]
|
||||
type Foo;
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,53 @@
|
||||
# Variadic Parameters
|
||||
|
||||
In javascript, both the types of function arguments, and the number of function arguments are
|
||||
dynamic. For example
|
||||
|
||||
```js
|
||||
function sum(...rest) {
|
||||
let i;
|
||||
// the old way
|
||||
let old_way = 0;
|
||||
for (i=0; i<arguments.length; i++) {
|
||||
old_way += arguments[i];
|
||||
}
|
||||
// the new way
|
||||
let new_way = 0;
|
||||
for (i=0; i<rest.length; i++) {
|
||||
new_way += rest[i];
|
||||
}
|
||||
// both give the same answer
|
||||
assert(old_way === new_way);
|
||||
return new_way;
|
||||
}
|
||||
```
|
||||
|
||||
This function doesn't translate directly into rust, since we don't currently support variadic
|
||||
arguments on the wasm target. To bind to it, we use a slice as the last argument, and annotate the
|
||||
function as variadic:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(variadic)]
|
||||
fn sum(args: &[i32]) -> i32;
|
||||
}
|
||||
```
|
||||
|
||||
when we call this function, the last argument will be expanded as the javascript expects.
|
||||
|
||||
|
||||
To export a rust function to javascript with a variadic argument, we will use the same bindgen variadic attribute and assume that the last argument will be the variadic array. For example the following rust function:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(variadic)]
|
||||
pub fn variadic_function(arr: &JsValue) -> JsValue {
|
||||
arr.into()
|
||||
}
|
||||
```
|
||||
|
||||
will generate the following TS interface
|
||||
|
||||
```ts
|
||||
export function variadic_function(...arr: any): any;
|
||||
```
|
||||
@@ -0,0 +1,24 @@
|
||||
# Vendor-prefixed APIs
|
||||
|
||||
On the web new APIs often have vendor prefixes while they're in an experimental
|
||||
state. For example the `AudioContext` API is known as `webkitAudioContext` in
|
||||
Safari at the time of this writing. The `vendor_prefix` attribute indicates
|
||||
these alternative names, which are used if the normal name isn't defined.
|
||||
|
||||
For example to use `AudioContext` you might do:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
extern "C" {
|
||||
#[wasm_bindgen(vendor_prefix = webkit)]
|
||||
type AudioContext;
|
||||
|
||||
// methods on `AudioContext` ...
|
||||
}
|
||||
```
|
||||
|
||||
Whenever `AudioContext` is used it'll use `AudioContext` if the global namespace
|
||||
defines it or alternatively it'll fall back to `webkitAudioContext`.
|
||||
|
||||
Note that `vendor_prefix` cannot be used with `module = "..."` or
|
||||
`js_namespace = ...`, so it's basically limited to web-platform APIs today.
|
||||
@@ -0,0 +1,34 @@
|
||||
# `constructor`
|
||||
|
||||
When attached to a Rust "constructor" it will make the generated JavaScript
|
||||
bindings callable as `new Foo()`.
|
||||
|
||||
For example, consider this exported Rust type and `constructor` annotation:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub struct Foo {
|
||||
contents: u32,
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
impl Foo {
|
||||
#[wasm_bindgen(constructor)]
|
||||
pub fn new() -> Foo {
|
||||
Foo { contents: 0 }
|
||||
}
|
||||
|
||||
pub fn get_contents(&self) -> u32 {
|
||||
self.contents
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This can be used in JavaScript as:
|
||||
|
||||
```js
|
||||
import { Foo } from './my_module';
|
||||
|
||||
const f = new Foo();
|
||||
console.log(f.get_contents());
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
# `getter` and `setter`
|
||||
|
||||
The `getter` and `setter` attributes can be used in Rust `impl` blocks to define
|
||||
properties in JS that act like getters and setters of a field. For example:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub struct Baz {
|
||||
field: i32,
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
impl Baz {
|
||||
#[wasm_bindgen(constructor)]
|
||||
pub fn new(field: i32) -> Baz {
|
||||
Baz { field }
|
||||
}
|
||||
|
||||
#[wasm_bindgen(getter)]
|
||||
pub fn field(&self) -> i32 {
|
||||
self.field
|
||||
}
|
||||
|
||||
#[wasm_bindgen(setter)]
|
||||
pub fn set_field(&mut self, field: i32) {
|
||||
self.field = field;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Can be combined in `JavaScript` like in this snippet:
|
||||
|
||||
```js
|
||||
const obj = new Baz(3);
|
||||
assert.equal(obj.field, 3);
|
||||
obj.field = 4;
|
||||
assert.equal(obj.field, 4);
|
||||
```
|
||||
|
||||
You can also configure the name of the property that is exported in JS like so:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
impl Baz {
|
||||
#[wasm_bindgen(getter = anotherName)]
|
||||
pub fn field(&self) -> i32 {
|
||||
self.field
|
||||
}
|
||||
|
||||
#[wasm_bindgen(setter = anotherName)]
|
||||
pub fn set_field(&mut self, field: i32) {
|
||||
self.field = field;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Getters are expected to take no arguments other than `&self` and return the
|
||||
field's type. Setters are expected to take one argument other than `&mut self`
|
||||
(or `&self`) and return no values.
|
||||
|
||||
The name for a `getter` is by default inferred from the function name it's
|
||||
attached to. The default name for a `setter` is the function's name minus the
|
||||
`set_` prefix, and if `set_` isn't a prefix of the function it's an error to not
|
||||
provide the name explicitly.
|
||||
@@ -0,0 +1,17 @@
|
||||
# `getter_with_clone`
|
||||
|
||||
By default, Rust exports exposed to JavaScript will generate getters that require fields to implement `Copy`. The `getter_with_clone` attribute can be used to generate getters that require `Clone` instead. This attribute can be applied per struct or per field. For example:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub struct Foo {
|
||||
#[wasm_bindgen(getter_with_clone)]
|
||||
pub bar: String,
|
||||
}
|
||||
|
||||
#[wasm_bindgen(getter_with_clone)]
|
||||
pub struct Foo {
|
||||
pub bar: String,
|
||||
pub baz: String,
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
# `#[wasm_bindgen]` on Rust Exports
|
||||
|
||||
This section enumerates the attributes available for customizing bindings for
|
||||
Rust functions and `struct`s exported to JavaScript.
|
||||
@@ -0,0 +1,53 @@
|
||||
# `inspectable`
|
||||
|
||||
By default, structs exported from Rust become JavaScript classes with a single `ptr` property. All other properties are implemented as getters, which are not displayed when calling `toJSON`.
|
||||
|
||||
The `inspectable` attribute can be used on Rust structs to provide a `toJSON` and `toString` implementation that display all readable fields. For example:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(inspectable)]
|
||||
pub struct Baz {
|
||||
pub field: i32,
|
||||
private: i32,
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
impl Baz {
|
||||
#[wasm_bindgen(constructor)]
|
||||
pub fn new(field: i32) -> Baz {
|
||||
Baz { field, private: 13 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Provides the following behavior as in this JavaScript snippet:
|
||||
|
||||
```js
|
||||
const obj = new Baz(3);
|
||||
assert.deepStrictEqual(obj.toJSON(), { field: 3 });
|
||||
obj.field = 4;
|
||||
assert.strictEqual(obj.toString(), '{"field":4}');
|
||||
```
|
||||
|
||||
One or both of these implementations can be overridden as desired. Note that the generated `toString` calls `toJSON` internally, so overriding `toJSON` will affect its output as a side effect.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
impl Baz {
|
||||
#[wasm_bindgen(js_name = toJSON)]
|
||||
pub fn to_json(&self) -> i32 {
|
||||
self.field
|
||||
}
|
||||
|
||||
#[wasm_bindgen(js_name = toString)]
|
||||
pub fn to_string(&self) -> String {
|
||||
format!("Baz: {}", self.field)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note that the output of `console.log` will remain unchanged and display only the `ptr` field in browsers. It is recommended to call `toJSON` or `JSON.stringify` in these situations to aid with logging or debugging. Node.js does not suffer from this limitation, see the section below.
|
||||
|
||||
## `inspectable` Classes in Node.js
|
||||
|
||||
When the `nodejs` target is used, an additional `[util.inspect.custom]` implementation is provided which calls `toJSON` internally. This method is used for `console.log` and similar functions to display all readable fields of the Rust struct.
|
||||
@@ -0,0 +1,28 @@
|
||||
# `js_class = Blah`
|
||||
|
||||
The `js_class` attribute is used to indicate that all the methods inside an
|
||||
`impl` block should be attached to the specified JS class instead of inferring
|
||||
it from the self type in the `impl` block. The `js_class` attribute is most
|
||||
frequently paired with [the `js_name` attribute](js_name.html) on structs:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(js_name = Foo)]
|
||||
pub struct JsFoo { /* ... */ }
|
||||
|
||||
#[wasm_bindgen(js_class = Foo)]
|
||||
impl JsFoo {
|
||||
#[wasm_bindgen(constructor)]
|
||||
pub fn new() -> JsFoo { /* ... */ }
|
||||
|
||||
pub fn foo(&self) { /* ... */ }
|
||||
}
|
||||
```
|
||||
|
||||
which is accessed like:
|
||||
|
||||
```rust
|
||||
import { Foo } from './my_module';
|
||||
|
||||
const x = new Foo();
|
||||
x.foo();
|
||||
```
|
||||
@@ -0,0 +1,54 @@
|
||||
# `js_name = Blah`
|
||||
|
||||
The `js_name` attribute can be used to export a different name in JS than what
|
||||
something is named in Rust. It can be applied to both exported Rust functions
|
||||
and types.
|
||||
|
||||
For example, this is often used to convert between Rust's snake-cased
|
||||
identifiers into JavaScript's camel-cased identifiers:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(js_name = doTheThing)]
|
||||
pub fn do_the_thing() -> u32 {
|
||||
42
|
||||
}
|
||||
```
|
||||
|
||||
This can be used in JavaScript as:
|
||||
|
||||
```js
|
||||
import { doTheThing } from './my_module';
|
||||
|
||||
const x = doTheThing();
|
||||
console.log(x);
|
||||
```
|
||||
|
||||
Like imports, `js_name` can also be used to rename types exported to JS:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(js_name = Foo)]
|
||||
pub struct JsFoo {
|
||||
// ..
|
||||
}
|
||||
```
|
||||
|
||||
to be accessed like:
|
||||
|
||||
```js
|
||||
import { Foo } from './my_module';
|
||||
|
||||
// ...
|
||||
```
|
||||
|
||||
Note that attaching methods to the JS class `Foo` should be done via the
|
||||
[`js_class` attribute](js_class.html):
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(js_name = Foo)]
|
||||
pub struct JsFoo { /* ... */ }
|
||||
|
||||
#[wasm_bindgen(js_class = Foo)]
|
||||
impl JsFoo {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
# `readonly`
|
||||
|
||||
When attached to a `pub` struct field this indicates that it's read-only from
|
||||
JavaScript, and a setter will not be generated and exported to JavaScript.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen]
|
||||
pub fn make_foo() -> Foo {
|
||||
Foo {
|
||||
first: 10,
|
||||
second: 20,
|
||||
}
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
pub struct Foo {
|
||||
pub first: u32,
|
||||
|
||||
#[wasm_bindgen(readonly)]
|
||||
pub second: u32,
|
||||
}
|
||||
```
|
||||
|
||||
Here the `first` field will be both readable and writable from JS, but the
|
||||
`second` field will be a `readonly` field in JS where the setter isn't
|
||||
implemented and attempting to set it will throw an exception.
|
||||
|
||||
```js
|
||||
import { make_foo } from "./my_module";
|
||||
|
||||
const foo = make_foo();
|
||||
|
||||
// Can both get and set `first`.
|
||||
foo.first = 99;
|
||||
console.log(foo.first);
|
||||
|
||||
// Can only get `second`.
|
||||
console.log(foo.second);
|
||||
```
|
||||
@@ -0,0 +1,46 @@
|
||||
# `skip`
|
||||
|
||||
When attached to a `pub` struct field this indicates that field will not be exposed to JavaScript,
|
||||
and neither getter nor setter will be generated in ES6 class.
|
||||
|
||||
```rust
|
||||
use wasm_bindgen::prelude::*;
|
||||
|
||||
#[wasm_bindgen]
|
||||
pub struct Foo {
|
||||
pub bar: u32,
|
||||
|
||||
#[wasm_bindgen(skip)]
|
||||
pub baz: u32,
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
impl Foo {
|
||||
pub fn new() -> Self {
|
||||
Foo {
|
||||
bar: 1,
|
||||
baz: 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Here the `bar` field will be both readable and writable from JS, but the
|
||||
`baz` field will be `undefined` in JS.
|
||||
|
||||
```js
|
||||
import('./pkg/').then(rust => {
|
||||
let foo = rust.Foo.new();
|
||||
|
||||
// bar is accessible by getter
|
||||
console.log(foo.bar);
|
||||
// field marked with `skip` is undefined
|
||||
console.log(foo.baz);
|
||||
|
||||
// you can shadow it
|
||||
foo.baz = 45;
|
||||
// so accessing by getter will return `45`
|
||||
// but it won't affect real value in rust memory
|
||||
console.log(foo.baz);
|
||||
});
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
# `skip_typescript`
|
||||
|
||||
By default, Rust exports exposed to JavaScript will generate TypeScript definitions (unless `--no-typescript` is used). The `skip_typescript` attribute can be used to disable type generation per function, enum, struct, or field. For example:
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(skip_typescript)]
|
||||
pub enum MyHiddenEnum {
|
||||
One,
|
||||
Two,
|
||||
Three
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
pub struct MyPoint {
|
||||
pub x: u32,
|
||||
|
||||
#[wasm_bindgen(skip_typescript)]
|
||||
pub y: u32,
|
||||
}
|
||||
|
||||
#[wasm_bindgen]
|
||||
impl MyPoint {
|
||||
|
||||
#[wasm_bindgen(skip_typescript)]
|
||||
pub fn stringify(&self) -> String {
|
||||
format!("({}, {})", self.x, self.y)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Will generate the following `.d.ts` file:
|
||||
|
||||
```ts
|
||||
/* tslint:disable */
|
||||
/* eslint-disable */
|
||||
export class MyPoint {
|
||||
free(): void;
|
||||
x: number;
|
||||
}
|
||||
```
|
||||
|
||||
When combined with [the `typescript_custom_section` attribute](typescript_custom_section.html), this can be used to manually specify more specific function types instead of using the generated definitions.
|
||||
@@ -0,0 +1,31 @@
|
||||
# `start`
|
||||
|
||||
When attached to a `pub` function this attribute will configure the `start`
|
||||
section of the wasm executable to be emitted, executing the tagged function as
|
||||
soon as the wasm module is instantiated.
|
||||
|
||||
```rust
|
||||
#[wasm_bindgen(start)]
|
||||
pub fn main() {
|
||||
// executed automatically ...
|
||||
}
|
||||
```
|
||||
|
||||
The `start` section of the wasm executable will be configured to execute the
|
||||
`main` function here as soon as it can. Note that due to various practical
|
||||
limitations today the start section of the executable may not literally point to
|
||||
`main`, but the `main` function here should be started up automatically when the
|
||||
wasm module is loaded.
|
||||
|
||||
There's a few caveats to be aware of when using the `start` attribute:
|
||||
|
||||
* The `start` function must take no arguments and must either return `()` or
|
||||
`Result<(), JsValue>`
|
||||
* Only one `start` function can be placed into a module, including its
|
||||
dependencies. If more than one is specified then `wasm-bindgen` will fail when
|
||||
the CLI is run. It's recommended that only applications use this attribute.
|
||||
* The `start` function will not be executed when testing.
|
||||
* If you're experimenting with WebAssembly threads, the `start` function is
|
||||
executed *once per thread*, not once globally!
|
||||
* Note that the `start` function is relatively new, so if you find any bugs with
|
||||
it, please feel free to report an issue!
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user