cmd/go: add support for godebug lines in go.mod and go.work

The fact that the go line sets both the language version and the
GODEBUG compatibility version can be a problem, especially since
the go line is also required to be ≥ the go lines of any required
dependency modules.

This change adds a new 'godebug' line to go.mod and go.work
to allow setting the GODEBUG values for the entire module.

It also adds a new meta-value default=go1.21 that means
take the defaults from Go 1.21 no matter what the go line says.

These were discussed in proposal #65573.

Fixes #65573.

Change-Id: I91746322a10178370ed1015ce5278372a024c824
Reviewed-on: https://go-review.googlesource.com/c/go/+/584476
Auto-Submit: Russ Cox <rsc@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Reviewed-by: Michael Matloob <matloob@golang.org>

1 files changed, 28 insertions, 4 deletions

diff --git a/doc/godebug.md b/doc/godebug.md
index 7dbdfa9a78..4cbc85f941 100644
--- a/doc/godebug.md
+++ b/doc/godebug.md
@@ -88,14 +88,38 @@ Because this method of setting GODEBUG defaults was introduced only in Go 1.21,
 programs listing versions of Go earlier than Go 1.20 are configured to match Go 1.20,
 not the older version.
 
-To override these defaults, a main package's source files
+To override these defaults, starting in Go 1.23, the work module's `go.mod`
+or the workspace's `go.work` can list one or more `godebug` lines:
+
+	godebug (
+		default=go1.21
+		panicnil=1
+		asynctimerchan=0
+	)
+
+The special key `default` indicates a Go version to take unspecified
+settings from. This allows setting the GODEBUG defaults separately
+from the Go language version in the module.
+In this example, the program is asking for Go 1.21 semantics and
+then asking for the old pre-Go 1.21 `panic(nil)` behavior and the
+new Go 1.23 `asynctimerchan=0` behavior.
+
+Only the work module's `go.mod` is consulted for `godebug` directives.
+Any directives in required dependency modules are ignored.
+It is an error to list a `godebug` with an unrecognized setting.
+(Toolchains older than Go 1.23 reject all `godebug` lines, since they do not
+understand `godebug` at all.)
+
+The defaults from the `go` and `godebug` lines apply to all main
+packages that are built. For more fine-grained control,
+starting in Go 1.21, a main package's source files
 can include one or more `//go:debug` directives at the top of the file
 (preceding the `package` statement).
-Continuing the `panicnil` example, if the module or workspace is updated
-to say `go` `1.21`, the program can opt back into the old `panic(nil)`
-behavior by including this directive:
+The `godebug` lines in the previous example would be written:
 
+	//go:debug default=go1.21
 	//go:debug panicnil=1
+	//go:debug asynctimerchan=0
 
 Starting in Go 1.21, the Go toolchain treats a `//go:debug` directive
 with an unrecognized GODEBUG setting as an invalid program.