x/tools/go/packages: document GOPACKAGESDRIVER

[jmhodges]

There is currently no documentation that shows up on godoc.org for the GOPACKAGESDRIVER environment variable. However, it's very useful for alternative build systems to provide lookups for gopls and other tools. For instance, it's mentioned in the bazel rules_go design doc for editor support.

It'd be nice for GOPACKAGESDRIVER to have publicly available documents.

[toothrot]

This sounds related to https://golang.org/cl/184943, which documents this environment variable in the code: https://github.com/golang/tools/blob/3b4f30a44f3bd52b676ee9e88db10d11971b7363/go/packages/external.go#L19-L28

/cc @matloob who may be able to explain why this is not exposed in the public documentation.

[jmhodges]

Ping!

[matloob]

We didn't document GOPACKAGESDRIVER earlier because it wasn't as stable, but I think it's reasonable to add documentation now.

[thepacketgeek]

@matloob, @jmhodges, @toothrot: I noticed gopackagesdriver is now deprecated (as of gopls 0.5.3)

Do any of you know if there is an alternate path for resolving packages (E.g. Buck) to provide gopls?

[stamblerre]

gopackagesdriver is still supported in go/packages--the reason it was disabled in gopls was because we weren't aware of any gopackagesdrivers that were actually available for use with gopls. If another gopackagesdriver becomes available, we can add back support for it in gopls, though that may be a large undertaking because we have started making assumptions in the codebase.

[thepacketgeek]

@stamblerre thank you for the clarification! We have a gopackagedriver for gopls so I'm trying to figure out a path forward. The commit above mentions gopls only supporting the go command, does go list offer something similar to gopackagedriver that gopls could use?

(as I ask this I realize that's what this very PR may be about, sorry for my confusion)

[stamblerre]

So the default gopackagesdriver is a go list driver, which is how gopls works by default. If you already have a gopackagesdriver then we'd be happy to work with you on making sure it works with gopls, because there is some logic in gopls that assumes the go list driver.

[thepacketgeek]

@stamblerre That would be incredible! What can I do to help? If I modify our gopackages driver to behave more similarly to go list, will that make integration easier?

[stamblerre]

That shouldn't be necessary--as long as it produces the correct output it should work. I would guess that we would need to revert https://golang.org/cl/268977 and then confirm whether or not gopls works. I think there will be a number of bugs and edge cases that might cause trouble, so it may take a while to fully diagnose all of the issues.

One thing that will be particularly tricky is our package metadata invalidation logic--for example, Bazel relies on BUILD files, but gopls isn't aware of those files, and so it won't invalidate package metadata when they change.