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.

[stamblerre]

Keeping this issue open to ensure that its content eventually gets converted to documentation.

[D4v1dW3bb]

Unsupported

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

For vscode I have a workaround, do not know if this work for other editors.

My directory structure is:

Projects
  Someproject1
    microservice1
      go.mod
      go.sum
      main.go
    microservice2
      go.mod
      go.sum
      main.go
  Someproject2
  ...

opening "Somepoject1" in vscode causes a problem.
To solve this I have made a second directory structure:

Workspaces
  Someproject1
  Someproject2

If i start working on a project I open the respective directory in "Workspace"s in vscode. There I add al the microservice directories from the corresponding project directory in "Projects" to the workspace.

it's a little bit of work to setup but it works.

no errors any more

[gatspy]

goland support this feature. vscode how config?

@stamblerre , work fine. thanks!

{
  "gopls": {
    "buildFlags": ["-tags=wireinject"],
    "experimentalWorkspaceModule": true
  },
}

[stamblerre]

You can use VS Code's File -> Add Folder to Workspace to add multiple modules to your project.

[chinglinwen]

I use vscode remote ssh

remote workspace path: /home/wenzhenglin/gocode/src/example.com.com/naas

go.mod:
module example.com.com/naas

This issue if it's relate, that makes vscode almost non-functional, only to disable the format, almlost every time I save a file (it just waiting long time and still fail to format, a few time works though)

https://mclo.gs/oB77yJW

I'm using Kubernetes's apiserver-builder-alpha to generate codes, it forced to create project under GOPATH. that's bad, I can't easily to change the project path to outside GOPATH.

// updated
I upgrade to 0.6.2
with newest log: https://mclo.gs/HZjp6x1

my test case
insert backslash before a import, then delete it, delete that line'ss left most empty space, press ctrl+s to save file, still cause some wait time, about 3 to 5 seconds though, expect, under 1 second at least I think.

// updated link
https://github.com/kubernetes-sigs/apiserver-builder-alpha/blob/master/cmd/apiserver-boot/boot/util/repo.go#L29

[stamblerre]

@chinglinwen: It's fine to keep your project in your $GOPATH, you just shouldn't open your entire $GOPATH/src folder. Also, it looks like you're using modules anyway, so it's not an issue. It sounds like you might be running into golang/vscode-go#236, so please take a look at the advice in that issue and file a new issue if you still need help investigating.

[chinglinwen]

@stamblerre yep, issue #236 is more alike for my case. Sorry that vscode just confused me, and I don't know what's the real problem.

shouldn't open your entire $GOPATH/src

I don't open src folder, but open src/example.com/naas, the folder under it, so I don't know why you think so.

One of problem is that it sometimes works and sometimes not, I don't have correct clue what's causing the problem. ( the log doesn't say much for me to get the clue ) .

[stamblerre]

Did any of the suggestions on golang/vscode-go#236 help with the problem?

[gopherbot]

Change https://golang.org/cl/283513 mentions this issue: gopls/doc: move contents of golang/go#36899 to documentation

[chinglinwen]

Did any of the suggestions on golang/vscode-go#236 help with the problem?

@stamblerre The problem is I can't easy re-produce and verify, so it sometimes works okay, sometimes not.

• at current frequencies of saving problem, it seems I can manual handle it(manual add import, or try fix the issue then do the save)

However I try with extreme case that full of undefined names ( and no such import etc), in that way, it will show the saving box ( about 10 seconds I guess ), and got three times vscode disconnect(auto reconnect though).

case:

• create a directory named afinalizer
• with this content: https://mclo.gs/quI970t
• under $GOPATH/src/example.com/pkg/afinalizer ( if it relate)

try save and close etc

https://mclo.gs/QM2qthv

version

$ gopls version
golang.org/x/tools/gopls master
    golang.org/x/tools/gopls@v0.6.2 h1:c3zVKbg4zEOayCwgV/RCA3ucNriOyzfTv22fBW+D1EQ=

vscode setting here if relate
https://mclo.gs/qvXjrfB

[stamblerre]

I'm seeing the following error messages in your logs:

Params: {"type":1,"message":"2021/01/14 12:41:22 warning: diagnose go.mod: err: exit status 1: stderr: go: finding module for package example.com/naas/pkg/cfg\nexample.com/naas/example/test imports\n\texample.com/naas/pkg/cfg: cannot find module providing package example.com/naas/pkg/cfg: module example.com/naas/pkg/cfg: reading https://goproxy.io/example.com/naas/pkg/cfg/@v/list: 404 Not Found\n\tserver response:\n\tnot found: go list -m -json -versions example.com/naas/pkg/cfg@latest\n\t: go list -m example.com/naas/pkg/cfg: unrecognized import path \"example.com/naas/pkg/cfg\" (parse https://example.com/naas/pkg/cfg?go-get=1: no go-import meta tags ())\n\n\tdirectory=/home/wen/gocode/src/example.com/naas\n\tsnapshot=1\n"}

This may indicate an issue. In any case, it will be easier to investigate on a dedicated issue, and it sounds like there may be some issues with VS Code here too. Do you mind filing a new issue with this information here?