cmd/go: clarify documentation for DefaultGODEBUG

[findleyr]

The documentation for DefaultGODEBUG at https://go.dev/doc/godebug says "Only differences from the base Go toolchain defaults are reported.", but that's not the case: consider that x/tools/cmd/eg sets gotypesalias=1 in a //go:debug directive. Yet:

• GOTOOLCHAIN=go1.22.0 go list -f {{.DefaultGODEBUG}} ./cmd/eg returns nothing
• GOTOOLCHAIN=go1.23.1 go list -f {{.DefaultGODEBUG}} ./cmd/eg reports gotypesalias=1, even though that's the default

I will send a fix to ./cmd/go/internal/load/godebug.go.

CC @rsc @timothy-king @adonovan

[gabyhelp]

Related Issues

• go/types: gotypesalias missing calls to IncNonDefault #66216 (closed)
• runtime/debug: BuildSetting does not document DefaultGODEBUG #66465
• cmd/go: `go env` does not show GODEBUG #65777 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[findleyr]

Aha, well I see now why this is the case: it's impossible to produce accurate output because nowhere are the current default values for godebug defined: it is up to each library to interpret the empty string.

At this point I don't know how to proceed. I will assert:

• DefaultGODEBUG is underdocumented.
• DefaultGODEBUG does not implement the semantics described at https://go.dev/doc/godebug.
• Given the confusion we've encountered around GODEBUG values, it would be useful if DefaultGODEBUG was accurate.

My recommendation would be to add default values to the table at internal/godebugs/table.go. However, this must have been considered in the past and deemed unnecessary. Certainly, there is a risk that it becomes redundant, or worse inaccurate.

[findleyr]

GOTOOLCHAIN=go1.22.0 go list -f {{.DefaultGODEBUG}} ./cmd/eg returns nothing

BTW: this tricked me. The reason this returns nothing is that the //go:debug directive is in a file that is also tagged //go:build go1.23. 🤦

[timothy-king]

GOTOOLCHAIN=go1.22.0 go list -f {{.DefaultGODEBUG}} ./cmd/eg returns nothing

BTW: this tricked me. The reason this returns nothing is that the //go:debug directive is in a file that is also tagged //go:build go1.23. 🤦

Yes this is the tricky solution we hit upon to only enable the type aliases GODEBUG when using a toolchain >= 1.23 while in a go.mod for 1.22 to support type parameterized aliases for 1.24.

[findleyr]

Yes this is the tricky solution we hit upon to only enable the type aliases GODEBUG when using a toolchain >= 1.23 while in a go.mod for 1.22 to support type parameterized aliases for 1.24.

Oh yeah, once I realized what was happening I remembered the background. I just wanted to explain the otherwise confusing bullet point in my original issue description.

[rsc]

Every GODEBUG setting value, like any other self-respecting Go value of type string, defaults to the empty string. As such, the behavior in the report for Go 1.23 is correct: if there is an explicit setting of "1", then it should be reported, even if the library happens to treat "" and "1" as meaning the same thing. (And as was pointed out later, the Go 1.22 behavior is also correct, because the //go:debug was guarded by a build tag.)

I can update /doc/godebug to point out that even though we often talk about GODEBUGs as (say) only having two values 0 and 1, every GODEBUG defaults to an empty string (unset), and it is up to the library defining the GODEBUG to decide how to react to the unset empty string. I agree that /doc/godebug is not clear on this point.

I'm not wild about extending the table to list non-empty default settings, because that list will grow and grow over time and fill with ancient, irrelevant settings. For example, we don't need to see panicnil=0 in all Go binaries for the rest of time. The SNR is much higher if we only report differences from what the toolchain would do with no overrides at all.

[findleyr]

Sure, just updating the doc sounds good to me.

The origin of this confusion was https://go.dev/issue/68900, where I was attempting to highlight non-default GODEBUG values when hovering over a package name. Absent a table of effective defaults, I decided that feature would be too confusing, and so decided not to implement.

For example, we don't need to see panicnil=0 in all Go binaries for the rest of time

Just to understand, where would you see this? It wouldn't show up in DefaultGODEBUG, since the setting would match its default value for the go version.