| 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 |
``` |