cmd/go: some documentation issues for new 1.24 'go tool' features #71663
Comments
|
Change https://go.dev/cl/648577 mentions this issue: |
|
Change https://go.dev/cl/648578 mentions this issue: |
Mention -modfile, -C, -overlay, and -modcacherw in the 'go tool' documentation. We let a reference to 'go help build' give a pointer to more detailed information. The -modfile flag in particular is newly useful with the Go 1.24 support for user-defined tools with 'go tool'. Updates #48429 Updates #33926 Updates #71663 Fixes #71502 Change-Id: Ida67df50ff774a0886733d661a40e27c2cadc0f6 Reviewed-on: https://go-review.googlesource.com/c/go/+/648577 LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com> Reviewed-by: Conrad Irwin <conrad.irwin@gmail.com> Reviewed-by: Michael Matloob <matloob@golang.org> Reviewed-by: Sam Thanawalla <samthanawalla@google.com> Auto-Submit: Sam Thanawalla <samthanawalla@google.com>
dmitshur
added
the
NeedsFix
|
We also need to add some documentation to the website for other Go Command features.
|
|
Somehow related: The vscode go extension might also need to be upgraded to accommodate for tools. After clicking upgrade direct dependencies vscode pulls in a bunch of not needed dependencies, which are removed once you run go mod tidy. This might be confusing, especially for new go developers. |
|
@hu3bi Report here: https://github.com/golang/vscode-go |
|
@dolmen Thank you and sorry. Should have known better. |
"Managing module dependencies":
a. The text seems to imply
-uis needed to upgrade tools, but the -u is not actually needed and often is undesirable. (This was also a problem in the release notes as well; I previously sent https://go.dev/cl/638296 to address in the release notes).Modules reference:
a.
go getsection is missing-toolflag.b.
go installsection doesn't mentiongo install tool. (It also somewhat implies it wouldn't work because it says 'go install' can't take meta-pattern, which we should also probably tweak).c. Most new-ish capabilities have a "Since Go 1.x" or a similar phrase, but the tools description does not (e.g., in https://go.dev/ref/mod#go-mod-file-tool).
d. No 'go tool' section. (Maybe this is OK for now given the documentation elsewhere, but could include a short section with a link for details).
cmd/go documentation
go toolsection:a. Does not mention needing to use full package path for
go toolin some cases.b. No mention of
go toolwithout args to list available tools.c. No -modfile mentioned (cmd/go: missing flags in help output for tool #71502).
d. These overlap with the help text shown at the command line in cmd/go.
1.24 release notes:
a. Ideally the release notes would mention the -modfile flag. (For example, see #71502, #48429 (comment), or various other recent & older comments on #48429, #33926 and elsewhere).
Opening this issue for discussion. I plan to send some CLs. It seems Go 1.24 official release is very close, so maybe some or all of these are adjustments for later.
For these new capabilities, I think the "Managing Dependencies" doc is currently the most comprehensive and also the easiest to digest, so probably reasonable to link to there from some of the other doc.
There are some other more minor issues, but I wanted to at least try to address some of these. Finally, one additional caveat is this writeup is based on some older notes I had taken, and I need to double-check some of it again.
The text was updated successfully, but these errors were encountered: