1This file describes some of the typecheckers internal organization and conventions.
2It is not meant to be complete; rather it is a living document that will be updated
3as needed.
4
5Read this file first before starting to make changes in the code.
6
7#
8### Overall organization
9
10There are two almost identical typecheckers:
11
12- cmd/compile/internal/types2 (or types2 for short)
13- go/types
14
15types2 is internal and used by the compiler.
16go/types is the std library typechecker and its API must remain strictly
17backward-compatible.
18The types2 API closely matches the go/types API but may not have some
19deprecated functions anymore (which we need to maintain in go/types).
20
21They differ primarily in what syntax tree they operate on:
22
23- types2 uses the syntax tree defined by cmd/compile/internal/syntax
24- go/types uses the syntax tree defined by go/ast
25
26We aim to keep the respective sources very closely in sync.
27**Any change will need to be made to both typechecker source bases**.
28
29Many go/types files can be generated automatically from the
30corresponding types2 sources.
31This is done via a generator (go/types/generate_test.go) which may be invoked via
32`go generate` in the go/types directory.
33Generated files are clearly marked with a comment at the top and should not
34be modified by hand.
35For this reason, it is usually best to make changes to the types2 sources first.
36The changes only need to be ported by hand for the go/types files that cannot
37be generated yet.
38
39New files may be added to the list of generated files by adding a respective
40entry to the table in generate_test.go (and possibly describing any necessary
41source transformations).
42
43In the following, examples and commands are based on types2 but usually apply
44directly to go/types.
45
46
47#
48### Tests
49
50There is a comprehensive suite of tests in the form of annotated source files.
51The tests are in:
52
53- src/internal/types/testdata/ (shared between go/types and types2)
54- ./testdata/local (typechecker local tests, for rare situations only)
55
56Tests are .go files annotated with `/* ERROR "msg" */` or `/* ERRORx "msg" */`
57comments (or the respective line comment form).
58For each such error comment, typechecking the respective file is expected to
59report an error at the position of the syntactic token _immediately preceding_
60the comment.
61For `ERROR`, the `"msg"` string must be a substring of the error message
62reported by the typechecker;
63for `ERRORx`, the `"msg"` string must be a regular expresspion matching the
64reported error.
65
66For each issue #NNNN that is fixed in the typecheckers, a test
67should be added as src/internal/types/testdata/fixedbugs/issueNNNN.go.
68
69
70#
71### Debugging
72
73The pre-existing template ./testdata/manual.go is convenient for debugging
74on-off situations. Simply populate it with the code of interest and then
75run `go test -run Manual` which will typecheck that file.
76
77Useful debugging flags (together with `go test -run Manual`):
78
79- -halt (panic and produce a stack trace where the first error is reported)
80- -v (produce a typechecking trace)
81- -verify (verify `ERROR` comments in manual.go)
82
83
84#
85### Frequently used types and variables
86
87#### Checker
88
89File: check.go
90
91A `Checker` maintains all typechecking state relevant for typechecking a package.
92Typically the receiver type for typechecker methods.
93
94
95#### operand
96
97File: operand.go
98
99An `operand` describes the type and value (if any) of an expression.
100The `operandMode` describes the kind of expression (constant, variable, etc.).
101Operands are the primary result of typechecking an expression.
102If typechecking of an expression fails, the resulting operand has mode `invalid`.
103
104
105#### Typ
106
107File: universe.go
108
109The `Typ` array provides access to all predeclared basic types.
110`Typ[Invalid]` is used to denote an invalid type.
111
112
113#
114### Internal coding conventions
115
116#### Predicates
117
118File: predicates.go (commonly used predicates only)
119
120Predicates are typically named in form `isX`, such as `isInteger`.
121
122#### Type-checking expressions
123
124Typically, there is a Checker method for typechecking a particular expression.
125For instance, there is a method `Checker.unary` that typechecks unary expressions.
126The basic form of such a function f is as follows:
127```
128func (check *Checker) f(x *operand, e syntax.Expr, /* addition arguments, if any */)
129```
130The result of typechecking expression `e` is returned via the operand `x`
131(which sometimes also serves as incoming argument).
132If an error occurred the function f will report the error and try to continue
133as best as it can, but it may return an invalid operand (`x.mode == invalid`).
134Callers may need to explicitly check for invalid operands.
135
136
137#
138### TODO
139
140Add more relevant content.
View as plain text