Frontend and Type Checking

Relevant source files

• src/cmd/compile/internal/types2/assignments.go
• src/cmd/compile/internal/types2/builtins.go
• src/cmd/compile/internal/types2/call.go
• src/cmd/compile/internal/types2/compilersupport.go
• src/cmd/compile/internal/types2/decl.go
• src/cmd/compile/internal/types2/expr.go
• src/cmd/compile/internal/types2/index.go
• src/cmd/compile/internal/types2/literals.go
• src/cmd/compile/internal/types2/stmt.go
• src/cmd/compile/internal/types2/typexpr.go
• src/go/types/assignments.go
• src/go/types/builtins.go
• src/go/types/call.go
• src/go/types/decl.go
• src/go/types/expr.go
• src/go/types/index.go
• src/go/types/literals.go
• src/go/types/stmt.go
• src/go/types/typexpr.go
• src/internal/goexperiment/exp_newinliner_off.go
• src/internal/goexperiment/exp_newinliner_on.go
• src/internal/types/testdata/spec/range.go
• src/internal/types/testdata/spec/range_int.go

Purpose and Scope

This document describes the frontend phases of the Go compiler toolchain, covering parsing, AST construction, and type checking. The frontend transforms Go source code into a typed intermediate representation (IR), performing semantic analysis to ensure program correctness according to the Go language specification.

For information about the IR itself and how it's used in later compilation stages, see Unified IR and Export Data. For SSA generation that follows type checking, see SSA Generation.

Architecture Overview

The Go repository maintains two parallel type checker implementations:

1. go/types - Used by external tools (gopls, staticcheck, etc.) and accessible via the standard library
2. cmd/compile/internal/types2 - Used internally by the Go compiler

These implementations share the same type checking algorithms and logic. The go/types package is generated from types2 with minimal differences to accommodate different AST representations (go/ast vs cmd/compile/internal/syntax).

Sources: src/go/types/expr.go1-57 src/cmd/compile/internal/types2/expr.go1-57 src/go/types/assignments.go1-3

Key Differences

Aspect	go/types	types2
Purpose	External tools, analysis	Compiler frontend
AST Package	go/ast	cmd/compile/internal/syntax
Position Info	token.Pos	syntax.Pos
Output	types.Info map	Typed ir.Node tree
Import Path	go/types	cmd/compile/internal/types2

Parsing and AST Construction

Parser Implementations

The parsing phase transforms source text into an Abstract Syntax Tree (AST). Two parsers exist corresponding to the two type checker implementations:

go/parser (for external tools):

• Produces ast.Node trees representing Go source structure
• Includes detailed position information and comments
• Used by gopls, gofmt, go vet, and other tools

cmd/compile/internal/syntax (for compiler):

• Produces syntax.Node trees with similar structure but different types
• Optimized for compiler performance
• Supports parser-level error recovery

Sources: src/go/types/expr.go17-57 src/cmd/compile/internal/syntax

AST Structure

Both AST representations organize code into hierarchical nodes:

• Declarations: FuncDecl, GenDecl (const, var, type)
• Statements: IfStmt, ForStmt, SwitchStmt, AssignStmt, etc.
• Expressions: BinaryExpr, CallExpr, IndexExpr, SelectorExpr, etc.
• Type Expressions: ArrayType, StructType, FuncType, InterfaceType, etc.

Type Checking Architecture

The Checker Type

The core type checking state is maintained in the Checker struct, which orchestrates the entire semantic analysis process.

Sources: src/go/types/decl.go48-167 src/cmd/compile/internal/types2/decl.go48-166

Checking Phases

Type checking proceeds in several phases:

1. Object Collection: Gather all package-level declarations into scopes
2. Dependency Resolution: Determine checking order based on dependencies
3. Type Determination: Check each object's type (constants, variables, types, functions)
4. Method Collection: Associate methods with their receiver types
5. Body Checking: Type-check function bodies and initializers

Sources: src/go/types/decl.go48-167 src/go/types/check.go

Expression Type Checking

Expression checking is the heart of semantic analysis. The algorithm recursively checks expressions top-down and propagates type information.

The Operand Abstraction

Type checking uses the operand type to represent the result of checking an expression:

Sources: src/go/types/operand.go src/go/types/expr.go17-57

Expression Checking Algorithm

The main entry points for expression checking are:

• rawExpr: Core recursive expression checker
• expr: Wrapper that calls rawExpr with default settings
• exprInternal: Dispatches to specific checkers based on expression kind

Sources: src/go/types/expr.go966-1200 src/go/types/expr.go1023-1200

Key Expression Checkers

Binary Operations

Binary expressions are checked by binary() which:

1. Checks both operands
2. Handles special cases (shifts, comparisons)
3. Performs type matching via matchTypes()
4. Validates operator applicability
5. Performs constant folding when possible

Sources: src/go/types/expr.go780-872

Call Expressions

Call checking (callExpr()) handles:

• Type conversions (T(x))
• Built-in function calls
• Ordinary function/method calls
• Generic function instantiation via funcInst()

Sources: src/go/types/call.go172-351 src/cmd/compile/internal/types2/call.go171-349

Function Instantiation

Generic function instantiation is handled by funcInst(), which:

1. Validates type argument count
2. Infers missing type arguments when possible
3. Instantiates the function signature
4. Verifies type constraints

