Last week jQuery 1.9 was released. This is the last release before jQuery 2.0. It adds many new functions, one of them is the source map.
By accessing http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js , you can scroll to the last line and you will see below line :
　//@ sourceMappingURL=jquery.min.map
This is source map, it is a separate file and it is put at the same directory as the source file. You can click here and see what it looks like. It's an very useful function, we will talk more about it here.
1. Start from source code transformation
JavaScript source codes now become more and more complex, many source codes(including function libraries and frameworks) need to be transformed before they can be put into production environment.
There are three common source code transformation modes:
- Compression, reduce the size of the source file. For example, source code of jQuery 1.9 is 252KB before compression, after compression, it becomes 32KB.
- Merge multiple files to reduce HTTP requests
- Other languages converts to JavaScript, the most common example is CoffeeScript.
All these three modes make the actual codes different from the production codes. It makes the debug more difficult.
Usually JavaScript interpreter will tell you which line and which column the error is, but this is useless for the codes which are transformed. For example, jQuery 1.9 source codes have only 3 lines after compression, each line has 30000 characters. All variable names are changed as well, so it's no use to see the error message from the JavaScript, you will not know where the error is in the source code.
This is what source map saves you.
2. What's source map
In short source map is an info file which stores the location information, i.e, the mapping between every position of code after transformation and the position of the code before transformation. With this, the debugger will tell where the error is in the source code before transformation.
As of now only Chrome supports this capability, you can enable it by going to Developer Tools->Setting->"Enable source maps".
3. How to enable source map
You only need to add the below line at the last line of the code after transformation.
　//@ sourceMappingURL=/path/to/file.js.map
The map file can be put on the internet or in the local system.
4. How to generate source map
The commonly used method is to use Google's Closure compiler.
The command to generate map is:
　 　java -jar compiler.jar \
　　　　--js script.js \
　　　　--create_source_map ./script-min.js.map \
　　　　--source_map_format=V3 \
　　　　--js_output_file script-min.js
The meaning of the parameters are:
--js : The source code file before transformation
--create_source_map : The generated source map file
--source_map_format :The version of the source map, now all use the V3 version
--js_output_file : The source code file after transformation
Other ways to generate source map can be referred here.
5. The format of the source map
The source map file looks like:
　　{
　　　　version : 3,
　　　　file: "out.js",
　　　　sourceRoot : "",
　　　　sources: ["foo.js", "bar.js"],
　　　　names: ["src", "maps", "are", "fun"],
　　　　mappings: "AAgBC,SAAQ,CAAEA"
　　}
The whole file is an object, it can be parsed by the interpreter. The properties are:
　　- version：Source map version, now it is 3
　　- file：file name after conversion
　　- sourceRoot：The directory where the source code file is before transformation.
　　- sources：Files before transformation, it is an array which may contain more than one file
　　- names：All variable names and properties before transformation
　　- mappings：A string which records the location information.
6. mappings property
This is the real interesting part. How are the locations in the two files mapped?
It depends on the mappings property. The mappings property has three layers:
- Line mapping : It is expressed with (;), each : separated one line of source code after transformation. The content before the first : means the first line of the source code.
- Position mapping : It is expressed with (,), each comma maps to one location of the source code after transformation. The content before the first comma represents the source code in the first position.
- Position conversion : Represented by VLQ code, it represents the position of the transformed file in the original source file.
For example, if the mappings property is like :
mappings:"AAAAA,BBBBB;CCCCC"
It means the transformed source code has two lines, the first line has two positions and the second line has only one position.
7. How position mapping works
Each position has 5 characters.Starting from left:
- First，It means which column is the current position in after transformation。
　　- Second : Which file is the position in the sources
　　- Third，Which line is this position in before transformation
　　- Fourth，Which column is this position in before transformation
　　- Fifth, which variables is this position in names property.
8 References
- Introduction To JavaScript Source Maps
　　- Source Map Revision 3 Proposal
Author : 阮一峰Source : http://www.ruanyifeng.com/blog/2013/01/javascript_source_map.html
