-
Notifications
You must be signed in to change notification settings - Fork 16
/
source_map.format.txt
137 lines (103 loc) · 8.79 KB
/
source_map.format.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
SOURCE_MAP
VERSION ==> #18/11/2013 (revision 3 proposal)
PREVIOUS REVISION ==> #Previous changes of revision 3:
# - //@ and /* @ instead of //# and /* #
# - no sourcesContent
# - X-SourceMap [S] instead of SourceMap [S]
#Revision 2 and 1 not documented because too different
GOAL ==> #Map positions and variable names compiled file <-> source file
#Reason: allowing to debug compiled file using source file
#Can:
# - be inlined ("inline source map") or a separate file
# - be concatenated ("index map")
# - work with multi-stage compilation ("multi-level map")
/=+===============================+=\
/ : : \
)==: FORMAT :==(
\ :_______________________________: /
\=+===============================+=/
FORMAT ==> #JSON
URI #Can be relative (i.e. looks like a Unix PATH)
version #3 (required)
sources #Source files' 'SOURCE_URI'_ARR
#If relative, relative to sourceRoot
sourceRoot #Source files' 'BASE_URI'
#If relative, relative to source map's file
#Def: source map's file
sourcesContent #Source files' STR|null_ARR: like "sources" but inline
#Index corresponds to index within "sources"
names #Source files' 'SOURCE_CODE'_ARR (usually mostly identifiers)
file #Compiled file's 'COMPILED_FILENAME'
mappings #MAPPINGS (required)
x_* #Extensions
x_google_linecount #Source files number of lines
/=+===============================+=\
/ : : \
)==: MAPPINGS :==(
\ :_______________________________: /
\=+===============================+=/
MAPPINGS #Map each position within compiled file to a position (and 'SOURCE_CODE') within source file
#A MAPPINGS is ;-separated into GROUPs
GROUP #A line in source file
#A GROUP is ,-separated into SEGMENTs
SEGMENT #A variable name/position
#Is a VLQ_INT_ARR ("fields") of length 1|4|5
#Fields:
# - represents "position" of:
# 0) index in compiled file
# 1) source file among "sources"
# 2) line in source file (1-based)
# 3) column in the source line (0-based)
# 4) the 'SOURCE_CODE' name among source "names"
# - only 0) is required
#Each "position" is relative offset to last field:
# - unless it is the first occurence, in which case it is absolute position
# - for segment 0) it also is absolute position for first segment of each group
# - can be negative offset, e.g. when returning to line 1 on new source file,
# or returning to column 0 on new line
#VLQ_INT is a 32 bits signed integer, encoded using source map's VLQ (see its doc)
/=+===============================+=\
/ : : \
)==: INDEX MAP :==(
\ :_______________________________: /
\=+===============================+=/
INDEX MAP ==> #When concatenating several "sections" (source files + compiled file + source map) into a single bundled file
#Can be used the same way as source maps
version #3
file #Index map's 'SOURCEMAP_FILENAME'
sections #OBJ_ARR
#Must be sorted by position and not overlap.
sections.*.line|column #Position within the bundled file
sections.*.url #URL of the source map
#Resolved the same way as "sources" and "sourceRoot"
sections.*.map #Same but inlined, i.e. OBJ of the source map
/=+===============================+=\
/ : : \
)==: LOCATION :==(
\ :_______________________________: /
\=+===============================+=/
SOURCE MAP LOCATION ==> #Can be:
# - comment "# sourceMappingURL=SOURCEMAP_URI" at end of compiled file
# - should use format's comment marker, e.g. //# ... for JavaScript, /* */ for CSS
# - when not data URI, often sibling file to the compiled file with '.map' appended
# - SourceMap: SOURCEMAP_URI [S] HTTP header
#SOURCEMAP_URI is relative to (in priority):
# - <script src>
# - comment "# sourceURL=URL"
# - should be "foo.js" if there is no file (e.g. generated with eval())
# - URL will also be used as FILE in ERROR.stack
# - parent page's URL
INLINE SOURCE MAP ==> #Using a SOURCEMAP_URI data URI + sourceContents + sections.*.map
#Data URI usually use JSON MIME, UTF-8 and base64
/=+===============================+=\
/ : : \
)==: MULTI-LEVEL MAPPING :==(
\ :_______________________________: /
\=+===============================+=/
MULTI-LEVEL MAPPING ==> #When there are several compilation stages, e.g. TypeScript + Minification
#Possible solutions:
# - single source map from last compiled file to source file
# - single source map from last compiled file to intermediary compiled file
# - several source maps for each stage