MozillaWiki

DevTools/Features/SourceMap: Difference between revisions

Page Discussion

DevTools/Features/SourceMap (view source)

Revision as of 18:22, 4 June 2013

1,400 bytes removed ,  4 June 2013
no edit summary
No edit summary
 
(36 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{| class="fullwidth-table"
{{FeatureStatus
|-
|Feature name=SourceMap
| style="font-weight: bold; background: #DDD;" | Feature
|Feature stage=Landed
| style="font-weight: bold; background: #DDD;" | Status
|Feature status=In progress
| style="font-weight: bold; background: #DDD;" | ETA
|Feature version=23
| style="font-weight: bold; background: #DDD;" | Owner
|Feature health=OK
|-
|Feature status note=Initial support landed in Firefox 23. Improvements coming down the pipe as always.
<section begin="status" />
}}
| [[DevTools/Features/SourceMap|Source Map]]
{{FeatureTeam
| {{StatusHealthy|status=planning}}
|Feature feature manager=Dave Camp
| 2011-06-01
|Feature lead engineer=Nick Fitzgerald
| Kevin Dangoor
|Feature qa lead=Vlad Maniac
<section end="status" />
}}
|-
{{FeaturePageBody
|}
|Feature overview=Nearly every web developer starts with JavaScript in one form during development and then produces JavaScript in another form for production use. Most often, this is a case of joining files together and minifying the output to reduce the number of requests the browser needs to make and how much data the browser needs to transfer. Another example of JavaScript starting in one form and ending up in the final form used by the browser is in PHP scripts which will sometimes generate bits of JavaScript as they generate their pages.
 
== Summary ==
 
Nearly every web developer starts with JavaScript in one form during development and then produces JavaScript in another form for production use. Most often, this is a case of joining files together and minifying the output to reduce the number of requests the browser needs to make and how much data the browser needs to transfer. Another example of JavaScript starting in one form and ending up in the final form used by the browser is in PHP scripts which will sometimes generate bits of JavaScript as they generate their pages.


When JavaScript gets an error, being able to help the web developer out by showing them where the error occurred in the original source file (PHP script or unminified, still-separate JavaScript for example) would save the developer time every single time they hit an error. The Web Console log messages also include links to the line that generated the log message, so these messages could link back to the original source lines as well.
When JavaScript gets an error, being able to help the web developer out by showing them where the error occurred in the original source file (PHP script or unminified, still-separate JavaScript for example) would save the developer time every single time they hit an error. The Web Console log messages also include links to the line that generated the log message, so these messages could link back to the original source lines as well.
Line 26: Line 22:


The solution to this problem is a mapping from the generated JS to the original source files.
The solution to this problem is a mapping from the generated JS to the original source files.
|Feature users and use cases=Case 1: Minified files


== Team ==
A user can take .js source files and compress them with the Closure Compiler. Errors and log messages in the Web Console will refer to the original .js files.
 
* '''Feature Manager''': ''Kevin Dangoor'' (irc: kdangoor)
* '''Lead Developer''': ''Nick Fitzgerald'' (irc: fitzgen)
* '''Web Console Contact''': ''David Dahl'' (irc: ddahl)
* '''SpiderMonkey Contact''': ''Jason Orendorff'' (irc: jorendorff)


== Release Requirements ==
Case 2: Languages which compile to JavaScript


* SpiderMonkey needs to output column in addition to source/line.
You can start with an original file which contains any language that compiles to JS (for example, CoffeeScript). Any logged output or uncaught errors will refer back to the original file, rather than the generated JS file which is actually being executed.
* When a sourcemap is available, error messages in console will link to the original source, not the generated JS
|Feature requirements=* When a sourcemap is available, error messages in console will link to the original source, not the generated JS
* Likewise, console log output will link back to the original source
* Likewise, console log output will link back to the original source
* Patches for CoffeeScript and UglifyJS will be used to produce examples
* Patches for CoffeeScript will be used to produce examples
* The Closure Compiler should generate compatible source maps
* A specification for generated scripts to refer to their mappings and a mapping format
* A specification for generated scripts to refer to their mappings and a mapping format
[[Link title]]
* SpiderMonkey needs to output column in addition to source/line.
 
* code that is loaded via eval() should also support sourcemaps
== Next Steps & Open Issues ==
|Feature non-goals=* Ideally, the source mapping file will also work for mapping LESS and similar to CSS. However, implementing the user interface for style source mapping is out of scope for this particular feature.
 
* It is possible to have a chain of source maps. Consider the case of a .coffee file that is compiled to .js and run through Closure Compiler. The final source map would refer to lines in the compiled JS, which would have a separate source map referring to lines in the .coffee file. For the first crack at this feature, we will not bother with that case.
* Decide if starting off without columns from SpiderMonkey is enough of a win to pursue this at this time
* console.trace does not need to be supported in the initial version
 
|Feature functional spec=I've written a web app called "Social Socialer Socialest". It's going to make me rich. I spent all morning creating it.
* How is the browser notified that a source map exists for a given script?
** Should it be a comment at the top of the source? Something like //@sourceMap=http://example.com/path/to/source/map
*** This could work with "eval" and script tag injection.
*** John J Barton has suggested that it is best to put the comment at the bottom of a script so that it can be dynamically added without shifting the existing line numbers for a script. I (fitzgen) agree with him.
** Should it be an attribute on the script's tag? Something like <script src='/path/to/foo.js' data-source-map='path/to/foo.smap'>
*** This would not work with eval, but would work with script tag injection.
** Should it just be implicit that the source map file is a replacement of the suffix of the script's file? For example, if a script's URL is "foo.js", the source map is implied to be at "foo.smap"?
*** This would not work with eval, but would work with script tag injection.
*** This would result in unnecessary HTTP requests when the source map does not exist.
** What is th URL pointing to the source map relative to?
*** The script itself, or the page loading the script?
 
* What requirements must be satisfied before the browser fetches a source map?
** Should the JavaScript engine be in debug-mode?
** Should a flag or preference be set?
** Should the console/firebug/debugger/etc have to flip a switch explicitly when they are started and flip it back off again when they exit?
 
* When should the browser fetch the source map?
** As soon as it knows of the existence of the source map?
** By the time a message is logged, or an exception is thrown, it is already too late to fetch the source map because we do not want to delay displaying a message while we go fetch the source map.
 
* When (if at all) should the browser fetch the original source file[s] referenced from a source map?
** As soon as it has retrieved the source map?
 
* From an API standpoint, how should the browser tell the JS debugger that a source map has been fetched and is available?
 
* Where are the original source files referenced from the source map?
** Presumably, they are URLs; what are they relative to?
*** The origin of the script?
*** The origin of the page?
 
* Where can source maps be located? Do we want to let script's say they come from any arbitrary place?
** Should they be restricted to the same origin as their script?
** Should they be restricted to the same origin as the webpage?
** From either of the above?
 
== Related Bugs & Dependencies ==
 
TBD (status page link)
 
* [https://bugzilla.mozilla.org/show_bug.cgi?id=568142 Bug 568142: Expand source notes to carry column information] - Bug to add line/col information to be available to debuggers.
 
* [https://bugzilla.mozilla.org/show_bug.cgi?id=618650 Bug 618650: map JS source coordinates to source language that was translated to JS]
 
* [https://bugzilla.mozilla.org/show_bug.cgi?id=626932 Bug 626932: Shrink JSParseNode] - Would add character-offset to SpiderMonkey (as opposed to line/col).
** Has an incomplete patch by njn. Doesn't compile.
 
* David Flanagan has been working on adding "//@line ###" style comment support to SpiderMonkey which is being tracked by [https://bugzilla.mozilla.org/show_bug.cgi?id=663934 this bug].
 
== Risks ==
 
* We could end up with two competing formats if other browsers pursue this at the same time and we're not aware of it.


== Designs ==
The app consists of 3 files:


TBD: link to mapping spec
* main.js (kicks off everything)
* socialgraph.js (everyone needs a social graph)
* nextgen.coffee (working on the next generation stuff already!)


This feature is related to the [[Script_Origin_Tracking|Script Origin Tracking proposal]], because the mapping should be able to accommodate the many ways in which JavaScript can come into existence on a page.
All three files contain a function with a console.log call and a statement that causes some sort of JS error.


== Test Plans ==
My build process joins and minifies main.js and socialgraph.js into a file called "s3.js" using the Closure Compiler with the option to generate a source map.


TBD
It compiles nextgen.coffee to nextgen.js, generating a source map in that process as well.


== Non-goals ==
There's also an HTML file. I haven't learned CSS yet, but I've bought a book.


* Ideally, the source mapping file will also work for mapping LESS and similar to CSS. However, implementing the user interface for style source mapping is out of scope for this particular feature.
The HTML file loads s3.js and nextgen.js.


== Other Stuff ==
Only l33t folks can use my app. So, I fire up the Web Console and call the functions from the 3 files by hand. In each case, I should see the log output and error message refer to the original files.


* Brendan and Jim Blandy have suggested that using a separate mapping file will work better than including the mapping in the generated source.
When I hover over the link to the source files, I should be presented with a link to the .js file that the browser executed as well.


* A [https://bugs.webkit.org/show_bug.cgi?id=60550 bug with a patch] was opened for WebKit but closed INVALID.
** Webkit has [https://bugs.webkit.org/show_bug.cgi?id=30933 another bug] open for this feature.


=== Note about source map loading ===


__NOTOC__
When an error is first generated, the source maps have not yet been loaded. That means that the Web Console cannot immediately display the mapped error info. Once an error is hit, however, the map should be loaded and the error message should be updated as soon as possible to contain the mapped info.
|Feature ux design=[[File:SourceMapInConsole.png|Source mapped output in the Web Console]]
|Feature implementation notes=* {{bug|771597}} - Source maps + debugger meta bug


[[Category:Features]]
[https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit The source map file format specification]
[[Category:Firefox]]
}}
[[Category:DevTools]]
{{FeatureInfo
|Feature priority=P3
|Feature rank=3
|Feature roadmap=Developer Tools
|Feature list=Desktop
|Feature engineering team=DevTools
}}
{{FeatureTeamStatus
|Feature security status=sec-review-complete
|Feature security health=OK
|Feature security notes=Complete: 2011.08.24 [[Security/Reviews/Firefox9/ReviewNotes/SourceMap|Notes]]
}}
Fitzgen
Confirmed users
125

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/324479...663285"