Sources: src/go/types/call.go34-130 src/cmd/compile/internal/types2/call.go33-129

Selector Expressions

Selector checking (selector()) handles:

• Package-qualified identifiers (pkg.Name)
• Field selection (struct.field)
• Method selection (value.method)
• Implicit pointer dereferencing

Sources: src/go/types/call.go686-890 src/cmd/compile/internal/types2/call.go681-880

Untyped Expression Handling

Go has untyped constants and values that receive their final type through context:

The updateExprType() function propagates final types through expression trees, ensuring untyped values become properly typed based on assignment context.

Sources: src/go/types/expr.go252-372 src/cmd/compile/internal/types2/expr.go253-397

Statement Type Checking

Statement checking validates control flow and operations that don't produce values.

Statement Checker Organization

Sources: src/go/types/stmt.go src/cmd/compile/internal/types2/stmt.go100-126

Assignment Checking

Assignment validation (assignment()) ensures:

1. Single value result (via singleValue())
2. Type compatibility between value and target
3. Untyped value conversion to target type
4. Addressability for certain assignments

Sources: src/go/types/assignments.go19-89 src/cmd/compile/internal/types2/assignments.go16-85

Control Flow Validation

Statement checking tracks context via stmtContext flags:

• breakOk: break statement allowed
• continueOk: continue statement allowed
• fallthroughOk: fallthrough statement allowed
• finalSwitchCase: last case in switch
• inTypeSwitch: within type switch

Sources: src/go/types/stmt.go84-99 src/cmd/compile/internal/types2/stmt.go83-98

Declaration Type Checking

Declaration Checking Flow

The objDecl() function type-checks declarations in dependency order:

Sources: src/go/types/decl.go48-167 src/cmd/compile/internal/types2/decl.go48-166

Dependency Tracking

The checker maintains:

• objPath: Stack of objects currently being checked
• objPathIdx: Map from object to its index in objPath
• objMap: Map from object to its declInfo

This enables cycle detection and proper ordering of declarations.

Sources: src/go/types/decl.go169-295 src/cmd/compile/internal/types2/decl.go168-293

Type Name Checking

Type declarations (typeDecl()) handle:

• Alias types (type A = B)
• Defined types (type T struct{...})
• Generic type declarations with type parameters
• Recursive type detection

Sources: src/go/types/typexpr.go src/cmd/compile/internal/types2/typexpr.go

Built-in Function Checking

Built-in functions have special type checking rules implemented in builtin():

Built-in Categories

Sources: src/go/types/builtins.go23-84 src/cmd/compile/internal/types2/builtins.go20-81

Example: len/cap Checking

The len() and cap() built-ins:

1. Check for function calls/receives (constant folding optimization)
2. Validate argument type (string, array, slice, map, channel)
3. Compute constant value for array types when possible
4. Set result type to int

Sources: src/go/types/builtins.go149-231 src/cmd/compile/internal/types2/builtins.go146-227

Scope and Symbol Management

Scope Hierarchy

Scopes form a tree structure representing lexical nesting:

The checker maintains the current scope in Checker.scope and provides:

• openScope(): Create nested scope
• closeScope(): Return to parent scope
• declare(): Add object to current scope
• lookupScope(): Find object in scope chain

Sources: src/go/types/scope.go src/go/types/decl.go16-34

Object Types

Scopes contain Object instances representing declared entities:

Object Type	Represents
*Const	Named constant
*Var	Variable (local, field, parameter)
*TypeName	Named type or alias
*Func	Function or method
*PkgName	Imported package
*Builtin	Built-in function
*Nil	Predeclared nil

Sources: src/go/types/object.go

Information Recording

The Info Type

Type information is recorded in types.Info for use by tools:

Sources: src/go/types/api.go

Recording Points

Type information is recorded at key points:

• After expression checking: Type and value via record()
• At identifier definition: Object via recordDef()
• At identifier use: Object via recordUse()
• At selector: Selection info via recordSelection()
• At instantiation: Type arguments via recordInstance()

Sources: src/go/types/expr.go989 src/go/types/call.go753

Error Reporting

Error Infrastructure

The checker maintains error state and provides several error reporting functions:

Sources: src/internal/types/errors/codes.go

Error Positions

Errors are reported at specific source positions:

• Expression errors: position of the problematic expression
• Type errors: position of the type expression
• Declaration errors: position of the identifier

The checker uses positioner interface to abstract position sources across go/ast and syntax packages.

Sources: src/go/types/errors.go src/cmd/compile/internal/types2/errors.go

Summary

The frontend and type checking phases transform Go source code into semantically valid, typed representations:

1. Parsing converts source text to AST (go/parser or syntax.Parse)
2. Type Checking validates semantics via Checker:
   • Collects and organizes declarations into scopes
   • Resolves dependencies and checks in proper order
   • Type-checks expressions, statements, and declarations
   • Records type information for tools or compiler
3. Output is either:
   • types.Info maps for external tools (go/types)
   • Typed ir.Node tree for compiler (types2)

The type checker implements the Go language specification's semantic rules, detecting errors like undefined names, type mismatches, invalid operations, and declaration cycles.

Sources: src/go/types/expr.go17-57 src/go/types/call.go1-14 src/go/types/decl.go48-167 src/cmd/compile/internal/types2/expr.go17-57 src/cmd/compile/internal/types2/call.go1-14 src/cmd/compile/internal/types2/decl.go48-166