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: unclear what ImportMap in "list -json" means #42446

Open
mvdan opened this issue Nov 8, 2020 · 5 comments
Open

cmd/go: unclear what ImportMap in "list -json" means #42446

mvdan opened this issue Nov 8, 2020 · 5 comments
Labels
Documentation GoCommand cmd/go NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@mvdan
Copy link
Member

mvdan commented Nov 8, 2020

$ go version
go version devel +974def803e Tue Nov 3 04:11:02 2020 +0000 linux/amd64
$ go help list | grep ImportMap
        ImportMap    map[string]string // map from source import to ImportPath (identity entries omitted)

I've been writing Go tools and using Go modules for years, and I can't understand what this field means, or when it's used.

My initial suspicion was that it mattered for vendored dependencies, because a user reported a go list -json output containing:

	"ImportMap": {
		"golang.org/x/crypto/internal/subtle": "vendor/golang.org/x/crypto/internal/subtle"
	},

However, I just created a simple module with vendored dependencies, and go list -json -deps does not show any ImportMap. I also had a brief look at the cmd/go code, and it seems like the map can contain RawImports (no idea what those are either), or imports like runtime/cgo which appear only in generated code.

Could we clarify the docs a bit on this? I realise that the doc line should still be one line, but perhaps we can expand on its definition in the text after the type definition, just like the paragraph starting with Packages stored in vendor directories report an ImportPath....

@mvdan
Copy link
Member Author

mvdan commented Nov 8, 2020

Digging a bit further, the original change was in mid-2018 at https://go-review.googlesource.com/c/go/+/122878/, presumably to better support foo.test packages for #25949. Unfortunately, the commit message doesn't really clarify much for me.

@mvdan
Copy link
Member Author

mvdan commented Nov 8, 2020

Ah, it seems like ImportMap is used for vendored packages in the standard library, but not in the current module:

$ go list -json vendor/golang.org/x/text/secure/bidirule | grep -A3 ImportMap
	"ImportMap": {
		"golang.org/x/text/transform": "vendor/golang.org/x/text/transform",
		"golang.org/x/text/unicode/bidi": "vendor/golang.org/x/text/unicode/bidi"
	},

This seems to be what I was running into. It's still unclear to me why vendored packages only appear in ImportMap in this case, but not others.

@bcmills
Copy link
Contributor

bcmills commented Nov 9, 2020

ImportMap used to be more significant: in GOPATH mode with per-package vendor directories, it reported the mapping of import paths to vendor trees.

In module mode it is indeed less useful, because we now have only one copy of each module dependency (instead of one per vendor subtree). However, it will probably become a bit more meaningful again once we get replacements straightened out (#26904, #30831).

@bcmills bcmills added Documentation NeedsFix The path to resolution is known, but the work has not been done. labels Nov 9, 2020
@bcmills bcmills added this to the Backlog milestone Nov 9, 2020
@bcmills bcmills added the GoCommand cmd/go label Nov 9, 2020
@mvdan
Copy link
Member Author

mvdan commented Nov 9, 2020

Thanks; at least this confirms that my being confused at the docs is somewhat justified :) I'm happy to have this issue in the backlog until those two issues are fixed. Once they are, perhaps the docs can be clarified with an example or two.

@dominikh
Copy link
Member

dominikh commented Jun 3, 2021

On the topic of confusion: #46462

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation GoCommand cmd/go NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

3 participants