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: confusing documentation on build tags #53308

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

cmd/go: confusing documentation on build tags #53308

gazerro opened this issue Jun 9, 2022 · 10 comments
Assignees
Labels
Documentation GoCommand NeedsDecision
Milestone

Comments

@gazerro
Copy link
Contributor

@gazerro 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
Contributor

@seankhliao seankhliao commented Jun 9, 2022

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

@gazerro
Copy link
Contributor Author

@gazerro gazerro commented Jun 9, 2022

@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 fzipp commented Jun 9, 2022

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 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 label Jun 9, 2022
@cherrymui cherrymui added this to the Backlog milestone Jun 9, 2022
@cherrymui
Copy link
Member

@cherrymui cherrymui commented Jun 9, 2022

cc @rsc @bcmills

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

@gopherbot gopherbot commented Jun 10, 2022

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

@gazerro
Copy link
Contributor Author

@gazerro 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

@ianlancetaylor ianlancetaylor commented Jun 11, 2022

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

@gazerro
Copy link
Contributor Author

@gazerro 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

@ianlancetaylor ianlancetaylor commented Jun 11, 2022

@gazerro Thanks, fixed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation GoCommand NeedsDecision
Projects
None yet
Development

No branches or pull requests

6 participants