Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/web-sys/unstable-apis.md

raw
1 # Unstable APIs
2
3 It's common for browsers to implement parts of a web API while the specification
4 for that API is still being written. The API may require frequent changes as the
5 specification continues to be developed, so the WebIDL is relatively unstable.
6
7 This causes some challenges for `web-sys` because it means `web-sys` would have
8 to make breaking API changes whenever the WebIDL changes. It also means that
9 previously published `web-sys` versions would be invalid, because the browser
10 API may have been changed to match the updated WebIDL.
11
12 To avoid frequent breaking changes for unstable APIs, `web-sys` hides all
13 unstable APIs through an attribute that looks like:
14
15 ```rust
16 #[cfg(web_sys_unstable_apis)]
17 pub struct Foo;
18 ```
19
20 By hiding unstable APIs through an attribute, it's necessary for crates to
21 explicitly opt-in to these reduced stability guarantees in order to use these
22 APIs. Specifically, these APIs do not follow semver and may break whenever the
23 WebIDL changes.
24
25 Crates can opt-in to unstable APIs at compile-time by passing the `cfg` flag
26 `web_sys_unstable_apis`. Typically the `RUSTFLAGS` environment variable is used
27 to do this. For example:
28
29 ```bash
30 RUSTFLAGS=--cfg=web_sys_unstable_apis cargo run
31 ```