Skip to content

Commit 9ef0547

Browse files
timothy-kingtimothy-king
committed
internal/gcimporter: move indexed format docs
Move the documentation for indexed export data format from $GOROOT/src/cmd/compile/internal/typecheck/iexport.go to x/tools/internal/gcimporter/iexport.go . This is the only current writer of this format. Updates golang/go#68778 Updates golang/go#68898 Change-Id: I365f56315d03affc5860cf407ea6e3d0caa1a88e Reviewed-on: https://go-review.googlesource.com/c/tools/+/607495 LUCI-TryBot-Result: Go LUCI <[email protected]> Reviewed-by: Robert Findley <[email protected]> Reviewed-by: Alan Donovan <[email protected]>
1 parent c7adb63 commit 9ef0547

File tree

2 files changed

+222
-4
lines changed

2 files changed

+222
-4
lines changed

‎internal/gcimporter/iexport.go

Lines changed: 221 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,227 @@
22
// Use of this source code is governed by a BSD-style
33
// license that can be found in the LICENSE file.
44

5-
// Indexed binary package export.
6-
// This file was derived from $GOROOT/src/cmd/compile/internal/gc/iexport.go;
7-
// see that file for specification of the format.
5+
// Indexed package export.
6+
//
7+
// The indexed export data format is an evolution of the previous
8+
// binary export data format. Its chief contribution is introducing an
9+
// index table, which allows efficient random access of individual
10+
// declarations and inline function bodies. In turn, this allows
11+
// avoiding unnecessary work for compilation units that import large
12+
// packages.
13+
//
14+
//
15+
// The top-level data format is structured as:
16+
//
17+
// Header struct {
18+
// Tag byte // 'i'
19+
// Version uvarint
20+
// StringSize uvarint
21+
// DataSize uvarint
22+
// }
23+
//
24+
// Strings [StringSize]byte
25+
// Data [DataSize]byte
26+
//
27+
// MainIndex []struct{
28+
// PkgPath stringOff
29+
// PkgName stringOff
30+
// PkgHeight uvarint
31+
//
32+
// Decls []struct{
33+
// Name stringOff
34+
// Offset declOff
35+
// }
36+
// }
37+
//
38+
// Fingerprint [8]byte
39+
//
40+
// uvarint means a uint64 written out using uvarint encoding.
41+
//
42+
// []T means a uvarint followed by that many T objects. In other
43+
// words:
44+
//
45+
// Len uvarint
46+
// Elems [Len]T
47+
//
48+
// stringOff means a uvarint that indicates an offset within the
49+
// Strings section. At that offset is another uvarint, followed by
50+
// that many bytes, which form the string value.
51+
//
52+
// declOff means a uvarint that indicates an offset within the Data
53+
// section where the associated declaration can be found.
54+
//
55+
//
56+
// There are five kinds of declarations, distinguished by their first
57+
// byte:
58+
//
59+
// type Var struct {
60+
// Tag byte // 'V'
61+
// Pos Pos
62+
// Type typeOff
63+
// }
64+
//
65+
// type Func struct {
66+
// Tag byte // 'F' or 'G'
67+
// Pos Pos
68+
// TypeParams []typeOff // only present if Tag == 'G'
69+
// Signature Signature
70+
// }
71+
//
72+
// type Const struct {
73+
// Tag byte // 'C'
74+
// Pos Pos
75+
// Value Value
76+
// }
77+
//
78+
// type Type struct {
79+
// Tag byte // 'T' or 'U'
80+
// Pos Pos
81+
// TypeParams []typeOff // only present if Tag == 'U'
82+
// Underlying typeOff
83+
//
84+
// Methods []struct{ // omitted if Underlying is an interface type
85+
// Pos Pos
86+
// Name stringOff
87+
// Recv Param
88+
// Signature Signature
89+
// }
90+
// }
91+
//
92+
// type Alias struct {
93+
// Tag byte // 'A' or 'B'
94+
// Pos Pos
95+
// TypeParams []typeOff // only present if Tag == 'B'
96+
// Type typeOff
97+
// }
98+
//
99+
// // "Automatic" declaration of each typeparam
100+
// type TypeParam struct {
101+
// Tag byte // 'P'
102+
// Pos Pos
103+
// Implicit bool
104+
// Constraint typeOff
105+
// }
106+
//
107+
// typeOff means a uvarint that either indicates a predeclared type,
108+
// or an offset into the Data section. If the uvarint is less than
109+
// predeclReserved, then it indicates the index into the predeclared
110+
// types list (see predeclared in bexport.go for order). Otherwise,
111+
// subtracting predeclReserved yields the offset of a type descriptor.
112+
//
113+
// Value means a type, kind, and type-specific value. See
114+
// (*exportWriter).value for details.
115+
//
116+
//
117+
// There are twelve kinds of type descriptors, distinguished by an itag:
118+
//
119+
// type DefinedType struct {
120+
// Tag itag // definedType
121+
// Name stringOff
122+
// PkgPath stringOff
123+
// }
124+
//
125+
// type PointerType struct {
126+
// Tag itag // pointerType
127+
// Elem typeOff
128+
// }
129+
//
130+
// type SliceType struct {
131+
// Tag itag // sliceType
132+
// Elem typeOff
133+
// }
134+
//
135+
// type ArrayType struct {
136+
// Tag itag // arrayType
137+
// Len uint64
138+
// Elem typeOff
139+
// }
140+
//
141+
// type ChanType struct {
142+
// Tag itag // chanType
143+
// Dir uint64 // 1 RecvOnly; 2 SendOnly; 3 SendRecv
144+
// Elem typeOff
145+
// }
146+
//
147+
// type MapType struct {
148+
// Tag itag // mapType
149+
// Key typeOff
150+
// Elem typeOff
151+
// }
152+
//
153+
// type FuncType struct {
154+
// Tag itag // signatureType
155+
// PkgPath stringOff
156+
// Signature Signature
157+
// }
158+
//
159+
// type StructType struct {
160+
// Tag itag // structType
161+
// PkgPath stringOff
162+
// Fields []struct {
163+
// Pos Pos
164+
// Name stringOff
165+
// Type typeOff
166+
// Embedded bool
167+
// Note stringOff
168+
// }
169+
// }
170+
//
171+
// type InterfaceType struct {
172+
// Tag itag // interfaceType
173+
// PkgPath stringOff
174+
// Embeddeds []struct {
175+
// Pos Pos
176+
// Type typeOff
177+
// }
178+
// Methods []struct {
179+
// Pos Pos
180+
// Name stringOff
181+
// Signature Signature
182+
// }
183+
// }
184+
//
185+
// // Reference to a type param declaration
186+
// type TypeParamType struct {
187+
// Tag itag // typeParamType
188+
// Name stringOff
189+
// PkgPath stringOff
190+
// }
191+
//
192+
// // Instantiation of a generic type (like List[T2] or List[int])
193+
// type InstanceType struct {
194+
// Tag itag // instanceType
195+
// Pos pos
196+
// TypeArgs []typeOff
197+
// BaseType typeOff
198+
// }
199+
//
200+
// type UnionType struct {
201+
// Tag itag // interfaceType
202+
// Terms []struct {
203+
// tilde bool
204+
// Type typeOff
205+
// }
206+
// }
207+
//
208+
//
209+
//
210+
// type Signature struct {
211+
// Params []Param
212+
// Results []Param
213+
// Variadic bool // omitted if Results is empty
214+
// }
215+
//
216+
// type Param struct {
217+
// Pos Pos
218+
// Name stringOff
219+
// Type typOff
220+
// }
221+
//
222+
//
223+
// Pos encodes a file:line:column triple, incorporating a simple delta
224+
// encoding scheme within a data object. See exportWriter.pos for
225+
// details.
8226

9227
package gcimporter
10228

‎internal/gcimporter/iimport.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
// license that can be found in the LICENSE file.
44

55
// Indexed package import.
6-
// See cmd/compile/internal/gc/iexport.go for the export data format.
6+
// See iexport.go for the export data format.
77

88
// This file is a copy of $GOROOT/src/go/internal/gcimporter/iimport.go.
99

0 commit comments

Comments
 (0)