1// Copyright 2013 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5// Package ir defines a representation of the elements of Go programs
6// (packages, types, functions, variables and constants) using a
7// static single-information (SSI) form intermediate representation
8// (IR) for the bodies of functions.
9//
10// THIS INTERFACE IS EXPERIMENTAL AND IS LIKELY TO CHANGE.
11//
12// For an introduction to SSA form, upon which SSI builds, see
13// http://en.wikipedia.org/wiki/Static_single_assignment_form.
14// This page provides a broader reading list:
15// http://www.dcs.gla.ac.uk/~jsinger/ssa.html.
16//
17// For an introduction to SSI form, see The static single information
18// form by C. Scott Ananian.
19//
20// The level of abstraction of the IR form is intentionally close to
21// the source language to facilitate construction of source analysis
22// tools.  It is not intended for machine code generation.
23//
24// The simplest way to create the IR of a package is
25// to load typed syntax trees using golang.org/x/tools/go/packages, then
26// invoke the irutil.Packages helper function. See ExampleLoadPackages
27// and ExampleWholeProgram for examples.
28// The resulting ir.Program contains all the packages and their
29// members, but IR code is not created for function bodies until a
30// subsequent call to (*Package).Build or (*Program).Build.
31//
32// The builder initially builds a naive IR form in which all local
33// variables are addresses of stack locations with explicit loads and
34// stores.  Registerisation of eligible locals and φ-node insertion
35// using dominance and dataflow are then performed as a second pass
36// called "lifting" to improve the accuracy and performance of
37// subsequent analyses; this pass can be skipped by setting the
38// NaiveForm builder flag.
39//
40// The primary interfaces of this package are:
41//
42//    - Member: a named member of a Go package.
43//    - Value: an expression that yields a value.
44//    - Instruction: a statement that consumes values and performs computation.
45//    - Node: a Value or Instruction (emphasizing its membership in the IR value graph)
46//
47// A computation that yields a result implements both the Value and
48// Instruction interfaces.  The following table shows for each
49// concrete type which of these interfaces it implements.
50//
51//                      Value?          Instruction?    Member?
52//   *Alloc             ✔               ✔
53//   *BinOp             ✔               ✔
54//   *BlankStore                        ✔
55//   *Builtin           ✔
56//   *Call              ✔               ✔
57//   *ChangeInterface   ✔               ✔
58//   *ChangeType        ✔               ✔
59//   *Const             ✔               ✔
60//   *Convert           ✔               ✔
61//   *DebugRef                          ✔
62//   *Defer             ✔               ✔
63//   *Extract           ✔               ✔
64//   *Field             ✔               ✔
65//   *FieldAddr         ✔               ✔
66//   *FreeVar           ✔
67//   *Function          ✔                               ✔ (func)
68//   *Global            ✔                               ✔ (var)
69//   *Go                ✔               ✔
70//   *If                                ✔
71//   *Index             ✔               ✔
72//   *IndexAddr         ✔               ✔
73//   *Jump                              ✔
74//   *Load              ✔               ✔
75//   *MakeChan          ✔               ✔
76//   *MakeClosure       ✔               ✔
77//   *MakeInterface     ✔               ✔
78//   *MakeMap           ✔               ✔
79//   *MakeSlice         ✔               ✔
80//   *MapLookup         ✔               ✔
81//   *MapUpdate         ✔               ✔
82//   *NamedConst                                        ✔ (const)
83//   *Next              ✔               ✔
84//   *Panic                             ✔
85//   *Parameter         ✔               ✔
86//   *Phi               ✔               ✔
87//   *Range             ✔               ✔
88//   *Recv              ✔               ✔
89//   *Return                            ✔
90//   *RunDefers                         ✔
91//   *Select            ✔               ✔
92//   *Send              ✔               ✔
93//   *Sigma             ✔               ✔
94//   *Slice             ✔               ✔
95//   *Store             ✔               ✔
96//   *StringLookup      ✔               ✔
97//   *Type                                              ✔ (type)
98//   *TypeAssert        ✔               ✔
99//   *UnOp              ✔               ✔
100//   *Unreachable                       ✔
101//
102// Other key types in this package include: Program, Package, Function
103// and BasicBlock.
104//
105// The program representation constructed by this package is fully
106// resolved internally, i.e. it does not rely on the names of Values,
107// Packages, Functions, Types or BasicBlocks for the correct
108// interpretation of the program.  Only the identities of objects and
109// the topology of the IR and type graphs are semantically
110// significant.  (There is one exception: Ids, used to identify field
111// and method names, contain strings.)  Avoidance of name-based
112// operations simplifies the implementation of subsequent passes and
113// can make them very efficient.  Many objects are nonetheless named
114// to aid in debugging, but it is not essential that the names be
115// either accurate or unambiguous.  The public API exposes a number of
116// name-based maps for client convenience.
117//
118// The ir/irutil package provides various utilities that depend only
119// on the public API of this package.
120//
121// TODO(adonovan): Consider the exceptional control-flow implications
122// of defer and recover().
123//
124// TODO(adonovan): write a how-to document for all the various cases
125// of trying to determine corresponding elements across the four
126// domains of source locations, ast.Nodes, types.Objects,
127// ir.Values/Instructions.
128//
129package ir // import "honnef.co/go/tools/ir"
130