doc: clarify the interaction between modules and synthesized packages

[perillo]

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

$ go version
go version go1.16.4 linux/amd64

Does this issue reproduce with the latest release?

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

go env Output

$ go env
GO111MODULE="on"
GOARCH="amd64"
GOBIN="/home/manlio/.local/bin"
GOCACHE="/home/manlio/.cache/go-build"
GOENV="/home/manlio/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE="*.local"
GOMODCACHE="/home/manlio/.local/lib/go/pkg/mod"
GONOPROXY=""
GONOSUMDB="*.local"
GOOS="linux"
GOPATH="/home/manlio/.local/lib/go:/home/manlio/src/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/usr/lib/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/usr/lib/go/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="go1.16.4"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/dev/null"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build1005692883=/tmp/go-build -gno-record-gcc-switches"
GOROOT/bin/go version: go version go1.16.4 linux/amd64
GOROOT/bin/go tool compile -V: compile version go1.16.4
uname -sr: Linux 5.12.7-arch1-1
/usr/lib/libc.so.6: GNU C Library (GNU libc) release release version 2.33.
gdb --version: GNU gdb (GDB) 10.2

What did you do?

The packages help topic (go help packages or https://golang.org/pkg/cmd/go/#hdr-Package_lists_and_patterns), says:

As a special case, if the package list is a list of .go files from a
single directory, the command is applied to a single synthesized
package made up of exactly those files, ignoring any build constraints
in those files and ignoring any other files in the directory.

The following command, as an example, works

go build /abs/path/to/file.go

The problem is that, in module mode, a package must belong to a module, so in theory go build should fail as in

cd /abs/path/to
go build

go: go.mod file not found in current directory or any parent directory; see 'go help modules'

The documentation should say that a module is also synthesized.

[perillo]

When file.go imports a remote package,

cd /abs/path/to
go build /abs/path/to/file.go

fails with:

file.go:3:8: no required module provides package golang.org/x/term: go.mod file not found in current directory or any parent directory; see 'go help modules'

If I add a go.mod file in /abs/path/to directory, the output is:

file.go:3:8: no required module provides package golang.org/x/term; to add it:
	go get golang.org/x/term

If go build is run from a different directory, the /abs/path/to/go.mod file is not recognized. Instead the go tool recognizes the go.mod file in the current directory.

If this is the intended behavior, it should be documented.

[perillo]

@bcmills do you think this is a possible issue for cmd/go implementation?

go run /abs/path/to/file.go

also fail with the same error

file.go:3:8: no required module provides package golang.org/x/term; to add it:
	go get golang.org/x/term

But I think the error message is confusing, since in this case go get will probably fail or, worse, update the wrong go.mod file.

In this case cmd/go should either report an error like

file.go:3:8: package golang.org/x/term is not accessible`

or it should synthesize a go.mod file and do the equivalent of go mod tidy.

[seankhliao]

https://golang.org/cmd/go/#hdr-The_go_mod_file says

... When the go command is run, it looks in the current directory and then successive parent directories to find the go.mod marking the root of the main (current) module.

---

The suggested command is the correct one for the previous one (go run /abs/path) to succeed (update to main module (see prev section) to include the dependency).
I think the suggested error message is even more opaque.
Though this message may change for #44961

---

synthesized module with dependencies for run is #42088

[perillo]

There are two problems:

1. The documentation says the command is applied to a single synthesized package made up of exactly those files.
   One interpretation is that the go.mod file is not included.
2. It is possible to run go run /abs/path/to/file.go from a directory different from the one containing file.go.
   The same with go build.

Thanks.

[seankhliao]

I don't see why 2 is a problem, a package is synthesized and run in the context of the current module, and it's an error if the current/main module doesn't provide all the necessary dependencies

[perillo]

IMHO, 2 is a problem for the same reason why go get pkg@version must ignore any go.mod in the current directory or parent directories.

[seankhliao]

go get pkg@version is the command for updating the current module. Are you thinking of go install pkg@version?
If so those are separate issues, run: #42088 build: 44469

[perillo]

Yes, I was thinking of go install pkg@version. To be more precise, about:

- No module is considered the "main" module. If the module containing
packages named on the command line has a go.mod file, it must not contain
directives (replace and exclude) that would cause it to be interpreted
differently than if it were the main module. The module must not require
a higher version of itself.

I think that something similar should also apply to a synthesized package.

The main problem with a synthesized package is that it currently uses the go.mod reachable from the current directory, so the behavior depends from the directory where the go command is invoked.

Thanks.

[perillo]

Reading the source code of cmd/go, I noted that the documentation does not report that the cgo build constraint is not ignored for synthesized packages

[perillo]

Another possible confusing error. When a non existing .go absolute file is specified, cmd/go reports a different error:

go run /abs/path/to/nofile.go

go: go.mod file not found in current directory or any parent directory; see 'go help modules'

[bcmills]

The main problem with a synthesized package is that it currently uses the go.mod reachable from the current directory, so the behavior depends from the directory where the go command is invoked.

The behavior of the go command always depends on the directory where it is invoked. That property is not specific to synthesized packages — for example, it also applies to packages specified as (absolute) filesystem directory paths.