1# Making Unified Intermediate Representation (UIR) Changes
2
3For general information on export data, see [here](../../README.md).
4
5UIR is the serial form of the compiler's intermediate representation, used to
6propagate bodies of generic and/or inlined functions from one compilation unit
7to another.
8
9The Go compiler has a single, canonical UIR writer implementation in
10`src/cmd/compile/internal/noder/writer.go`. When we update the byte stream that
11the UIR writer writes, *all* of the UIR readers need to be reviewed and
12potentially updated; a change might not be backward compatible for them. These
13instructions outline the steps required to keep all UIR readers up-to-date.
14
15## The Writer
16
17The UIR version written by the compiler is controlled by
18`src/cmd/compile/internal/noder/unified.go`. Do not change this yet. Instead:
19
201. Add a version flag N+1 for `MyChange` in `internal/pkgbits/version.go`.
212. Update the UIR writer in `src/cmd/compile/internal/noder/writer.go` to guard
22 the writing of any fields added in N+1. Note: readers still on version N
23 *must* be oblivious to this change to avoid breaking the readers on
24 submission.
25
26## The Readers
27
28Besides the compiler itself, there are other readers in go, x/tools, and
29externally. Those in x/tools and the general public exist because
30`go list -export` produces export data files in this format and we support the
31ability of applications to decode it.
32
33> Note that there is an upcoming plan to decouple the compiler's IR from x/tools
34> by changing the format encoded by `go list -export`; this would make UIR a
35> private detail of the compiler, free to break at any time. For now, these
36> instructions must still be followed.
37
38We assume that external readers will update on their own. The necessary reader
39updates in go and x/tools are detailed below.
40
41### go
42
433. Update the compiler's own UIR reader in
44 `src/cmd/compile/internal/noder/reader.go` to guard the reading of any fields
45 added in N+1.
464. Repeat this change for the readers in `src/go/internal/gcimporter/ureader.go`
47 and `src/cmd/compile/internal/importer/ureader.go`. Note that these readers
48 only read data needed for type checking (in `src/go/types` and
49 `src/cmd/compile/internal/types2` respectively). For instance, they do not
50 read exported function bodies. Thus, it's possible that a change to UIR (such
51 as the encoding of function bodies) would require no change to these readers.
52
53### x/tools
54
555. Add a version flag for `MyChange` in `internal/pkgbits/version.go`. Note:
56 x/tools has its own pkgbits implementation, which is intended to be an exact
57 copy of the [one in go](#the-writer). Any change made to one must be
58 reflected in the other.
596. Update the x/tools UIR reader in `internal/gcimporter/ureader.go` to guard
60 the reading of any fields added in N+1. Call this commit C.
617. In go, take the commit hash for C and update `src/cmd/go.mod` to use x/tools@C
62 per the [vendoring instructions](https://go.dev/wiki/MinorReleases#cherry-pick-cls-for-vendored-golangorgx-packages).
63
64## Finalizing
65
66> If this UIR change will be tested, check the [following section](#testing) and
67> consider when it makes to finalize.
68
69Only after reviewing *all* of the readers, bump the UIR version written by the
70writer to N+1 in `src/cmd/compile/internal/noder/unified.go`. Because the
71readers have already been updated to handle version N+1, this change is
72compatible.
73
74## Testing
75
76If making changes related to some new feature requiring extensive testing, it's
77best to postpone bumping the UIR version until *all* of the tests are in. To
78commit tests incrementally, develop them with a locally-incremented UIR version
79and commit *skipped* tests; don't yet bump the remote UIR version.
80
81Once all of the required tests are in, bump the remote UIR version while turning
82on all of the previously skipped tests. This minimizes churn on the UIR version
83as testing uncovers any discrepancies.
View as plain text