github.com/go-asm/go@v1.21.1-0.20240213172139-40c5ead50c48/cmd/compile/inline/inlheur/testdata/props/README.txt (about)

     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  
     5  Notes on the format of the testcase files in
     6  github.com/go-asm/go/cmd/compile/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