cmd/compile: add a README section on developing the compiler

[mvdan]

For example, such a section could mention:

• https://godoc.org/golang.org/x/tools/cmd/toolstash, to make backups of a working/previous Go compiler
• General recommendations like toolstash restore && go install cmd/compile to rebuild the compiler in a fast and stable way
• Tips to ensure that the compiler hasn't been obviously broken, such as go build -toolexec "toolstash -cmp" -a -v std cmd
• Tips on how to use https://godoc.org/golang.org/x/tools/cmd/compilebench along with toolstash and benchstat to measure performance optimizations

Anything else that comes to mind, please add it to this issue. I plan on sending a CL to add a markdown section sometime during the 1.13 cycle.

I realise the SSA package has lots of extra checks and debugging flags one can enable, but I think those should be covered by cmd/compile/internal/ssa/README. I am also not nearly as familiar with those as I'm with this list here, so I'm leaving ssa's tips for another issue/CL.

/cc @josharian @mdempsky @aclements @randall77

[josharian]

Wrapper tools: toolstash-check and compilecmp. (Maybe those should move to x/tools?)

[josharian]

Maybe references to gosmith and how to fuzz the compiler and how to build and run a race-enabled compiler. Mention the SSA rulelog? Some basic tips (like start with the simplest possible reproduction and understand exactly what is happening with it). Pointers on where all the tests live (some in-package, some over in the test dir).

[mvdan]

toolstash-check

Hmm, I've personally found it a bit unnecessary. What I do is always run GOROOT=/usr/lib/go ./make.bash && toolstash save, so then I always have a stashed set of tools which correspond to the current master branch I'm on.

Not exactly the same, as toolstash-check compares with the direct parent, but close enough :)

and compilecmp

I think it would need documentation if we are to suggest it here :)

Maybe references to gosmith and how to fuzz the compiler and how to build and run a race-enabled compiler.

I worry that these would be a bit too advanced for the "modifying the compiler" intro section. We don't want to bombard new developers with two pages of tools to learn. Perhaps this could fall under a more advanced section.

Mention the SSA rulelog?

Sure, but wouldn't this go in the SSA readme?

Some basic tips (like start with the simplest possible reproduction and understand exactly what is happening with it). Pointers on where all the tests live (some in-package, some over in the test dir).

Good ideas! I was forgetting about the simpler pieces of advice like these.

[mvdan]

Here's another idea: How to measure whether a compiler patch produces smaller binaries. For example, if the prove pass is made a bit smarter, and we want to check that it's really removing many bounds checks from a large binary.

I believe this is usually measured by comparing text section sizes between two built binaries, but I'm not sure what the tips for this are. For example:

• What large binaries are generally good for this? cmd/go, cmd/gofmt, cmd/compile?
• Which (portable) tool should be used to extract the sizes? size, readelf, or go tool something?
• Is this process automatable in any way?

[josharian]

toolstash-check
Hmm, I've personally found it a bit unnecessary.

It helps prevent making silly mistakes, which I have personally done more than I care to recount. Also, it makes it easy to check all platforms, which matters sometimes.

I think it would need documentation if we are to suggest it here :)

Yes. Mea culpa. Although FWIW most folks I have recommended it to (on CLs/issues) figure it out pretty readily. It could also use a bit of cleanup.

I have also long had plans to unify some of the toolchain-wranging in compilecmp and toolstash-check and pull it into a re-usable package. I have some of it written, but never finished it.

How to measure whether a compiler patch produces smaller binaries.

compilecmp does a fair amount of this already. If you pass it -obj, which could be made to default to on, it inspects the object files produced by the compiler and tells you about changes, separating out code and static symbols from the export data. It also does a check on the size of hello world, although that's not really very informative. But the infrastructure to do this is all in compilecmp.

[mdempsky]

Hmm, I've personally found it a bit unnecessary. What I do is always run GOROOT=/usr/lib/go ./make.bash && toolstash save, so then I always have a stashed set of tools which correspond to the current master branch I'm on.

For rapid development, I usually just toolstash directly as well, but when I'm working on multi-stage CLs where some (but not all) of the CLs affect compiler output, it's easy for me to lose track of what toolchain I stashed. So toolstash-check is my error-proof pre-upload check.

Since it builds in /tmp, you can also check multiple CLs in parallel. And like @josharian mentioned, it can help checking other platforms too.

• General recommendations like toolstash restore && go install cmd/compile to rebuild the compiler in a fast and stable way

FWIW, I usually use go install -toolexec=toolstash cmd/compile.

--

Some other things to mention: how to inspect various stages of the compiler. For example, using -S to dump assembly output; GOSSAFUNC to dump SSA stuff; -W to dump the typechecked trees; etc.

[josharian]

@mvdan want to write some docs, call this completed, or bump to 1.14?

[mvdan]

I do intend to work on this, ideally for 1.13. I assume it's fine to review and submit during the first half of the freeze, as it's only documentation that doesn't affect the release. But if people disagree, it can wait until 1.14.

[randall77]

Documentation during the freeze is actively encouraged.

[mvdan]

Great! I'm currently at GopherCon Singapore, so I'll probably get to this later in May.

[josharian]

A section about the -d flags would be helpful. See conversation at CL 176718.

[dgryski]

Related: https://rustc-dev-guide.rust-lang.org/

[mvdan]

I'll probably get to this later in May.

I evidently did not get to this, and I haven't done any compiler development in a while, so this is up for grabs. Ideally by someone who actually keeps up to date with how to do compiler development nowadays.

[gopherbot]

Change https://go.dev/cl/404694 mentions this issue: cmd/compile: update README.md

[gopherbot]

Change https://go.dev/cl/503895 mentions this issue: cmd/compile: add a 'Tips' section to README to help new contributors

[thepudds]

FYI, I sent CL 503895, which adds a new "Tips" section to the cmd/compile README.

I initially built it up as a classic "things I wish I knew a month ago", and hence is mostly focused on new-ish cmd/compile contributors.

I fleshed it out by cross-checking against topics mentioned above. The CL currently at least touches on many of them, but not:

Wrapper tools: toolstash-check and compilecmp. (Maybe those should move to x/tools?)

Maybe references to gosmith and how to fuzz the compiler and how to build and run a race-enabled compiler.

How to measure whether a compiler patch produces smaller binaries

See conversation at CL 176718.

I can add more to the CL, though perhaps more advanced topics can be left to the future.

[thepudds]

Hi @alandonovan, a brief follow-up on our discussion just now — it would be helpful I think if there was a short paragraph on export data (ideally with a few outbound links) added to cmd/compile/README.md.

[gopherbot]

Change https://go.dev/cl/578055 mentions this issue: cmd/compile: describe export data