-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathsource_map.format.txt
115 lines (93 loc) · 7.1 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
┏━━━━━━━━━━━━━━━━┓
┃ 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