JavaScript Source Map Detailed

Last week, JQuery 1.9 was released.

This is the last new version prior to version 2.0, with a number of new features, one of which is support for source Map.

To access Http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js, open the compressed version, scroll to the bottom, and you can see that the last line is this:

@ sourcemappingurl=jquery.min.map

This is the source Map. It is a standalone map file, and in the same directory as the source code, you can click inside to see what it looks like.

This is a very useful feature and this article will explain this feature in detail.

First, from the source of the conversion to talk about

JavaScript scripts are becoming more and more complex. Most of the source code (especially the various libraries and frameworks) has to be transformed before it can be put into production.

Common source code conversion, mainly the following three kinds of situations:

(1) Compress, reduce the volume. For example, jquery 1.9 source code, before compression is 252KB, compression is 32KB.

(2) Multiple file merges, reducing the number of HTTP requests.

(3) Other languages compiled into JavaScript. The most common example is coffeescript.

In all three cases, the code that actually runs is different from the development code, which makes debugging difficult.

In general, the JavaScript interpreter will tell you that the first few lines of code are in error. However, this is useless for the converted code. For example, JQuery 1.9 compresses only 3 rows, 30,000 characters per line, and all internal variables are renamed. You look at the error message, feel no clue, do not know where it corresponds to the original location.

This is the problem that source map wants to solve.

Ii. What is source map

Simply put, the Source map is an information file that stores the location information. That is, each position of the converted code, corresponding to the position before the conversion.

With it, when the error occurs, the Debug tool will display the original code directly, not the converted code. This undoubtedly brings great convenience to the developers.

Currently, only chrome browsers support this feature for the time being. In the setting settings for Developer tools, verify that Enable source maps is selected.

Third, how to enable the source map

As mentioned earlier, as long as the end of the converted code, add a line.

@ sourcemappingurl=/path/to/file.js.map

The map file can be placed on the network or on a local file system.

Iv. how to generate a source map

The most common approach is to use Google's closure compiler.

The format of the build command is as follows:

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 meanings of each parameter are as follows:

-JS: Pre-conversion code file
-Create_source_map: Generated source Map file
-Source_map_format:source map version, the current use of V3.
-Js_output_file: The converted code file.

Other methods of generation can refer to this article.

V. Format of the Source map

Open the source map file, which is probably what it looks like:

{
Version:3,
File: "Out.js",
SourceRoot: "",
Sources: ["Foo.js", "Bar.js"],
Names: ["src", "Maps", "is", "fun"],
Mappings: "Aagbc,saaq,caaea"
}

The entire file is a JavaScript object that can be read by the interpreter. It mainly has the following properties:

-Version:source map version, currently 3.

-file: the converted filename.

-SourceRoot: The directory where the pre-converted files are located. If the file is in the same directory as the pre-transform, the entry is empty.

-Sources: The file before the conversion. The item is an array that indicates that multiple file merges may exist.

-Names: All variable names and property names before conversion.

-Mappings: A string that records location information, described in detail below.

Vi.. Mappings Properties

Here's a really interesting part: how one by one corresponds to each of the two files.

The key is the mappings property of the map file. This is a very long string, it is divided into three layers.

The first layer is the line corresponding to the semicolon (;), each semicolon corresponds to the converted source line. So, the content before the first semicolon corresponds to the first line of the source code, and so on.

The second layer is the position corresponding to the comma (,), each comma corresponds to a location of the source code after the conversion. So, the first comma before the content, corresponding to the line source of the first location, and so on.

The third layer is the position conversion , which is represented by the VLQ code, which represents the location of the pre-conversion source of the position.

For example, assume that the contents of the Mappings property are as follows:

Mappings: "AAAAA,BBBBB; CCCCC "

means that the converted source code is divided into two lines, the first line has two positions, and the second row has a position.

Seven, the principle of position correspondence

Each location uses a five-bit, representing five fields.

Counting from the left,

-The first bit, which indicates the column of this position in the (converted code).

-second bit, indicating which file in the sources attribute this location belongs to.

-The third bit, which indicates that this position belongs to the first line of the pre-conversion code.

-The fourth bit, which indicates that this position belongs to the first column of the pre-conversion code.

-The fifth bit, which indicates which of the variables in the names attribute this position belongs to.

There are a few points to note. First, all of the values are based on a base of 0. Second, the fifth bit is not required, and if the position does not have a variable in the corresponding names attribute, you can omit the fifth bit. Again, each bit is represented by a VLQ code; Since VLQ encoding is long, each bit can be composed of multiple characters.

If a location is AAAAA, because a is represented in the VLQ encoding of 0, the five bits in this position are actually 0. It means that the position is in the No. 0 column of the converted code, corresponding to the No. 0 file in the sources attribute, which belongs to the No. 0 row No. 0 column of the pre-conversion code, corresponding to the NO. 0 variable in the Names property.

Eight, VLQ code

Finally, we talk about how to use VLQ coding to represent numerical values.

This encoding was first used for MIDI files and later used in many formats. It is characterized by the ability to represent very large numbers very thinly.

The VLQ encoding is variable-length. If the (integer) value is between 15 and +15 (with two endpoints), it is represented by a character, and beyond this range, multiple characters are required. It specifies that each character uses 6 binary bits, which can be borrowed from a base 64 encoded character set.

In these 6 bits, the first bit (highest bit) on the left indicates whether "continuous" (continuation). If it is 1, the 6 bits that follow the 6 bits also belong to the same number, and if it is 0, the value is the end of the 6 bits.

Continuation
| Sign
| |
V V
101011

The meaning of the last (lowest bit) of the right side of these 6 bits depends on whether the 6 bits are the first character of the VLQ encoding of a numeric value. If yes, this bit represents "sign", 0 is positive, 1 is negative (the symbol for Source map is fixed to 0); If not, the bit has no special meaning and is counted as part of the value.

Nine, VLQ code: Example

Here is an example of how to encode the value 16 VLQ.

The first step is to rewrite 16 into binary form 10000.

The second step, on the far right, complements the sign bit. Since 16 is greater than 0, the sign bit is 0 and the entire number becomes 100000.

The third step, starting from the lowest bit on the right, is to segment the entire number every 5 bits, which becomes 1 and 2 segments. If the highest bit is in less than 5 bits, the front is 0, so the two segments become 00001 and 00000.

The fourth step is to reverse the order of two paragraphs, i.e. 00000 and 00001.

Fifth step, add a "continuous bit" at the top of each paragraph, except the last paragraph is 0, the others are 1, which becomes 100000 and 000001.

Sixth step, turn each section into a base 64 encoding.

The table indicates that 100000 is g,000001 B. Therefore, the VLQ encoding of the value 16 is GB. The above process, seems to be very complex, it is actually very simple, specific implementation please see the official Base64-vlq.js file, which has detailed comments.

X. Reference links

-Introduction to JavaScript Source Maps
-Source MAP Revision 3 proposal

Finish

JavaScript Source Map detailed