1// Copyright 2023 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
5Notes on the format of the testcase files in
6cmd/compile/internal/inline/inlheur/testdata/props:
7
8- each (compilable) file contains input Go code and expected results
9 in the form of column-0 comments.
10
11- functions or methods that begin with "T_" are targeted for testing,
12 as well as "init" functions; all other functions are ignored.
13
14- function header comments begin with a line containing
15 the file name, function name, definition line, then index
16 and a count of the number of funcs that share that same
17 definition line (needed to support generics). Example:
18
19 // foo.go T_mumble 35 1 4
20
21 Here "T_mumble" is defined at line 35, and it is func 0
22 out of the 4 funcs that share that same line.
23
24- function property expected results appear as comments in immediately
25 prior to the function. For example, here we have first the function
26 name ("T_feeds_if_simple"), then human-readable dump of the function
27 properties, as well as the JSON for the properties object, each
28 section separated by a "<>" delimiter.
29
30 // params.go T_feeds_if_simple 35 0 1
31 // RecvrParamFlags:
32 // 0: ParamFeedsIfOrSwitch
33 // <endpropsdump>
34 // {"Flags":0,"RecvrParamFlags":[8],"ReturnFlags":[]}
35 // callsite: params.go:34:10|0 "CallSiteOnPanicPath" 2
36 // <endcallsites>
37 // <endfuncpreamble>
38 func T_feeds_if_simple(x int) {
39 if x < 100 {
40 os.Exit(1)
41 }
42 println(x)
43 }
44
45- when the test runs, it will compile the Go source file with an
46 option to dump out function properties, then compare the new dump
47 for each function with the JSON appearing in the header comment for
48 the function (in the example above, the JSON appears between
49 "<endpropsdump>" and "<endfuncpreamble>". The material prior to the
50 dump is simply there for human consumption, so that a developer can
51 easily see that "RecvrParamFlags":[8] means that the first parameter
52 has flag ParamFeedsIfOrSwitch.
53
54- when making changes to the compiler (which can alter the expected
55 results) or edits/additions to the go code in the testcase files,
56 you can remaster the results by running
57
58 go test -v -count=1 .
59
60 In the trace output of this run, you'll see messages of the form
61
62 === RUN TestFuncProperties
63 funcprops_test.go:NNN: update-expected: emitted updated file
64 testdata/props/XYZ.go.new
65 funcprops_test.go:MMM: please compare the two files, then overwrite
66 testdata/props/XYZ.go with testdata/props/XYZ.go.new
67
68 at which point you can compare the old and new files by hand, then
69 overwrite the *.go file with the *.go.new file if you are happy with
70 the diffs.
71
72- note that the remastering process will strip out any existing
73 column-0 (unindented) comments; if you write comments that you
74 want to see preserved, use "/* */" or indent them.
75
76
77
View as plain text