x/tools/gopls: defining the workspace root

[stamblerre]

gopls supports both module and GOPATH modes. However, we need to define a scope in which language features like references, rename, and implementation should operate. The following is subject to, and will likely, change.

For now, we have the following cases:

Module mode

Supported

• Open workspace at the module root (directory containing the go.mod file). The scope is the entire module.
• Open a subdirectory of a module. The scope is the subdirectory that has been opened.

Unsupported

• Open a directory that contains a module in a subdirectory. gopls will not work in this case.

GOPATH mode

Supported

• Open a directory inside of your GOPATH. The scope is the open directory.

At your own risk

• Open your entire GOPATH. The workspace scope will be your entire GOPATH. Note that this will cause gopls to load your entire GOPATH. If your GOPATH is large, this will take a long time and cause gopls to be very slow.

To work around this case, you can create a new GOPATH that contains only the packages you want to work on.

Unsupported

• Open a directory containing your GOPATH. Similar to the case above, this will cause gopls to treat your entire GOPATH as the workspace scope. It will be very slow to start because it will try to find all of the Go files in the directory you have opened. It will then load all of the files it has found.

---

We are working on addressing all of these cases and improving the behavior of gopls in the unsupported cases. All of these cases will be supported once gopls reaches v1.0.0.

We understand it may be inconvenient to change your typical workflow to accommodate frequent changes in gopls. In this case, it may be easier to stick with a version of gopls that works for you (gopls/v0.2.2, for instance), or if you are using GOPATH, gopls may not be the best tool to use until it reaches v1.0.0.

If you have additional use cases that are not mentioned above, please comment below.

[myitcv]

Thanks for documenting this @stamblerre.

In module mode, specifically:

Open a subdirectory of a module

Can you expand on the motivation behind limiting the scope to the subdirectory tree?

My intuition was that the scope would have been the entire module, just as running cmd/go in a sub directory still has a module context of the main module itself. Reason being: we're talking in terms of modules here (given we're in module mode) and not packages.

[stamblerre]

@myitcv: We are still considering the path forward here. For now, this is the current state, but it's possible that we may change it to be module-scoped in the future.

[joeblubaugh]

Would you consider an implementation in $GOPATH mode that allows one to set the scope when opening gopls - perhaps as a configuration or startup flag option? I frequently jump to a given code location before opening my editor; it's inconvenient to need to open my $GOPATH root (or a sufficiently "high" parent directory) in order to find all the references.

For example, I have a $GOPATH of ~/go and frequently work in ~/go/src/github.com/mybigrepo

Any time I'm within mybigrepo I'd like to set the gopls scope to mybigrepo so I can find implementations, etc in that whole scope.

[stamblerre]

@joeblubaugh: Yes, that is our eventual goal for GOPATH mode - I think a scope configuration is probably what we'll go with. I'll post more information here once we have more details planned out.

[TBBle]

I'm sorry, it's not totally clear from the write-up.

Module mode

...

Unsupported

• Open a directory that contains a module in a subdirectory. gopls will not work in this case.

Is this a design limitation, or just not currently implemented? Using VS Code (and having spent an afternoon suffering from golang/vscode-go#250 (comment)) it'd be good to understand if this is a temporary limitation, or if I will need to permanently change workflows. golang/vscode-go#226 (comment) is what brought me here.

Or perhaps I'm misunderstanding, or this is really a feature vscode-go should implement, not gopls. Perhaps vscode-go it should be starting gopls in the correct directory for my currently-open file/package, so gopls sees the supported case of "go.mod in CWD"

[stamblerre]

This is something we are working on improving for future versions of gopls. The idea will be that we infer the workspace root based on the modules under the top-level directory. This design doc explains our plans: https://github.com/golang/proposal/blob/master/design/37720-gopls-workspaces.md.

[stamblerre]

One use case we haven't considered yet is directories that contain multiple Go files, each for a different command. Right now, gopls will report errors for duplicate main functions. We need a general solution for this, so that users can open such directories/files without unnecessary errors.