fluencelabs/wasm-bindgen
1
0
Fork 0
mirror of https://github.com/fluencelabs/wasm-bindgen synced 2025-06-08 10:31:21 +00:00
Code Issues Projects Releases Wiki Activity
wasm-bindgen/guide/src/web-sys/supporting-more-web-apis.md

77 lines
3.2 KiB
Markdown
Raw Normal View History

Create the `web-sys` crate mechanically from WebIDL (#409) * Create a new `web-sys` crate This will eventually contain all the WebIDL-generated bindings to Web APIs. * ci: Test the new `web-sys` crate in CI * web-sys: Add a small README * web-sys: Vendor all the WebIDL files from mozilla-central * backend: Add a pass to remove AST items that use undefined imports This is necessary for the WebIDL frontend, which can't translate many WebIDL constructs into equivalent wasm-bindgen AST things yet. It lets us make incremental progress: we can generate bindings to methods we can support right now even though there might be methods on the same interface that we can't support yet. * webidl: Add a bunch of missing semicolons * webidl: Make parsing private It was only `pub` so that we could test it, but we ended up moving towards integration tests rather than unit tests that assert particular ASTs are parsed from WebIDL files. * webidl: Remove uses of undefined import types * test-project-builder: Build projects in "very verbose" mode This helps for debugging failing WebIDL-related tests. * test-project-builder: Add more profiling timers * test-project-builder: Detect when webpack-dev-server fails Instead of going into an infinite loop, detect when webpack-dev-server fails to start up and early exit the test. * webidl: Specify version for dev-dependency on wasm-bindgen-backend Instead of only a relative path. * guide: Add section about contributing to `web-sys` * WIP enable Event.webidl Still need to fix and finish the test. * Update expected webidl output * Start out a test's status as incomplete That way if we don't fill it in the error message doesn't look quite so bizarre * Fix onerror function in headless mode Otherwise we don't see any output! * Fix package.json/node_modules handling in project generation Make sure these are looked up in the git project root rather than the crate root * Avoid logging body text This was meant for debugging and is otherwise pretty noisy * Fix a relative path * More expected test fixes * Fix a typo * test-project-builder: Allow asynchronous tests * webidl: Convert [Unforgeable] attributes into `#[wasm_bindgen(structural)]` Fixes #432 * test-project-builder: Print generated WebIDL bindings for debugging purposes Helps debug bad WebIDL bindings generation inside tests. * When we can't find a descriptor, say which one can't be found This helps when debugging things that need to become structural. * web-sys: Test bindings for Event * ci: Use `--manifest-path dir` instead of `cd dir && ...` * web-sys: Just move .webidl files isntead of symlinking to enable them * tests: Polyfill Array.prototype.values for older browsers in CI * test-project-builder: Don't panic on poisoned headless test mutex We only use it to serialize headless tests so that we don't try to bind the port concurrently. Its OK to run another headless test if an earlier one panicked. * JsValue: Add {is,as}_{object,function} methods Allows dynamically casting values to `js::Object` and `js::Function`. * tidy: Fix whitespace and missing semicolons * Allow for dynamic feature detection of methods If we create bindings to a method that doesn't exist in this implementation, then it shouldn't fail until if/when we actually try and invoke that missing method. * tests: Do feature detection in Array.prototype.values test * Add JsValue::{is_string, as_js_string} methods And document all the cast/convert/check methods for js value. * eslint: allow backtick string literals * Only generate a fallback import function for non-structural imports
2018-07-09 16:35:25 -07:00
# Supporting More Web APIs in `web-sys`
1. <input type="checkbox"/> 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.
Try to enable all webidls (#573) * Try to enable all webidls * Separate out unavailable webidl files by reason. * Create record of fully tested WebIDL files * Update notes to reflect new situation with web-idl * Make a blank ident fail, disable the necessary widls. It turns out that all the blank idents came from blank enum variants, which is allowed in webidl apparently.
2018-07-30 00:07:19 +01:00
* 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.:
Create the `web-sys` crate mechanically from WebIDL (#409) * Create a new `web-sys` crate This will eventually contain all the WebIDL-generated bindings to Web APIs. * ci: Test the new `web-sys` crate in CI * web-sys: Add a small README * web-sys: Vendor all the WebIDL files from mozilla-central * backend: Add a pass to remove AST items that use undefined imports This is necessary for the WebIDL frontend, which can't translate many WebIDL constructs into equivalent wasm-bindgen AST things yet. It lets us make incremental progress: we can generate bindings to methods we can support right now even though there might be methods on the same interface that we can't support yet. * webidl: Add a bunch of missing semicolons * webidl: Make parsing private It was only `pub` so that we could test it, but we ended up moving towards integration tests rather than unit tests that assert particular ASTs are parsed from WebIDL files. * webidl: Remove uses of undefined import types * test-project-builder: Build projects in "very verbose" mode This helps for debugging failing WebIDL-related tests. * test-project-builder: Add more profiling timers * test-project-builder: Detect when webpack-dev-server fails Instead of going into an infinite loop, detect when webpack-dev-server fails to start up and early exit the test. * webidl: Specify version for dev-dependency on wasm-bindgen-backend Instead of only a relative path. * guide: Add section about contributing to `web-sys` * WIP enable Event.webidl Still need to fix and finish the test. * Update expected webidl output * Start out a test's status as incomplete That way if we don't fill it in the error message doesn't look quite so bizarre * Fix onerror function in headless mode Otherwise we don't see any output! * Fix package.json/node_modules handling in project generation Make sure these are looked up in the git project root rather than the crate root * Avoid logging body text This was meant for debugging and is otherwise pretty noisy * Fix a relative path * More expected test fixes * Fix a typo * test-project-builder: Allow asynchronous tests * webidl: Convert [Unforgeable] attributes into `#[wasm_bindgen(structural)]` Fixes #432 * test-project-builder: Print generated WebIDL bindings for debugging purposes Helps debug bad WebIDL bindings generation inside tests. * When we can't find a descriptor, say which one can't be found This helps when debugging things that need to become structural. * web-sys: Test bindings for Event * ci: Use `--manifest-path dir` instead of `cd dir && ...` * web-sys: Just move .webidl files isntead of symlinking to enable them * tests: Polyfill Array.prototype.values for older browsers in CI * test-project-builder: Don't panic on poisoned headless test mutex We only use it to serialize headless tests so that we don't try to bind the port concurrently. Its OK to run another headless test if an earlier one panicked. * JsValue: Add {is,as}_{object,function} methods Allows dynamically casting values to `js::Object` and `js::Function`. * tidy: Fix whitespace and missing semicolons * Allow for dynamic feature detection of methods If we create bindings to a method that doesn't exist in this implementation, then it shouldn't fail until if/when we actually try and invoke that missing method. * tests: Do feature detection in Array.prototype.values test * Add JsValue::{is_string, as_js_string} methods And document all the cast/convert/check methods for js value. * eslint: allow backtick string literals * Only generate a fallback import function for non-structural imports
2018-07-09 16:35:25 -07:00
```sh
cd crates/web-sys
Try to enable all webidls (#573) * Try to enable all webidls * Separate out unavailable webidl files by reason. * Create record of fully tested WebIDL files * Update notes to reflect new situation with web-idl * Make a blank ident fail, disable the necessary widls. It turns out that all the blank idents came from blank enum variants, which is allowed in webidl apparently.
2018-07-30 00:07:19 +01:00
git mv webidls/unavailable_enum_ident/MyWebApi.webidl webidls/enabled/MyWebApi.webidl
Create the `web-sys` crate mechanically from WebIDL (#409) * Create a new `web-sys` crate This will eventually contain all the WebIDL-generated bindings to Web APIs. * ci: Test the new `web-sys` crate in CI * web-sys: Add a small README * web-sys: Vendor all the WebIDL files from mozilla-central * backend: Add a pass to remove AST items that use undefined imports This is necessary for the WebIDL frontend, which can't translate many WebIDL constructs into equivalent wasm-bindgen AST things yet. It lets us make incremental progress: we can generate bindings to methods we can support right now even though there might be methods on the same interface that we can't support yet. * webidl: Add a bunch of missing semicolons * webidl: Make parsing private It was only `pub` so that we could test it, but we ended up moving towards integration tests rather than unit tests that assert particular ASTs are parsed from WebIDL files. * webidl: Remove uses of undefined import types * test-project-builder: Build projects in "very verbose" mode This helps for debugging failing WebIDL-related tests. * test-project-builder: Add more profiling timers * test-project-builder: Detect when webpack-dev-server fails Instead of going into an infinite loop, detect when webpack-dev-server fails to start up and early exit the test. * webidl: Specify version for dev-dependency on wasm-bindgen-backend Instead of only a relative path. * guide: Add section about contributing to `web-sys` * WIP enable Event.webidl Still need to fix and finish the test. * Update expected webidl output * Start out a test's status as incomplete That way if we don't fill it in the error message doesn't look quite so bizarre * Fix onerror function in headless mode Otherwise we don't see any output! * Fix package.json/node_modules handling in project generation Make sure these are looked up in the git project root rather than the crate root * Avoid logging body text This was meant for debugging and is otherwise pretty noisy * Fix a relative path * More expected test fixes * Fix a typo * test-project-builder: Allow asynchronous tests * webidl: Convert [Unforgeable] attributes into `#[wasm_bindgen(structural)]` Fixes #432 * test-project-builder: Print generated WebIDL bindings for debugging purposes Helps debug bad WebIDL bindings generation inside tests. * When we can't find a descriptor, say which one can't be found This helps when debugging things that need to become structural. * web-sys: Test bindings for Event * ci: Use `--manifest-path dir` instead of `cd dir && ...` * web-sys: Just move .webidl files isntead of symlinking to enable them * tests: Polyfill Array.prototype.values for older browsers in CI * test-project-builder: Don't panic on poisoned headless test mutex We only use it to serialize headless tests so that we don't try to bind the port concurrently. Its OK to run another headless test if an earlier one panicked. * JsValue: Add {is,as}_{object,function} methods Allows dynamically casting values to `js::Object` and `js::Function`. * tidy: Fix whitespace and missing semicolons * Allow for dynamic feature detection of methods If we create bindings to a method that doesn't exist in this implementation, then it shouldn't fail until if/when we actually try and invoke that missing method. * tests: Do feature detection in Array.prototype.values test * Add JsValue::{is_string, as_js_string} methods And document all the cast/convert/check methods for js value. * eslint: allow backtick string literals * Only generate a fallback import function for non-structural imports
2018-07-09 16:35:25 -07:00
```
2. <input type="checkbox"/> Verify that the `web-sys` crate still builds and
that its tests still pass with the new `.webidl` file enabled:
```sh
cd crates/web-sys
cargo build
cargo test
```
3. <input type="checkbox"/> Verify that bindings are being generated for your new
API by generating the documentation and searching for the new API in it:
```sh
cd crates/web-sys
cargo doc --open
# search for the new API in the opened docs
```
* <input type="checkbox"/> If the new API is **not** showing up in the docs,
Try to enable all webidls (#573) * Try to enable all webidls * Separate out unavailable webidl files by reason. * Create record of fully tested WebIDL files * Update notes to reflect new situation with web-idl * Make a blank ident fail, disable the necessary widls. It turns out that all the blank idents came from blank enum variants, which is allowed in webidl apparently.
2018-07-30 00:07:19 +01:00
rebuild the `web-sys` crate [with logging enabled](logging.html)
Create the `web-sys` crate mechanically from WebIDL (#409) * Create a new `web-sys` crate This will eventually contain all the WebIDL-generated bindings to Web APIs. * ci: Test the new `web-sys` crate in CI * web-sys: Add a small README * web-sys: Vendor all the WebIDL files from mozilla-central * backend: Add a pass to remove AST items that use undefined imports This is necessary for the WebIDL frontend, which can't translate many WebIDL constructs into equivalent wasm-bindgen AST things yet. It lets us make incremental progress: we can generate bindings to methods we can support right now even though there might be methods on the same interface that we can't support yet. * webidl: Add a bunch of missing semicolons * webidl: Make parsing private It was only `pub` so that we could test it, but we ended up moving towards integration tests rather than unit tests that assert particular ASTs are parsed from WebIDL files. * webidl: Remove uses of undefined import types * test-project-builder: Build projects in "very verbose" mode This helps for debugging failing WebIDL-related tests. * test-project-builder: Add more profiling timers * test-project-builder: Detect when webpack-dev-server fails Instead of going into an infinite loop, detect when webpack-dev-server fails to start up and early exit the test. * webidl: Specify version for dev-dependency on wasm-bindgen-backend Instead of only a relative path. * guide: Add section about contributing to `web-sys` * WIP enable Event.webidl Still need to fix and finish the test. * Update expected webidl output * Start out a test's status as incomplete That way if we don't fill it in the error message doesn't look quite so bizarre * Fix onerror function in headless mode Otherwise we don't see any output! * Fix package.json/node_modules handling in project generation Make sure these are looked up in the git project root rather than the crate root * Avoid logging body text This was meant for debugging and is otherwise pretty noisy * Fix a relative path * More expected test fixes * Fix a typo * test-project-builder: Allow asynchronous tests * webidl: Convert [Unforgeable] attributes into `#[wasm_bindgen(structural)]` Fixes #432 * test-project-builder: Print generated WebIDL bindings for debugging purposes Helps debug bad WebIDL bindings generation inside tests. * When we can't find a descriptor, say which one can't be found This helps when debugging things that need to become structural. * web-sys: Test bindings for Event * ci: Use `--manifest-path dir` instead of `cd dir && ...` * web-sys: Just move .webidl files isntead of symlinking to enable them * tests: Polyfill Array.prototype.values for older browsers in CI * test-project-builder: Don't panic on poisoned headless test mutex We only use it to serialize headless tests so that we don't try to bind the port concurrently. Its OK to run another headless test if an earlier one panicked. * JsValue: Add {is,as}_{object,function} methods Allows dynamically casting values to `js::Object` and `js::Function`. * tidy: Fix whitespace and missing semicolons * Allow for dynamic feature detection of methods If we create bindings to a method that doesn't exist in this implementation, then it shouldn't fail until if/when we actually try and invoke that missing method. * tests: Do feature detection in Array.prototype.values test * Add JsValue::{is_string, as_js_string} methods And document all the cast/convert/check methods for js value. * eslint: allow backtick string literals * Only generate a fallback import function for non-structural imports
2018-07-09 16:35:25 -07:00
and look for warning messages that mention your new API. Figure out why
bindings weren't generated and then add support to `wasm_bindgen_webidl` for
whatever is needed to generate your API's bindings.
Fix some links in the guide Closes #569
2018-07-27 08:48:10 -07:00
> You might find it helpful to view the generated rust bindings, to see if
Try to enable all webidls (#573) * Try to enable all webidls * Separate out unavailable webidl files by reason. * Create record of fully tested WebIDL files * Update notes to reflect new situation with web-idl * Make a blank ident fail, disable the necessary widls. It turns out that all the blank idents came from blank enum variants, which is allowed in webidl apparently.
2018-07-30 00:07:19 +01:00
> they are what you would expect. The file will be located at
> `target/wasm32-unknown-unknown/debug/build/web-sys-xxx/out/bindings.rs`,
> where `xxx` is a combinations of numbers and letters that represents your
> build. This file is pretty unintelligable until you run `rustfmt` on it, like
> `rustfmt target/wasm32-unknown-unknown/debug/build/web-sys-xxx/out/bindings.rs`.
> There are commented out lines in `web-sys/build.rs` that run rustfmt as part of
> the build process, and this can be very helpful for debugging as any error
> messages with inline code will display it in a readable format.
4. <input type="checkbox"/> Add tests for as many of the features in the WebIDL file
as possible to `crates/web-sys/tests/all/`. See the
[`web-sys` testing documentation](testing.html) for details.
> __Note__: Start here at __4__ if the WebIDL has already been added but doesn't have
> full test coverage, then go back to __3__ if you find any problems.
Create the `web-sys` crate mechanically from WebIDL (#409) * Create a new `web-sys` crate This will eventually contain all the WebIDL-generated bindings to Web APIs. * ci: Test the new `web-sys` crate in CI * web-sys: Add a small README * web-sys: Vendor all the WebIDL files from mozilla-central * backend: Add a pass to remove AST items that use undefined imports This is necessary for the WebIDL frontend, which can't translate many WebIDL constructs into equivalent wasm-bindgen AST things yet. It lets us make incremental progress: we can generate bindings to methods we can support right now even though there might be methods on the same interface that we can't support yet. * webidl: Add a bunch of missing semicolons * webidl: Make parsing private It was only `pub` so that we could test it, but we ended up moving towards integration tests rather than unit tests that assert particular ASTs are parsed from WebIDL files. * webidl: Remove uses of undefined import types * test-project-builder: Build projects in "very verbose" mode This helps for debugging failing WebIDL-related tests. * test-project-builder: Add more profiling timers * test-project-builder: Detect when webpack-dev-server fails Instead of going into an infinite loop, detect when webpack-dev-server fails to start up and early exit the test. * webidl: Specify version for dev-dependency on wasm-bindgen-backend Instead of only a relative path. * guide: Add section about contributing to `web-sys` * WIP enable Event.webidl Still need to fix and finish the test. * Update expected webidl output * Start out a test's status as incomplete That way if we don't fill it in the error message doesn't look quite so bizarre * Fix onerror function in headless mode Otherwise we don't see any output! * Fix package.json/node_modules handling in project generation Make sure these are looked up in the git project root rather than the crate root * Avoid logging body text This was meant for debugging and is otherwise pretty noisy * Fix a relative path * More expected test fixes * Fix a typo * test-project-builder: Allow asynchronous tests * webidl: Convert [Unforgeable] attributes into `#[wasm_bindgen(structural)]` Fixes #432 * test-project-builder: Print generated WebIDL bindings for debugging purposes Helps debug bad WebIDL bindings generation inside tests. * When we can't find a descriptor, say which one can't be found This helps when debugging things that need to become structural. * web-sys: Test bindings for Event * ci: Use `--manifest-path dir` instead of `cd dir && ...` * web-sys: Just move .webidl files isntead of symlinking to enable them * tests: Polyfill Array.prototype.values for older browsers in CI * test-project-builder: Don't panic on poisoned headless test mutex We only use it to serialize headless tests so that we don't try to bind the port concurrently. Its OK to run another headless test if an earlier one panicked. * JsValue: Add {is,as}_{object,function} methods Allows dynamically casting values to `js::Object` and `js::Function`. * tidy: Fix whitespace and missing semicolons * Allow for dynamic feature detection of methods If we create bindings to a method that doesn't exist in this implementation, then it shouldn't fail until if/when we actually try and invoke that missing method. * tests: Do feature detection in Array.prototype.values test * Add JsValue::{is_string, as_js_string} methods And document all the cast/convert/check methods for js value. * eslint: allow backtick string literals * Only generate a fallback import function for non-structural imports
2018-07-09 16:35:25 -07:00
Try to enable all webidls (#573) * Try to enable all webidls * Separate out unavailable webidl files by reason. * Create record of fully tested WebIDL files * Update notes to reflect new situation with web-idl * Make a blank ident fail, disable the necessary widls. It turns out that all the blank idents came from blank enum variants, which is allowed in webidl apparently.
2018-07-30 00:07:19 +01:00
5. <input type="checkbox"/> If all entities in the WebIDL file have full test coverage,
mark the WebIDL script in the `README.md` file as complete by changing `[ ]` to `[x]`.
Create the `web-sys` crate mechanically from WebIDL (#409) * Create a new `web-sys` crate This will eventually contain all the WebIDL-generated bindings to Web APIs. * ci: Test the new `web-sys` crate in CI * web-sys: Add a small README * web-sys: Vendor all the WebIDL files from mozilla-central * backend: Add a pass to remove AST items that use undefined imports This is necessary for the WebIDL frontend, which can't translate many WebIDL constructs into equivalent wasm-bindgen AST things yet. It lets us make incremental progress: we can generate bindings to methods we can support right now even though there might be methods on the same interface that we can't support yet. * webidl: Add a bunch of missing semicolons * webidl: Make parsing private It was only `pub` so that we could test it, but we ended up moving towards integration tests rather than unit tests that assert particular ASTs are parsed from WebIDL files. * webidl: Remove uses of undefined import types * test-project-builder: Build projects in "very verbose" mode This helps for debugging failing WebIDL-related tests. * test-project-builder: Add more profiling timers * test-project-builder: Detect when webpack-dev-server fails Instead of going into an infinite loop, detect when webpack-dev-server fails to start up and early exit the test. * webidl: Specify version for dev-dependency on wasm-bindgen-backend Instead of only a relative path. * guide: Add section about contributing to `web-sys` * WIP enable Event.webidl Still need to fix and finish the test. * Update expected webidl output * Start out a test's status as incomplete That way if we don't fill it in the error message doesn't look quite so bizarre * Fix onerror function in headless mode Otherwise we don't see any output! * Fix package.json/node_modules handling in project generation Make sure these are looked up in the git project root rather than the crate root * Avoid logging body text This was meant for debugging and is otherwise pretty noisy * Fix a relative path * More expected test fixes * Fix a typo * test-project-builder: Allow asynchronous tests * webidl: Convert [Unforgeable] attributes into `#[wasm_bindgen(structural)]` Fixes #432 * test-project-builder: Print generated WebIDL bindings for debugging purposes Helps debug bad WebIDL bindings generation inside tests. * When we can't find a descriptor, say which one can't be found This helps when debugging things that need to become structural. * web-sys: Test bindings for Event * ci: Use `--manifest-path dir` instead of `cd dir && ...` * web-sys: Just move .webidl files isntead of symlinking to enable them * tests: Polyfill Array.prototype.values for older browsers in CI * test-project-builder: Don't panic on poisoned headless test mutex We only use it to serialize headless tests so that we don't try to bind the port concurrently. Its OK to run another headless test if an earlier one panicked. * JsValue: Add {is,as}_{object,function} methods Allows dynamically casting values to `js::Object` and `js::Function`. * tidy: Fix whitespace and missing semicolons * Allow for dynamic feature detection of methods If we create bindings to a method that doesn't exist in this implementation, then it shouldn't fail until if/when we actually try and invoke that missing method. * tests: Do feature detection in Array.prototype.values test * Add JsValue::{is_string, as_js_string} methods And document all the cast/convert/check methods for js value. * eslint: allow backtick string literals * Only generate a fallback import function for non-structural imports
2018-07-09 16:35:25 -07:00
Try to enable all webidls (#573) * Try to enable all webidls * Separate out unavailable webidl files by reason. * Create record of fully tested WebIDL files * Update notes to reflect new situation with web-idl * Make a blank ident fail, disable the necessary widls. It turns out that all the blank idents came from blank enum variants, which is allowed in webidl apparently.
2018-07-30 00:07:19 +01:00
6. <input type="checkbox"/> Send a pull request! 😊
Reference in New Issue Copy Permalink