qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-05 17:26:11 -07:00
Code Releases Activity

cmd/compile: add a 'Tips' section to README to help new contributors

Browse Source 
This CL adds a new 'Tips' section to the cmd/compile README.

The primary intent is to help new-ish contributors.

It includes some basics on getting started, testing changes,
viewing coverage, juggling different compiler versions,
some links to additional tools, and so on.

Updates #30074

Change-Id: I393bf1137db9d2bb851f7e254b08455273ccad8c
Reviewed-on: https://go-review.googlesource.com/c/go/+/503895
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Matthew Dempsky <mdempsky@google.com>
Run-TryBot: t hepudds <thepudds1460@gmail.com>
Reviewed-by: Keith Randall <khr@golang.org>
Reviewed-by: Keith Randall <khr@google.com>
This commit is contained in:
thepudds 2023-06-15 15:09:11 -04:00 committed by Keith Randall
parent 5f04ef752b
commit bc1d71ff64
1 changed files with 170 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
src/cmd/compile/README.md
View File

@ -140,7 +140,177 @@ a series of obj.Prog instructions. These are passed to the assembler
final object file. The object file will also contain reflect data, export data,
and debugging information.
### 8. Tips
#### Getting Started
* If you have never contributed to the compiler before, a simple way to begin
can be adding a log statement or `panic("here")` to get some
initial insight into whatever you are investigating.
* The compiler itself provides logging, debugging and visualization capabilities,
such as:
```
$ go build -gcflags=-m=2 # print optimization info, including inlining, escape analysis
$ go build -gcflags=-d=ssa/check_bce/debug # print bounds check info
$ go build -gcflags=-W # print internal parse tree after type checking
$ GOSSAFUNC=Foo go build # generate ssa.html file for func Foo
$ go build -gcflags=-S # print assembly
$ go tool compile -bench=out.txt x.go # print timing of compiler phases
```
Some flags alter the compiler behavior, such as:
```
$ go tool compile -h file.go # panic on first compile error encountered
$ go build -gcflags=-d=checkptr=2 # enable additional unsafe pointer checking
```
There are many additional flags. Some descriptions are available via:
```
$ go tool compile -h # compiler flags, e.g., go build -gcflags='-m=1 -l'
$ go tool compile -d help # debug flags, e.g., go build -gcflags=-d=checkptr=2
$ go tool compile -d ssa/help # ssa flags, e.g., go build -gcflags=-d=ssa/prove/debug=2
```
There are some additional details about `-gcflags` and the differences between `go build`
vs. `go tool compile` in a [section below](#-gcflags-and-go-build-vs-go-tool-compile).
* In general, when investigating a problem in the compiler you usually want to
start with the simplest possible reproduction and understand exactly what is
happening with it.
#### Testing your changes
* Be sure to read the [Quickly testing your changes](https://go.dev/doc/contribute#quick_test)
section of the Go Contribution Guide.
* Some tests live within the cmd/compile packages and can be run by `go test ./...` or similar,
but many cmd/compile tests are in the top-level
[test](https://github.com/golang/go/tree/master/test) directory:
```
$ go test cmd/internal/testdir # all tests in 'test' dir
$ go test cmd/internal/testdir -run='Test/escape.*.go' # test specific files in 'test' dir
```
For details, see the [testdir README](https://github.com/golang/go/tree/master/test#readme).
The `errorCheck` method in [testdir_test.go](https://github.com/golang/go/blob/master/src/cmd/internal/testdir/testdir_test.go)
is helpful for a description of the `ERROR` comments used in many of those tests.
In addition, the `go/types` package from the standard library and `cmd/compile/internal/types2`
have shared tests in `src/internal/types/testdata`, and both type checkers
should be checked if anything changes there.
* The new [application-based coverage profiling](https://go.dev/testing/coverage/) can be used
with the compiler, such as:
```
$ go install -cover -coverpkg=cmd/compile/... cmd/compile # build compiler with coverage instrumentation
$ mkdir /tmp/coverdir # pick location for coverage data
$ GOCOVERDIR=/tmp/coverdir go test [...] # use compiler, saving coverage data
$ go tool covdata textfmt -i=/tmp/coverdir -o coverage.out # convert to traditional coverage format
$ go tool cover -html coverage.out # view coverage via traditional tools
```
#### Juggling compiler versions
* Many of the compiler tests use the version of the `go` command found in your PATH and
its corresponding `compile` binary.
* If you are in a branch and your PATH includes `<go-repo>/bin`,
doing `go install cmd/compile` will build the compiler using the code from your
branch and install it to the proper location so that subsequent `go` commands
like `go build` or `go test ./...` will exercise your freshly built compiler.
* [toolstash](https://pkg.go.dev/golang.org/x/tools/cmd/toolstash) provides a way
to save, run, and restore a known good copy of the Go toolchain. For example, it can be
a good practice to initially build your branch, save that version of
the toolchain, then restore the known good version of the tools to compile
your work-in-progress version of the compiler.
Sample set up steps:
```
$ go install golang.org/x/tools/cmd/toolstash@latest
$ git clone https://go.googlesource.com/go
$ cd go
$ git checkout -b mybranch
$ ./src/all.bash # build and confirm good starting point
$ export PATH=$PWD/bin:$PATH
$ toolstash save # save current tools
```
After that, your edit/compile/test cycle can be similar to:
```
<... make edits to cmd/compile source ...>
$ toolstash restore && go install cmd/compile # restore known good tools to build compiler
<... 'go build', 'go test', etc. ...> # use freshly built compiler
```
* toolstash also allows comparing the installed vs. stashed copy of
the compiler, such as if you expect equivalent behavior after a refactor.
For example, to check that your changed compiler produces identical object files to
the stashed compiler while building the standard library:
```
$ toolstash restore && go install cmd/compile # build latest compiler
$ go build -toolexec "toolstash -cmp" -a -v std # compare latest vs. saved compiler
```
* If versions appear to get out of sync (for example, with errors like
`linked object header mismatch` with version strings like
`devel go1.21-db3f952b1f`), you might need to do
`toolstash restore && go install cmd/...` to update all the tools under cmd.
#### Additional helpful tools
* [compilebench](https://pkg.go.dev/golang.org/x/tools/cmd/compilebench) benchmarks
the speed of the compiler.
* [benchstat](https://pkg.go.dev/golang.org/x/perf/cmd/benchstat) is the standard tool
for reporting performance changes resulting from compiler modifications,
including whether any improvements are statistically significant:
```
$ go test -bench=SomeBenchmarks -count=20 > new.txt # use new compiler
$ toolstash restore # restore old compiler
$ go test -bench=SomeBenchmarks -count=20 > old.txt # use old compiler
$ benchstat old.txt new.txt # compare old vs. new
```
* [bent](https://pkg.go.dev/golang.org/x/benchmarks/cmd/bent) facilitates running a
large set of benchmarks from various community Go projects inside a Docker container.
* [perflock](https://github.com/aclements/perflock) helps obtain more consistent
benchmark results, including by manipulating CPU frequency scaling settings on Linux.
* [view-annotated-file](https://github.com/loov/view-annotated-file) (from the community)
overlays inlining, bounds check, and escape info back onto the source code.
* [godbolt.org](https://go.godbolt.org) is widely used to examine
and share assembly output from many compilers, including the Go compiler. It can also
[compare](https://go.godbolt.org/z/5Gs1G4bKG) assembly for different versions of
a function or across Go compiler versions, which can be helpful for investigations and
bug reports.
#### -gcflags and 'go build' vs. 'go tool compile'
* `-gcflags` is a go command [build flag](https://pkg.go.dev/cmd/go#hdr-Compile_packages_and_dependencies).
`go build -gcflags=<args>` passes the supplied `<args>` to the underlying
`compile` invocation(s) while still doing everything that the `go build` command
normally does (e.g., handling the build cache, modules, and so on). In contrast,
`go tool compile <args>` asks the `go` command to invoke `compile <args>` a single time
without involving the standard `go build` machinery. In some cases, it can be helpful to have
fewer moving parts by doing `go tool compile <args>`, such as if you have a
small standalone source file that can be compiled without any assistance from `go build`.
In other cases, it is more convenient to pass `-gcflags` to a build command like
`go build`, `go test`, or `go install`.
* `-gcflags` by default applies to the packages named on the command line, but can
use package patterns such as `-gcflags='all=-m=1 -l'`, or multiple package patterns such as
`-gcflags='all=-m=1' -gcflags='fmt=-m=2'`. For details, see the
[cmd/go documentation](https://pkg.go.dev/cmd/go#hdr-Compile_packages_and_dependencies).
### Further reading
To dig deeper into how the SSA package works, including its passes and rules,
head to [cmd/compile/internal/ssa/README.md](internal/ssa/README.md).
Finally, if something in this README or the SSA README is unclear
or if you have an idea for an improvement, feel free to leave a comment in
[issue 30074](https://go.dev/issue/30074).