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

Jump to bottom

cmd/go: confusing documentation on build tags #53308

Closed
gazerro opened this issue Jun 9, 2022 · 10 comments
Closed

cmd/go: confusing documentation on build tags #53308

gazerro opened this issue Jun 9, 2022 · 10 comments
Assignees
@ianlancetaylor
Labels
Documentation FrozenDueToAge GoCommand cmd/go NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone
Backlog

Comments

@gazerro
Copy link
Contributor

gazerro commented Jun 9, 2022

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

go1.18.3

Does this issue reproduce with the latest release?

Yes.

What did you do?

The go command documentation (https://pkg.go.dev/cmd/go@master) reports

-tags tag,list
	a comma-separated list of build tags to consider satisfied during the
	build. For more information about build tags, see the description of
	build constraints in the documentation for the go/build package.

So tag and list in the example are called "build tags". I open the description of build constraints in the go/build package documentation (https://pkg.go.dev/go/build#hdr-Build_Constraints) and it reports:

A build constraint, also known as a build tag, is a line comment that begins

//go:build

So the tag option of the go command wants a list of line comments? And which "build tags" can be used with the go command?

What did you expect to see?

The values ​​that can be used for the tag option of the go command.

What did you see instead?

Confusing documentation on build tags.
@seankhliao
Copy link
Member

go/build links to https://pkg.go.dev/cmd/go#hdr-Build_constraints for details.

@gazerro
Copy link
Contributor Author

gazerro commented Jun 9, 2022 •
edited

@seankhliao cmd/go says to read go/build and go/build link back to cmd/go and even this latest documentation does not resolve what I have indicated in this issue.

@fzipp
Copy link
Contributor

fzipp commented Jun 9, 2022 •
edited

I'd say the "also known as a build tag" part is wrong. "darwin" and "cgo" are build tags, the whole //go:build line is a build constraint using build tags, but not a build tag itself.

@fzipp
Copy link
Contributor

fzipp commented Jun 9, 2022

This was added on purpose: https://codereview.appspot.com/44100043
Contrary to the commit message I don't think it made things clearer.

@cherrymui cherrymui added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Jun 9, 2022
@cherrymui cherrymui added this to the Backlog milestone Jun 9, 2022
@cherrymui
Copy link
Member

cc @rsc @bcmills

@cherrymui cherrymui added the GoCommand cmd/go label Jun 9, 2022
@ianlancetaylor ianlancetaylor self-assigned this Jun 10, 2022
@gopherbot
Copy link

Change https://go.dev/cl/411697 mentions this issue: cmd/go, go/build: clarify build constraint docs

@gazerro
Copy link
Contributor Author

gazerro commented Jun 11, 2022

To clarify, I would also suggest adding the term "additional" to the documentation of the -tags flag

a comma-separated list of additional build tags to consider satisfied during the build.

as already used in the build constraints documentation by referring to the -tags flag.

@ianlancetaylor
Copy link
Contributor

@gazerro Thanks, I made that change in https://go.dev/cl/411697.

@gazerro
Copy link
Contributor Author

gazerro commented Jun 11, 2022

@ianlancetaylor Thanks. I just noticed a typo in the same line, 'go help buildconstraints' should be 'go help buildconstraint'.

@ianlancetaylor
Copy link
Contributor

@gazerro Thanks, fixed.

jproberts pushed a commit to jproberts/go that referenced this issue Aug 10, 2022
@ianlancetaylor @jproberts
cmd/go, go/build: clarify build constraint docs
95bcfd9 
Clarify that the //go:build line is an expression of constraints,
not a constraint itself.

Fixes golang#53308

Change-Id: Ib67243c6ee5cfe3b688c12b943b5e7496f686035
Reviewed-on: https://go-review.googlesource.com/c/go/+/411697
Reviewed-by: Rob Pike <r@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Run-TryBot: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: David Chase <drchase@google.com>
@golang golang locked and limited conversation to collaborators Jul 1, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@ianlancetaylor ianlancetaylor

Labels
Documentation FrozenDueToAge GoCommand cmd/go NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
6 participants
@fzipp @gazerro @ianlancetaylor @gopherbot @seankhliao @cherrymui