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: document build constraints in 'go help' #37018

Open
pjweinb opened this issue Feb 4, 2020 · 6 comments
Open

cmd/go: document build constraints in 'go help' #37018

pjweinb opened this issue Feb 4, 2020 · 6 comments

Comments

@pjweinb
Copy link

@pjweinb pjweinb commented Feb 4, 2020

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

go version devel +a50c3ffbd4 linux/amd64

Does this issue reproduce with the latest release?

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

go env Output
GOARCH="amd64"
GOBIN=""
GOCACHE="/usr/local/google/home/pjw/.cache/go-build"
GOENV="/usr/local/google/home/pjw/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"

What did you do?

In x/tools/internal/lsp/span/uri_windows_test.go I removed // +build window, and renamed the test function to TestURIA (to avoid conflicts with uri_test.go)

I then ran go test -run URI .

What did you expect to see?

I expected to see it run TestURI (from uri_test.go) and TestURIA (from uri_windows_test.go)

What did you see instead?

It just ran TestURI

[If I rename uri_window_test.go then go test will run TestURIA]

@stamblerre stamblerre changed the title Tests not run after removing // +build windows x/tools/gopls: invalidate metadata after a change to build tags Feb 4, 2020
@gopherbot gopherbot added this to the Unreleased milestone Feb 4, 2020
@stamblerre stamblerre modified the milestones: Unreleased, gopls/v0.4.0 Feb 4, 2020
@ALTree

This comment has been minimized.

Copy link
Member

@ALTree ALTree commented Feb 4, 2020

The build tag in the filename is preventing the test from being run. Having _GOOS_ in the filename adds a +GOOS build constraint to the file.

@pjweinbgo

This comment has been minimized.

Copy link
Contributor

@pjweinbgo pjweinbgo commented Feb 4, 2020

It would be nice if that were documented somewhere in ordinary help, rather than hoping users will paw through the source code.

@stamblerre stamblerre changed the title x/tools/gopls: invalidate metadata after a change to build tags Tests not run after removing // +build windows Feb 4, 2020
@ALTree

This comment has been minimized.

Copy link
Member

@ALTree ALTree commented Feb 4, 2020

This is documented. From https://golang.org/pkg/go/build

If a file's name, after stripping the extension and a possible _test suffix, 
matches any of the following patterns:

*_GOOS
*_GOARCH
*_GOOS_GOARCH

(example: source_windows_amd64.go) where GOOS and GOARCH 
represent any known operating system and architecture values 
respectively, then the file is considered to have an implicit build 
constraint requiring those terms (in addition to any explicit 
constraints in the file). 
@jayconrod

This comment has been minimized.

Copy link
Contributor

@jayconrod jayconrod commented Feb 4, 2020

It would be nice if that were documented somewhere in ordinary help, rather than hoping users will paw through the source code.

I agree with this. Build constraints are mentioned a few times in https://golang.org/cmd/go/, but they aren't defined. There's only one reference to the go/build package documentation under go help filetype. It's pretty hard to find.

I think we should add a go help build-constraints page that describes tags and suffixes more thoroughly, and it should be referenced from any section that mentions build constraints.

@jayconrod jayconrod changed the title Tests not run after removing // +build windows cmd/go: document build constraints in 'go help' Feb 4, 2020
@jayconrod jayconrod modified the milestones: gopls/v0.4.0, Go1.15 Feb 4, 2020
@ALTree

This comment has been minimized.

Copy link
Member

@ALTree ALTree commented Feb 4, 2020

@jayconrod

There's only one reference to the go/build package documentation under go help filetype

This is not true; the feature is pretty clearly documented in the https://golang.org/pkg/go/build section I pasted above (I mean the filename thing that is the topic of this issue).

@jayconrod

This comment has been minimized.

Copy link
Contributor

@jayconrod jayconrod commented Feb 4, 2020

Very true, but I don't think it's enough. If you're reading go help pages, it's not currently clear that you need to read the docs for go/build. go/build is only referenced twice in the context of build constraints: once in the description for the -tags flag, and again at the end of go help filetype. It's not obvious in either case that GOOS / GOARCH suffixes are meaningful.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants
You can’t perform that action at this time.