diff --git a/FutureFeatures.md b/FutureFeatures.md index d2c90897..ebc9d958 100644 --- a/FutureFeatures.md +++ b/FutureFeatures.md @@ -148,16 +148,6 @@ instance. However, operators with 32-bit indices and operators with 64-bit indices will be given separate names to leave open the possibility of supporting both in the same instance in the future. -### Source maps integration - -* Add a new source maps [module section type](MVP.md#module-structure). -* Either embed the source maps directly or just a URL from which source maps can - be downloaded. -* Text source maps become intractably large for even moderate-sized compiled - codes, so probably need to define new binary format for source maps. -* Gestate ideas and start discussions at the - [Source Map RFC repository](https://github.com/source-map/source-map-rfc/issues) - ### Coroutines Coroutines will [eventually be part of C++][] and is already popular in other diff --git a/Web.md b/Web.md index b59f5ae9..2a110536 100644 --- a/Web.md +++ b/Web.md @@ -299,6 +299,86 @@ Transcoding failure is detected by `decodeURIComponent`, which may throw `URIError`. If it does, the WebAssembly module will not validate. This validation rule is only mandatory for Web embedding. +## Source Maps for WebAssembly files on the web + +### Background +[Source maps](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k) +are a debug-information format used on the web, generated by toolchains that target +JavaScript, either from other languages (e.g. TypeScript, Emscripten) or from +JavaScript itself (e.g. Closure, minifiers). A browser that supports source maps +can display the original source in its developer tools instead of the compiled +JavaScript that the VM actually executes. It can support setting breakpoints +specified as source lines, single-stepping through source lines, and showing +source lines in stack traces; however it cannot support getting or setting +variables from the original source code because the format is not "full" debug +info: it only maps locations from the compiled code back to locations in the +source files (where a generated-code location consists of a line and column +number, and a source location consists of file, line, and column). Generated +files use a specially-formatted comment to specify a URL for a source map that +describes the file. + +Source maps can be made to serve the same purpose for WebAssembly binary files, +allowing parity with asm.js. By re-using an existing standard, browsers can +take advantage of their existing source map support without having to make +significant changes to their developer tools. + + +### Alternatives + +An alternative method is to specify location mapping information in some way +other than source maps. For example, it could be encoded directly into the WebAssembly +binary the way function and local names are written in the "name" section. This +is more convenient if the VM itself uses the information (for example to +generate a stack trace). However existing developer tools implementations are +designed around the source map model of passing a URL from the VM to the dev +tools code, which fetches and interprets the information. Therefore it is +expected that it will be much simpler to use "real" source maps than to design +another format. + +Source maps also have known limitations (e.g. source variables cannot be +described). A complete debug info format will eventually be needed; however the +intention of this specification is to allow for easy integration with existing +developer tools implementations in browsers. + + +### Spec + +With few exceptions, most aspects of the source map +[spec](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/) +may be applied directly to WebAssembly. +Because WebAssembly is a binary format (and thus does not have lines and columns, or +comments per se), some simple reinterpretation of concepts is needed. + +#### Locations + +Source maps specify how to map a (zero-based) line and column position in +generated code to a file, line, and column location in the source. For +WebAssembly binary locations, the line number is always 1, and the column number +is interpreted as a byte offset into the WebAssembly binary content (this results +in a more efficient encoding than using the line number instead). +Source locations are interpreted as in the source map spec. + +#### Linking generated code to source maps + +When the generated code is JavaScript, it includes a specially-formatted line +at the end, which is the URL of the associated source map. For WebAssembly, a custom +section named `"sourceMappingURL"` contains the URL. +The URL is represented and encoded as defined in the WHATWG +[URL spec](https://url.spec.whatwg.org). +If the URL is not absolute, then: +* If the wasm module is associated with an HTTP response (e.g. the +compileStreaming or instantiateStreaming +[APIs](#additional-web-embedding-api) are used), then it is resolved relative to +the URL of the response. +* Otherwise it is relative to the page's origin. + +For wasm modules with an associated HTTP response (e.g. those using +the compileStreaming or instantiateStreaming +[APIs](#additional-web-embedding-api)) the source map URL may also be specified +using the `SourceMap:` HTTP header as with JavaScript source maps. + + + ## Security WebAssembly's [security](Security.md) model should depend on the