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 updated3as needed.45Read this file first before starting to make changes in the code.67#8### Overall organization910There are two almost identical typecheckers:1112- cmd/compile/internal/types2 (or types2 for short)13- go/types1415types2 is internal and used by the compiler.16go/types is the std library typechecker and its API must remain strictly17backward-compatible.18The types2 API closely matches the go/types API but may not have some19deprecated functions anymore (which we need to maintain in go/types).2021They differ primarily in what syntax tree they operate on:2223- types2 uses the syntax tree defined by cmd/compile/internal/syntax24- go/types uses the syntax tree defined by go/ast2526We aim to keep the respective sources very closely in sync.27**Any change will need to be made to both typechecker source bases**.2829Many go/types files can be generated automatically from the30corresponding types2 sources.31This is done via a generator (go/types/generate_test.go) which may be invoked via32`go generate` in the go/types directory.33Generated files are clearly marked with a comment at the top and should not34be 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 cannot37be generated yet.3839New files may be added to the list of generated files by adding a respective40entry to the table in generate_test.go (and possibly describing any necessary41source transformations).4243In the following, examples and commands are based on types2 but usually apply44directly to go/types.454647#48### Tests4950There is a comprehensive suite of tests in the form of annotated source files.51The tests are in:5253- src/internal/types/testdata/ (shared between go/types and types2)54- ./testdata/local (typechecker local tests, for rare situations only)5556Tests 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 to59report 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 message62reported by the typechecker;63for `ERRORx`, the `"msg"` string must be a regular expresspion matching the64reported error.6566For each issue #NNNN that is fixed in the typecheckers, a test67should be added as src/internal/types/testdata/fixedbugs/issueNNNN.go.686970#71### Debugging7273The pre-existing template ./testdata/manual.go is convenient for debugging74on-off situations. Simply populate it with the code of interest and then75run `go test -run Manual` which will typecheck that file.7677Useful debugging flags (together with `go test -run Manual`):7879- -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)828384#85### Frequently used types and variables8687#### Checker8889File: check.go9091A `Checker` maintains all typechecking state relevant for typechecking a package.92Typically the receiver type for typechecker methods.939495#### operand9697File: operand.go9899An `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`.103104105#### Typ106107File: universe.go108109The `Typ` array provides access to all predeclared basic types.110`Typ[Invalid]` is used to denote an invalid type.111112113#114### Internal coding conventions115116#### Predicates117118File: predicates.go (commonly used predicates only)119120Predicates are typically named in form `isX`, such as `isInteger`.121122#### Type-checking expressions123124Typically, 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 continue133as best as it can, but it may return an invalid operand (`x.mode == invalid`).134Callers may need to explicitly check for invalid operands.135136137#138### TODO139140Add more relevant content.