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.
5 // Package ssa defines a representation of the elements of Go programs
6 // (packages, types, functions, variables and constants) using a
7 // static single-assignment (SSA) form intermediate representation
8 // (IR) for the bodies of functions.
10 // THIS INTERFACE IS EXPERIMENTAL AND IS LIKELY TO CHANGE.
12 // For an introduction to SSA form, 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.
17 // The level of abstraction of the SSA form is intentionally close to
18 // the source language to facilitate construction of source analysis
19 // tools. It is not intended for machine code generation.
21 // All looping, branching and switching constructs are replaced with
22 // unstructured control flow. Higher-level control flow constructs
23 // such as multi-way branch can be reconstructed as needed; see
24 // ssautil.Switches() for an example.
26 // The simplest way to create the SSA representation of a package is
27 // to load typed syntax trees using golang.org/x/tools/go/packages, then
28 // invoke the ssautil.Packages helper function. See ExampleLoadPackages
29 // and ExampleWholeProgram for examples.
30 // The resulting ssa.Program contains all the packages and their
31 // members, but SSA code is not created for function bodies until a
32 // subsequent call to (*Package).Build or (*Program).Build.
34 // The builder initially builds a naive SSA form in which all local
35 // variables are addresses of stack locations with explicit loads and
36 // stores. Registerisation of eligible locals and φ-node insertion
37 // using dominance and dataflow are then performed as a second pass
38 // called "lifting" to improve the accuracy and performance of
39 // subsequent analyses; this pass can be skipped by setting the
40 // NaiveForm builder flag.
42 // The primary interfaces of this package are:
44 // - Member: a named member of a Go package.
45 // - Value: an expression that yields a value.
46 // - Instruction: a statement that consumes values and performs computation.
47 // - Node: a Value or Instruction (emphasizing its membership in the SSA value graph)
49 // A computation that yields a result implements both the Value and
50 // Instruction interfaces. The following table shows for each
51 // concrete type which of these interfaces it implements.
53 // Value? Instruction? Member?
58 // *ChangeInterface ✔ ✔
68 // *Function ✔ ✔ (func)
82 // *NamedConst ✔ (const)
98 // Other key types in this package include: Program, Package, Function
101 // The program representation constructed by this package is fully
102 // resolved internally, i.e. it does not rely on the names of Values,
103 // Packages, Functions, Types or BasicBlocks for the correct
104 // interpretation of the program. Only the identities of objects and
105 // the topology of the SSA and type graphs are semantically
106 // significant. (There is one exception: Ids, used to identify field
107 // and method names, contain strings.) Avoidance of name-based
108 // operations simplifies the implementation of subsequent passes and
109 // can make them very efficient. Many objects are nonetheless named
110 // to aid in debugging, but it is not essential that the names be
111 // either accurate or unambiguous. The public API exposes a number of
112 // name-based maps for client convenience.
114 // The ssa/ssautil package provides various utilities that depend only
115 // on the public API of this package.
117 // TODO(adonovan): Consider the exceptional control-flow implications
118 // of defer and recover().
120 // TODO(adonovan): write a how-to document for all the various cases
121 // of trying to determine corresponding elements across the four
122 // domains of source locations, ast.Nodes, types.Objects,
123 // ssa.Values/Instructions.
125 package ssa // import "golang.org/x/tools/go/ssa"
projects / dotfiles / .git / blob