cmd/go: mod list type Module is missing toolchain version

[egonk7615]

See https://github.com/golang/go/blob/master/src/cmd/go/internal/list/list.go

    type Module struct {
        Path       string        // module path
        Query      string        // version query corresponding to this version
        Version    string        // module version
        Versions   []string      // available module versions
        Replace    *Module       // replaced by this module
        Time       *time.Time    // time version was created
        Update     *Module       // available update (with -u)
        Main       bool          // is this the main module?
        Indirect   bool          // module is only indirectly needed by main module
        Dir        string        // directory holding local copy of files, if any
        GoMod      string        // path to go.mod file describing module, if any
        GoVersion  string        // go version used in module
        Retracted  []string      // retraction information, if any (with -retracted or -u)
        Deprecated string        // deprecation message, if any (with -u)
        Error      *ModuleError  // error loading module
        Sum        string        // checksum for path, version (as in go.sum)
        GoModSum   string        // checksum for go.mod (as in go.sum)
        Origin     any           // provenance of module
        Reuse      bool          // reuse of old module info is safe
    }

    type ModuleError struct {
        Err string // the error itself
    }

We have GoVersion string // go version used in module, which contains go X.Y.Z directive.

It would be nice to have something like GoToolchain string too which would contain toolchain goX.Y.Z directive.

[matloob]

Hi, I'm interested what the use case for this is?

We have the go version in the module because the go version determines the semantics of the module. But the toolchain only affects (and is just one of the factors in) the selection of the toolchain that's run for the module. And toolchains of dependency modules don't affect the build at all.

[egonk7615]

@matloob

One is from the completeness perspective to record the directives that affect builds, it seems like an oversight?

But more concretely, we set GOTOOLCHAIN=local and take (parse) the Go version from toolchain directive in our builds. We also have a script to check the output of list command so it matches the expectations exactly (versions of dependencies, etc). That's where I noticed we could also check the toolchain directive of the main module.

[seankhliao]

i think this ties in with #75331 wanting to use the toolchain directive as the canonical setting for identifying the go toolchain version.

[matloob]

@egonk7615 So I think a good analogue for toolchain is the godebug directive. It does affect the default godebug setting for a build, but it does so indirectly, through influencing the the determination of the godebug settings, which can also be influenced by other factors such as the GODEBUG environment variable. So it ends up giving an incomplete picture. Or the replace, which contains the resolved replacement module rather than the set of directives in the file.

But more concretely, we set GOTOOLCHAIN=local and take (parse) the Go version from toolchain directive in our builds. We also have a script to check the output of list command so it matches the expectations exactly (versions of dependencies, etc). That's where I noticed we could also check the toolchain directive of the main module.

To make sure I understand are you saying that you have a build system or makefile that determines the go version using the toolchain directive and uses that version to do a build instead of using the go command's toolchain selection mechanism? I think for that use case, if you want to check the toolchain version in the go.mod file, you could use go mod edit -json. It will print a JSON representation of the go.mod file that you could check for the toolchain directive.

So for example, for a module with go.mod:

module example.com/mod

go 1.24.0

toolchain go1.25.0

it will output

{
	"Module": {
		"Path": "example.com/mod"
	},
	"Go": "1.24.0",
	"Toolchain": "go1.25.0",
	"Require": null,
	"Exclude": null,
	"Replace": null,
	"Retract": null,
	"Tool": null,
	"Ignore": null
}

and you can extract the JSON from the output to get the toolchain without needing to use golang.org/x/mod/modfile.Parse to parse the go.mod file. go mod edit doesn't have a template mechanism, but using -json without other arguments is the better way to get information about the contents of a go.mod file for tools rather than using go list -m whose purpose is to give you the 'resolved' information about the modules used to do a build.

[egonk7615]

@matloob

To make sure I understand are you saying that you have a build system or makefile that determines the go version using the toolchain directive and uses that version to do a build instead of using the go command's toolchain selection mechanism? I think for that use case, if you want to check the toolchain version in the go.mod file, you could use go mod edit -json. It will print a JSON representation of the go.mod file that you could check for the toolchain directive.

We have something even simpler already, we build in both Powershell and Bash with a simple ^toolchain (.*)$ regex.

However the issue that I reported here is related to another script that we use:

			args := []string{"list", "-deps", "-f", "{{with .Module}}{{if .Main}}go {{.GoVersion}}{{end}}{{end}}{{with .Module}}{{if not .Main}}{{.Path}} {{.Version}}{{with .Replace}} => {{if .Version}}{{.}}{{else}}{{.Dir}}{{end}}{{end}}{{end}}{{end}}"}
			args = append(args, "-test", "./...")
			c := exec.Command("go", args...)

We use it to check the deps before the builds even run. I thought it would be nice if I could include toolchain in the report:

{{with .Module}}{{if .Main}}go {{.GoVersion}}, toolchain {{.GoToolchain}}{{end}}{{end}}{{with .Module}}{{if not .Main}}{{.Path}} {{.Version}}{{with .Replace}} => {{if .Version}}{{.}}{{else}}{{.Dir}}{{end}}{{end}}{{end}}{{end}}