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.

Sign up for GitHub

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: tidy behavior regarding ignore tag is hard to find #54993

Open
mem opened this issue Sep 10, 2022 · 4 comments · May be fixed by #54998
Open

cmd/go: tidy behavior regarding ignore tag is hard to find #54993

mem opened this issue Sep 10, 2022 · 4 comments · May be fixed by #54998
Labels
Documentation GoCommand cmd/go help wanted NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone
Backlog

Comments

@mem
Copy link

mem commented Sep 10, 2022

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

go env Output
$ go env
not applicable

What did you do?

I was working with ruleguard, which recommends to use the ignore tag to exclude rules form the build.

Quoting from https://github.com/quasilyte/go-ruleguard/blob/master/README.md?plain=1#L72

// +build ignore

package gorules

import "github.com/quasilyte/go-ruleguard/dsl"
...

ruleguard fails to run because the package github.com/quasilyte/go-ruleguard/dsl is not listed in the main module's go.mod file and because of the way it works, it needs to have this package available.

After running:

go get github.com/quasilyte/go-ruleguard/dsl

ruleguard works.

But after running go mod tidy, ruleguard fails again.

Going over go.mod, the package is no longer listed.

What did you expect to see?

The package github.com/quasilyte/go-ruleguard/dsl is still present in go.mod after running go mod tidy.

What did you see instead?

The package github.com/quasilyte/go-ruleguard/dsl is gone from go.mod after running go mod tidy.

It turns out the problem is that go mod tidy will handle the ignore tag in a different way, as mentioned in https://go.dev/ref/mod#go-mod-tidy, which is referenced from the output of go help mod tidy:

go mod tidy works by loading all of the packages in the main module and all of the packages they import, recursively. This includes packages imported by tests (including tests in other modules). go mod tidy acts as if all build tags are enabled, so it will consider platform-specific source files and files that require custom build tags, even if those source files wouldn’t normally be built. There is one exception: the ignore build tag is not enabled, so a file with the build constraint // +build ignore will not be considered. Note that go mod tidy will not consider packages in the main module in directories named testdata or with names that start with . or _ unless those packages are explicitly imported by other packages.

The detail about ignore is not minor, and it should be more readily available.
@mem
Copy link
Author

mem commented Sep 10, 2022

I should be more clear:

This is the output of go help mod tidy:

go help mod tidy
usage: go mod tidy [-e] [-v] [-go=version] [-compat=version]

Tidy makes sure go.mod matches the source code in the module.
It adds any missing modules necessary to build the current module's
packages and dependencies, and it removes unused modules that
don't provide any relevant packages. It also adds any missing entries
to go.sum and removes any unnecessary ones.

The -v flag causes tidy to print information about removed modules
to standard error.

The -e flag causes tidy to attempt to proceed despite errors
encountered while loading packages.

The -go flag causes tidy to update the 'go' directive in the go.mod
file to the given version, which may change which module dependencies
are retained as explicit requirements in the go.mod file.
(Go versions 1.17 and higher retain more requirements in order to
support lazy module loading.)

The -compat flag preserves any additional checksums needed for the
'go' command from the indicated major Go release to successfully load
the module graph, and causes tidy to error out if that version of the
'go' command would load any imported package from a different module
version. By default, tidy acts as if the -compat flag were set to the
version prior to the one indicated by the 'go' directive in the go.mod
file.

See https://golang.org/ref/mod#go-mod-tidy for more about 'go mod tidy'.

The detail about how go mod tidy handles ignore should be available here, not behind the link.

mem added a commit to mem/go that referenced this issue Sep 10, 2022
@mem
Expand help text for go mod tidy
c6e3c8b 
`go mod tidy` will ignore files with the build constraint `ignore`. This
is documented in https://go.dev/ref/mod#go-mod-tidy. While this URL in
mentioned in the existing help text, the fact about the special handling
of the `ignore` tag is significant enough to be mentioned explicitly in
the help text. From the existing link it's not inmediately obvious that
this special behavior exists.

Take most of the relevant text from the online description and add it to
the help text of `go mod tidy`.

Fixes: golang#54993
Signed-off-by: Marcelo E. Magallon <marcelo.magallon@gmail.com>
@mem mem linked a pull request Sep 10, 2022 that will close this issue
Open
@gopherbot
Copy link

Change https://go.dev/cl/430136 mentions this issue: cmd/go/internal/modcmd: expand help text for go mod tidy

@mem
Copy link
Author

mem commented Sep 10, 2022

The alternative fix is to change the help text in go help buildconstraint, which reads:

To keep a file from being considered for the build:

        //go:build ignore

(any other unsatisfied word will work as well, but "ignore" is conventional.)

because that is not true: ignore is NOT just a convention, it's handled differently by the compiler:

https://github.com/golang/go/blob/master/src/cmd/go/internal/imports/build.go#L188

If that is preferred, I would still propose that the help text for go help mod tidy should be changed to include a link to go help buildconstraint.

@mem mem mentioned this issue Sep 10, 2022
Closed
@seankhliao seankhliao changed the title cmd/go/internal/modcmd: tidy behavior regarding ignore tag is hard to find cmd/go: tidy behavior regarding ignore tag is hard to find Sep 10, 2022
@seankhliao
Copy link
Member

cc @bcmills

@toothrot toothrot added this to the Backlog milestone Sep 13, 2022
@toothrot toothrot added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Sep 13, 2022
mem added a commit to mem/go that referenced this issue Sep 24, 2022
@mem
cmd/go: expand help text for go mod tidy
206b1c4 
`go mod tidy` will ignore files with the build constraint `ignore`. This
is documented in https://go.dev/ref/mod#go-mod-tidy. While this URL in
mentioned in the existing help text, the fact about the special handling
of the `ignore` tag is significant enough to be mentioned explicitly in
the help text. From the existing link it's not inmediately obvious that
this special behavior exists.

Take most of the relevant text from the online description and add it to
the help text of `go mod tidy`.

Fixes: golang#54993
Signed-off-by: Marcelo E. Magallon <marcelo.magallon@gmail.com>
mem added a commit to mem/go that referenced this issue Oct 8, 2022
@mem
cmd/go: expand help text for go mod tidy
045729b 
`go mod tidy` will ignore files with the build constraint `ignore`. This
is documented in https://go.dev/ref/mod#go-mod-tidy. While this URL in
mentioned in the existing help text, the fact about the special handling
of the `ignore` tag is significant enough to be mentioned explicitly in
the help text. From the existing link it's not inmediately obvious that
this special behavior exists.

Take most of the relevant text from the online description and add it to
the help text of `go mod tidy`.

Fixes: golang#54993
Signed-off-by: Marcelo E. Magallon <marcelo.magallon@gmail.com>
mem added a commit to mem/go that referenced this issue Nov 25, 2022
@mem
cmd/go: expand help text for go mod tidy
dc73bc1 
`go mod tidy` will ignore files with the build constraint `ignore`. This
is documented in https://go.dev/ref/mod#go-mod-tidy. While this URL in
mentioned in the existing help text, the fact about the special handling
of the `ignore` tag is significant enough to be mentioned explicitly in
the help text. From the existing link it's not inmediately obvious that
this special behavior exists.

Take most of the relevant text from the online description and add it to
the help text of `go mod tidy`.

Fixes: golang#54993
Signed-off-by: Marcelo E. Magallon <marcelo.magallon@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation GoCommand cmd/go help wanted NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Milestone
Backlog
Development

Successfully merging a pull request may close this issue.

cmd/go/internal/modcmd: expand help text for go mod tidy mem/go
5 participants
@toothrot @mem @bcmills @gopherbot @seankhliao