From 8a4b439ee6e0f5d41cb6ae30146b901f3c0ad4b7 Mon Sep 17 00:00:00 2001 From: Robert Griesemer Date: Thu, 5 Sep 2024 16:29:10 -0700 Subject: [PATCH] go/types, types2: add initial README.md Change-Id: I0a5ce4d50d65b803b001d01d627e8e6d2af66d6e Reviewed-on: https://go-review.googlesource.com/c/go/+/611335 TryBot-Bypass: Robert Griesemer Reviewed-by: Cuong Manh Le Reviewed-by: Robert Griesemer Reviewed-by: Tim King Auto-Submit: Robert Griesemer --- src/cmd/compile/internal/types2/README.md | 140 ++++++++++++++++++++++ src/go/types/README.md | 1 + 2 files changed, 141 insertions(+) create mode 100644 src/cmd/compile/internal/types2/README.md create mode 100644 src/go/types/README.md diff --git a/src/cmd/compile/internal/types2/README.md b/src/cmd/compile/internal/types2/README.md new file mode 100644 index 0000000000..5b913f9174 --- /dev/null +++ b/src/cmd/compile/internal/types2/README.md @@ -0,0 +1,140 @@ +This file describes some of the typecheckers internal organization and conventions. +It is not meant to be complete; rather it is a living document that will be updated +as needed. + +Read this file first before starting to make changes in the code. + +# +### Overall organization + +There are two almost identical typecheckers: + +- cmd/compile/internal/types2 (or types2 for short) +- go/types + +types2 is internal and used by the compiler. +go/types is the std library typechecker and its API must remain strictly +backward-compatible. +The types2 API closely matches the go/types API but may not have some +deprecated functions anymore (which we need to maintain in go/types). + +They differ primarily in what syntax tree they operate on: + +- types2 uses the syntax tree defined by cmd/compile/internal/syntax +- go/types uses the syntax tree defined by go/ast + +We aim to keep the respective sources very closely in sync. +**Any change will need to be made to both typechecker source bases**. + +Many go/types files can be generated automatically from the +corresponding types2 sources. +This is done via a generator (go/types/generate_test.go) which may be invoked via +`go generate` in the go/types directory. +Generated files are clearly marked with a comment at the top and should not +be modified by hand. +For this reason, it is usally best to make changes to the types2 sources first. +The changes only need to be ported by hand for the go/types files that cannot +be generated yet. + +New files may be added to the list of generated files by adding a respective +entry to the table in generate_test.go (and possibly describing any necessary +source transformations). + +In the following, examples and commands are based on types2 but usually apply +directly to go/types. + + +# +### Tests + +There is a comprehensive suite of tests in the form of annotated source files. +The tests are in: + +- src/internal/types/testdata/ (shared between go/types and types2) +- ./testdata/local (typechecker local tests, for rare situations only) + +Tests are .go files annotated with `/* ERROR "msg" */` or `/* ERRORx "msg" */` +comments (or the respective line comment form). +For each such error comment, typechecking the respective file is expected to +report an error at the position of the syntactic token _immediately preceeding_ +the comment. +For `ERROR`, the `"msg"` string must be a substring of the error message +reported by the typechecker; +for `ERRORx`, the `"msg"` string must be a regular expresspion matching the +reported error. + +For each issue #NNNN that is fixed in the typecheckers, a test +should be added as src/internal/types/testdata/fixedbugs/issueNNNN.go. + + +# +### Debugging + +The pre-existing template ./testdata/manual.go is convenient for debugging +on-off situations. Simply populate it with the code of interest and then +run `go test -run Manual` which will typecheck that file. + +Useful debugging flags (together with `go test -run Manual`): + +- -halt (panic and produce a stack trace where the first error is reported) +- -v (produce a typechecking trace) +- -verify (verify `ERROR` comments in manual.go) + + +# +### Frequently used types and variables + +#### Checker + +File: check.go + +A `Checker` maintains all typechecking state relevant for typechecking a package. +Typically the receiver type for typechecker methods. + + +#### operand + +File: operand.go + +An `operand` describes the type and value (if any) of an expression. +The `operandMode` describes the kind of expression (constant, variable, etc.). +Operands are the primary result of typechecking an expression. +If typechecking of an expression fails, the resulting operand has mode `invalid`. + + +#### Typ + +File: universe.go + +The `Typ` array provides access to all predeclared basic types. +`Typ[Invalid]` is used to denote an invalid type. + + +# +### Internal coding conventions + +#### Predicates + +File: predicates.go (commonly used predicates only) + +Predicates are typically named in form `isX`, such as `isInteger`. + +#### Type-checking expressions + +Typically, there is a Checker method for typechecking a particular expression. +For instance, there is a method `Checker.unary` that typechecks unary expressions. +The basic form of such a function f is as follows: +``` +func (check *Checker) f(x *operand, e syntax.Expr, /* addition arguments, if any */) +``` +The result of typechecking expression `e` is returned via the operand `x` +(which sometimes also serves as incoming argument). +If an error occured the function f will report the error and try to continue +as best as it can, but it may return an invalid operand (`x.mode == invalid`). +Callers may need to explicitly check for invalid operands. + + +# +### TODO + +Add more relevant content. diff --git a/src/go/types/README.md b/src/go/types/README.md new file mode 100644 index 0000000000..a1a6a81cef --- /dev/null +++ b/src/go/types/README.md @@ -0,0 +1 @@ +See [src/cmd/compile/internal/types2/README.md](https://cs.opensource.google/go/go/+/master:src/cmd/compile/internal/types2/README.md). -- 2.48.1