Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cmd/go: clarify package argument in 'go help run' summary #41830

brandondube opened this issue Oct 7, 2020 · 2 comments

cmd/go: clarify package argument in 'go help run' summary #41830

brandondube opened this issue Oct 7, 2020 · 2 comments
Documentation NeedsFix


Copy link

@brandondube brandondube commented Oct 7, 2020

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

$ go version
go version go1.14.4 darwin/amd64

Does this issue reproduce with the latest release?

I don't know

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

go env Output
$ go env
GOENV="/Users/bdube/Library/Application Support/go/env"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/1m/s4hjpz8s4wxfmj189l4chx30z_vgf2/T/go-build827010893=/tmp/go-build -gno-record-gcc-switches -fno-common

What did you do?

run go run main.go in a directory containing:

├── lib.go
├── main.go

What did you expect to see?

A successful compilation, on the basis that go help run begins with

$go help run
usage: go run [build flags] [-exec xprog] package [arguments...]

Run compiles and runs the named main Go package.

I wish to emphasize package and not file.

What did you see instead?

$ go run main.go
# command-line-arguments
./main.go:28:26: undefined: Config
./main.go:101:7: undefined: Config
./main.go:118:7: undefined: Config
./main.go:131:7: undefined: Config
./main.go:136:9: undefined: BuildMux

(build errors due to undefined symbols from lib.go)

The documentation for Go is very explicit in what a package is:

A package is a collection of source files in the same directory that are compiled together.


The output of $ go help packages perhaps disagrees:

$ go help packages 
Many commands apply to a set of packages:

	go action [packages]

Usually, [packages] is a list of import paths.

An import path that is a rooted path or that begins with
a . or .. element is interpreted as a file system path and
denotes the package in that directory.

Otherwise, the import path P denotes the package found in
the directory DIR/src/P for some DIR listed in the GOPATH
environment variable (For more details see: 'go help gopath').

If no import paths are given, the action applies to the
package in the current directory.

It may disagree on the basis of what an import path means. If import path ~= folder, then the file main.go is not a package, but the set of .go files in the directory is a package.

If we are to say that main.go is given as an identifier for its package, then go run main.go should pull in all source files for the package. I think that if main.go is given as a package in and of itself, this is different to an import path in the usual semantics of the language and the documentation (and wealth of tutorials, books, and so forth) about the language should also be updated.

Copy link

@bcmills bcmills commented Oct 7, 2020

You mentioned go help packages, but didn't get to the paragraph that covers this case:

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.

In that case, the “package” is still “a collection of source files in the same directory that are compiled together“ — it's just that the subset of the directory included in the package is determined by the command-line arguments rather than the usual build constraints.

@bcmills bcmills changed the title cmd/go: run behavior does not agree with docs for pkg main with more than one file cmd/go: clarify package argument in 'go help run' summary Oct 7, 2020
@bcmills bcmills added the NeedsFix label Oct 7, 2020
@bcmills bcmills added this to the Backlog milestone Oct 7, 2020
Copy link

@brandondube brandondube commented Oct 8, 2020

I guess the interpretation boils down to where the active word in the sentence "A package is a collection of source files in the same directory that are compiled together." is. If being in the same directory is acting, then it states that all go files in a directory must be in the same package. It is a compiler (linter? At least tooling...) error when you have files that declare different packages in the same directory. The majority of writing on Go nods in that direction.

If being in the same directory is passive (a requirement, but not defining), then I would say the behavior of go build main.go in this case is correct, otherwise I believe it is a bug.

There is a meta topic, too, of what determines what a package is at all -- can command line arguments restrict the scope of consideration for being a package? Why? Do the language rules allow sufficient ambiguity for there to be interpretation? Isn't the point of the language to be completely explicit, always, and remove ambiguity?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Documentation NeedsFix
None yet

No branches or pull requests

3 participants