Document and maintain standard library development setup

[FiloSottile]

vscode-go and gopls mostly work on the standard library, which is awesome, but it takes some setup and it broke a few times recently. It would be great to document a supported setup, and maintain it such that it doesn't break over time.

Here's what I have so far in ~/go/src/.vscode/settings.json.

{
    "go.alternateTools": {
        "go": "~/go/bin/go"
    },
    // Workaround https://github.com/microsoft/vscode-go/issues/3163
    "gopls": {
        "env": {
            "PATH": "$HOME/go/bin/go:$PATH",
        },
    },
    // Keep tools built for this Go tree separate.
    "go.toolsGopath": "~/.vscode/godev",
    // Respect existing style in the standard library.
    "html.format.enable": false,
    "editor.codeActionsOnSave": {
        "source.organizeImports": false
    },
}

The following issues affect standard library development, and should be mentioned in the docs.

• 3163: gopls.env.PATH needs to be set as well as go.alternateTools.go

• golang/go#32394: you must open GOROOT/src as the workspace root
• ~#3105: saving files in certain packages, like crypto/x509, can take tens of seconds~ (this might be an issue with a different extension)

[stamblerre]

Definitely agree that we need to add documentation for this use case. I have a few more questions inline.

vscode-go and gopls mostly work on the standard library

When you say "mostly" - are there features that don't work? If so, it would be good to know about so we can address the issues.

but it takes some setup and it broke a few times recently

What breakages are you referring to specifically? AFAIK, we've never respected the "go.alternateTools" setting, and we've always required users to open directories within a module. Are there others that I'm missing?

"editor.codeActionsOnSave": {
    "source.organizeImports": false
}

Out of curiosity, why do you disable import organization?

[FiloSottile]

vscode-go and gopls mostly work on the standard library

When you say "mostly" - are there features that don't work? If so, it would be good to know about so we can address the issues.

I've noticed the occasional minor issue, but sometimes it's hard to tell if the tree is in a bad state, or if it's something gopls can fix. I'll pay more attention and open issues referencing this one when I do in the future.

I also do some development on the dev.boringcrypto branch, which I totally don't expect you to support, so I wonder how much breakage I was seeing because of that. I now have a separate worktree for that.

but it takes some setup and it broke a few times recently

What breakages are you referring to specifically? AFAIK, we've never respected the "go.alternateTools" setting, and we've always required users to open directories within a module. Are there others that I'm missing?

Not sure how, but it somewhat worked for me until recently even if I always opened GOROOT and did not set gopls.env. I think I went from go.goroot to go.alternateTools at some point and some things resumed working (although now I know it was still misconfigured). Before gopls and in the transition to gopls vscode-go also broke a couple times on the stdlib.

"editor.codeActionsOnSave": {
    "source.organizeImports": false
}

Out of curiosity, why do you disable import organization?

Imports in the standard library are not grouped (that is, golang.org/x imports are sorted with the rest), and I could not find a setting to get that behavior. It's niche, so I didn't bother opening a feature request. Maybe we should fix it in the standard library by doing a giant CL grouping them.

Relatedly, sometimes (maybe when the packages are new?) new imports get added with the std/ prefix. I could not figure out exactly when that happens.

[stamblerre]

Thanks for the clarifications! Please file issues when you see something that's not working, since we want to make sure that gopls supports as many use cases as we can.

And, yeah I don't think goimports supports one block of imports. If you find a repro for the std/ case, please file an issue.

[stamblerre]

@katiehockman filed a similar issue in the upstream repository, so I'm going to close this issue in favor of that one: https://github.com/golang/go/issues/38603.

[FiloSottile]

FWIW, I think the docs should be about how to make the whole vscode-go work for standard library development, not just gopls.

[heschi]

Happened to skim this bug. std/ prefixes would most likely be a consequence of adding a new package, or maybe just a new symbol to a package, while being in the wrong GOROOT.