cmd/go: clarify doc that go commands like 'go build' are not always sufficient to update go.mod and 'go mod -sync' is sometimes required to handle variability due to GOOS/GOARCH/build tags

[thepudds]

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

go version devel +08ab820 Tue Jul 24 09:23:08 2018 +0000 windows/amd64

Does this issue reproduce with the latest release?

Yes (tip).

What operating system and processor architecture are you using (go env)?

set GOARCH=amd64
set GOBIN=
set GOCACHE=C:\Users\thepudds\AppData\Local\go-build
set GOEXE=.exe
set GOHOSTARCH=amd64
set GOHOSTOS=windows
set GOOS=windows
set GOPATH=C:\thepudds_projects\go_home
set GOPROXY=
set GORACE=
set GOROOT=C:\Go
set GOTMPDIR=
set GOTOOLDIR=C:\Go\pkg\tool\windows_amd64
set GCCGO=gccgo
set CC=gcc
set CXX=g++
set CGO_ENABLED=0
set GOMOD=
set CGO_CFLAGS=-g -O2
set CGO_CPPFLAGS=
set CGO_CXXFLAGS=-g -O2
set CGO_FFLAGS=-g -O2
set CGO_LDFLAGS=-g -O2
set PKG_CONFIG=pkg-config
set GOGCCFLAGS=-m64 -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=C:\Users\thepudds\AppData\Local\Temp\go-build914143802=/tmp/go-build -gno-record-
gcc-switches

What did you do?

go help modules
go help mod

What did you expect to see?

Additional doc for go mod -sync.

What did you see instead?

I realize the documentation for versioned Go modules is still a work-in-progress, but wanted to submit this issue in case it helps...

Brief background:

#25971 was closed as working as intended. Some pertinent snippets:

@kardianos wrote:

go build should be lazy and do minimal work for that GOOS, GOARCH, and tag-set.

go mod x is for managing the mod requirements regardless of the current system setup.

In the reply, @bcmills wrote:

vgo build does the minimal work needed to satisfy the imports of the requested packages for that particular build invocation. So I think this is working as intended.

Personally, I would recommend vgo build as the default during development, plus a vgo mod -sync in any commit to be tagged for release.

If that indeed is the intended behavior, it seems the documentation should be updated to more clearly make that distinction in behavior between go commands like 'go build' vs. 'go mod -sync'.

Current snippet from go help modules (the final sentence in 'Defining a module' section):

Once the go.mod file exists, no additional steps are required:
go commands like 'go build', 'go test', or even 'go list' will automatically
add new dependencies as needed to satisfy imports.

I'm not sure that sentence from go help modules as it stands is correct, or at least it seems to gloss over the subtlety of build tags, etc., and hence it seems possible to mis-read that sentence as implying that new dependencies always will be added automatically just using go commands like 'go build', 'go test', etc. (It is instead apparently the case that 'go build' will only add new dependencies as needed to satisfy imports for that particular build invocation (e.g., as described in snippets above from #25971)).

Later, in the 'Maintaining module requirements' section of go help modules, there is this:

Any go command can determine that a module requirement is
missing and must be added, even when considering only a single
package from the module. On the other hand, determining that a module requirement
is no longer necessary and can be deleted requires a full view of
all packages in the module, across all possible build configurations
(architectures, operating systems, build tags, and so on).
The 'go mod -sync' command builds that view and then
adds any missing module requirements and removes unnecessary ones.

There is an implication there or at least a possible mis-reading that 'go mod -sync' is required to have greater visibility to be able to prune requirements that are no longer necessary, but that "Any go command" has enough visibility to add missing requirements (which does not seem to agree with the snippets quoted above from #25971). There is mention there of go mod -sync having a view of all possible build configurations, but the implications of what a user should do and when a user should use -sync are not explicit (especially if the reader is someone who is not steeped in the mechanisms of go build, build tags, etc.).

There are a couple points made elsewhere in 'Maintaining module requirements' section that use softer language (e.g., "In most cases, therefore, it suffices to add an import to source code and run 'go build', 'go test', or even 'go list': as part of analyzing the package, the go command will discover and resolve the import and update the go.mod file."), but overall it is not as explicit as it could be.

In addition, the documentation for the -sync flag in 'go help mod' doesn't mention anything regarding build tags/GOOS/GOARCH:

Snippet from go help mod:

The -sync flag synchronizes go.mod with the source code in the module.
It adds any missing modules necessary to build the current module's
packages and dependencies, and it removes unused modules that
don't provide any relevant packages. It also adds any missing entries
to go.sum and removes any unnecessary ones.

Finally, the following issue is a related issue regarding clarifying a separate/additional use case for when go mod -sync is required for indirect dependencies:

#26474 "cmd/go: clarify doc for go get <module> and indirect dependencies"

(edit: fixed link)

[thepudds]

@gopherbot, please add label modules

[thepudds]

This documentation issue might get resolved as part of #26581 "cmd/go: mod is too much of a grab bag"

[rsc]

This all seems far too subtle to try to call out in the help text for 'go build'. 'go mod tidy' exists.