Skip to content

Commit 0b46a62

Browse files
jayconrodjayconrod
authored
docs: copy editor setup instructions from wiki to docs/editors.md (#4504)
**What type of PR is this?** > Documentation **What does this PR do? Why is it needed?** And link from README.rst. GitHub wikis seem to be downranked pretty hard by Google, so these instructions haven't been very visible. Linking from the README should help. **Which issues(s) does this PR fix?** n/a **Other notes for review** For some reason, the vim instructions were in docs/go/editors/vim.md instead of in the wiki. I've squashed them into a new section here.
1 parent dfed61b commit 0b46a62

File tree

3 files changed

+350
-72
lines changed

3 files changed

+350
-72
lines changed

‎README.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,11 @@ Go rules for Bazel_
1515
.. _Coverage: https://bazel.google.cn/docs/coverage
1616
.. _Dependencies: go/dependencies.rst
1717
.. _Deprecation schedule: https://github.com/bazelbuild/rules_go/wiki/Deprecation-schedule
18+
.. _Editor setup instructions: docs/editors.md
1819
.. _examples/basic_gazelle: examples/basic_gazelle
1920
.. _examples/hello: examples/hello
2021
.. _Gopher Slack: https://invite.slack.golangbridge.org/
21-
.. _gopls integration: https://github.com/bazelbuild/rules_go/wiki/Editor-setup
22+
.. _gopls integration: docs/editors.md
2223
.. _Overriding dependencies: go/dependencies.rst#overriding-dependencies
2324
.. _Proto rules: proto/core.rst
2425
.. _Protocol buffers: proto/core.rst
@@ -123,6 +124,7 @@ Documentation
123124
Quick links
124125
~~~~~~~~~~~
125126

127+
* `Editor setup instructions`_
126128
* `rules_go and Gazelle roadmap`_
127129
* `Deprecation schedule`_
128130
* `Using rules_go on Windows`_

‎docs/editors.md‎

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
# General setup
2+
3+
The `GOPACKAGESDRIVER` allows `gopls` and any package using `x/tools/packages` to
4+
expose package data. Configuring the rules_go's packages driver is simple.
5+
6+
## 1. `gopls`
7+
`gopls >= v0.6.10` ([released on Apr 13th 2021](https://github.com/golang/tools/releases/tag/gopls%2Fv0.6.10)) is required.
8+
9+
Install it in your path. If you have $GOBIN in your PATH, this should do the trick:
10+
```
11+
$ go install golang.org/x/tools/gopls@latest
12+
```
13+
14+
If you are using Visual Studio Code, it should have been automatically updated by now.
15+
16+
## 2. Launcher script
17+
Create a launcher script, say `tools/gopackagesdriver.sh`. If your repo is loading `rules_go` in its MODULE.bazel, give it these contents:
18+
19+
```bash
20+
#!/usr/bin/env bash
21+
exec bazel run -- @rules_go//go/tools/gopackagesdriver "${@}"
22+
```
23+
24+
If your repo is still loading `rules_go` in the WORKSPACE file:
25+
26+
```bash
27+
#!/usr/bin/env bash
28+
exec bazel run -- @io_bazel_rules_go//go/tools/gopackagesdriver "${@}"
29+
```
30+
31+
## 3. Editor Setup
32+
33+
You might want to replace `github.com/my/mypkg` with your package. When first opening
34+
a file in the workspace, give the driver some time to load.
35+
36+
### Visual Studio Code
37+
In the `.vscode/settings.json` of your workspace, you'll need to one of the two following JSON blobs, depending on if your repo is using MODULE.bazel or WORKSPACE to load rules_go (the difference is in the `go.goroot`). Also, for both of these, you'll need to edit some of the lines.
38+
39+
#### Bzlmod (MODULE.bazel file)
40+
If you're using MODULE.bazel, use a JSON blob like this, after editing the following three lines:
41+
42+
1. In `build.directoryFilters` replace `mypkg` in `bazel-mypkg` with your repo's workspace name.
43+
2. In `formatting.local` replace the import path there with the import path of your repo's code.
44+
3. In `go.goroot`, replace `mymodule` with the name of your root module.
45+
46+
**NOTE:** The example below assumes you are using Bazel v8.0.0 or greater (or have the `--incompatible_use_plus_in_repo_names` flag enabled). If you are using an earlier version of Bazel (without that flag enabled), use this value for `go.goroot` instead: `${workspaceFolder}/bazel-${workspaceFolderBasename}/external/rules_go~~go_sdk~mymodule__download_0/`.
47+
48+
```jsonc
49+
{
50+
// Settings for go/bazel are based on editor setup instructions at
51+
// https://github.com/bazelbuild/rules_go/wiki/Editor-setup#visual-studio-code
52+
"go.goroot": "${workspaceFolder}/bazel-${workspaceFolderBasename}/external/rules_go++go_sdk+mymodule__download_0/",
53+
"go.toolsEnvVars": {
54+
"GOPACKAGESDRIVER": "${workspaceFolder}/tools/gopackagesdriver.sh"
55+
},
56+
"go.enableCodeLens": {
57+
"runtest": false
58+
},
59+
"gopls": {
60+
"build.workspaceFiles": [
61+
"**/BUILD",
62+
"**/WORKSPACE",
63+
"**/*.{bzl,bazel}",
64+
],
65+
"build.directoryFilters": [
66+
"-bazel-bin",
67+
"-bazel-out",
68+
"-bazel-testlogs",
69+
"-bazel-mypkg",
70+
],
71+
"formatting.gofumpt": true,
72+
"formatting.local": "github.com/my/mypkg",
73+
"ui.completion.usePlaceholders": true,
74+
"ui.semanticTokens": true,
75+
"ui.codelenses": {
76+
"gc_details": false,
77+
"regenerate_cgo": false,
78+
"generate": false,
79+
"test": false,
80+
"tidy": false,
81+
"upgrade_dependency": false,
82+
"vendor": false
83+
},
84+
},
85+
"go.useLanguageServer": true,
86+
"go.buildOnSave": "off",
87+
"go.lintOnSave": "off",
88+
"go.vetOnSave": "off",
89+
}
90+
```
91+
92+
#### Pre-Bzlmod (WORKSPACE file)
93+
If your repo is using WORKSPACE to load `rules_go`, use a JSON blob like this, after editing the following two lines:
94+
95+
1. In `build.directoryFilters` replace `mypkg` in `bazel-mypkg` with your repo's workspace name.
96+
2. In `formatting.local` replace the import path there with the import path of your repo's code.
97+
98+
```jsonc
99+
{
100+
// Settings for go/bazel are based on editor setup instructions at
101+
// https://github.com/bazelbuild/rules_go/wiki/Editor-setup#visual-studio-code
102+
"go.goroot": "${workspaceFolder}/bazel-${workspaceFolderBasename}/external/rules_go++go_sdk+go_sdk/",
103+
"go.toolsEnvVars": {
104+
"GOPACKAGESDRIVER": "${workspaceFolder}/tools/gopackagesdriver.sh"
105+
},
106+
"go.enableCodeLens": {
107+
"runtest": false
108+
},
109+
"gopls": {
110+
"build.workspaceFiles": [
111+
"**/BUILD",
112+
"**/WORKSPACE",
113+
"**/*.{bzl,bazel}",
114+
],
115+
"build.directoryFilters": [
116+
"-bazel-bin",
117+
"-bazel-out",
118+
"-bazel-testlogs",
119+
"-bazel-mypkg",
120+
],
121+
"formatting.gofumpt": true,
122+
"formatting.local": "github.com/my/mypkg",
123+
"ui.completion.usePlaceholders": true,
124+
"ui.semanticTokens": true,
125+
"ui.codelenses": {
126+
"gc_details": false,
127+
"regenerate_cgo": false,
128+
"generate": false,
129+
"test": false,
130+
"tidy": false,
131+
"upgrade_dependency": false,
132+
"vendor": false
133+
},
134+
},
135+
"go.useLanguageServer": true,
136+
"go.buildOnSave": "off",
137+
"go.lintOnSave": "off",
138+
"go.vetOnSave": "off",
139+
}
140+
```
141+
142+
### Neovim
143+
144+
```lua
145+
nvim_lsp.gopls.setup {
146+
on_attach = on_attach,
147+
settings = {
148+
gopls = {
149+
workspaceFiles = {
150+
"**/BUILD",
151+
"**/WORKSPACE",
152+
"**/*.{bzl,bazel}",
153+
},
154+
env = {
155+
GOPACKAGESDRIVER = './tools/gopackagesdriver.sh'
156+
},
157+
directoryFilters = {
158+
"-bazel-bin",
159+
"-bazel-out",
160+
"-bazel-testlogs",
161+
"-bazel-mypkg",
162+
},
163+
...
164+
},
165+
},
166+
}
167+
```
168+
169+
### Vim
170+
171+
1. Install [vim-go](https://github.com/fatih/vim-go), a Vim plugin for Go
172+
development with support for `gopls`.
173+
174+
2. Follow the instructions from [Editor
175+
setup](https://github.com/bazelbuild/rules_go/wiki/Editor-setup#3-editor-setup)
176+
for installing `gopls` and adding a launcher script.
177+
* Note that `gopls` should already be installed as part of installing `vim-go`.
178+
179+
3. Add the following to your `.vimrc`:
180+
181+
```vim
182+
function! MaybeSetGoPackagesDriver()
183+
" Start at the current directory and see if there's a WORKSPACE file in the
184+
" current directory or any parent. If we find one, check if there's a
185+
" gopackagesdriver.sh in a tools/ directory, and point our
186+
" GOPACKAGESDRIVER env var at it.
187+
let l:dir = getcwd()
188+
while l:dir != "/"
189+
if filereadable(simplify(join([l:dir, 'WORKSPACE'], '/')))
190+
let l:maybe_driver_path = simplify(join([l:dir, 'tools/gopackagesdriver.sh'], '/'))
191+
if filereadable(l:maybe_driver_path)
192+
let $GOPACKAGESDRIVER = l:maybe_driver_path
193+
break
194+
end
195+
end
196+
let l:dir = fnamemodify(l:dir, ':h')
197+
endwhile
198+
endfunction
199+
200+
call MaybeSetGoPackagesDriver()
201+
202+
" See https://github.com/golang/tools/blob/master/gopls/doc/settings.md
203+
let g:go_gopls_settings = {
204+
\ 'build.workspaceFiles': [
205+
\ '**/BUILD',
206+
\ '**/WORKSPACE',
207+
\ '**/*.{bzl,bazel}',
208+
\ ],
209+
\ 'build.directoryFilters': [
210+
\ '-bazel-bin',
211+
\ '-bazel-out',
212+
\ '-bazel-testlogs',
213+
\ '-bazel-mypkg',
214+
\ ],
215+
\ 'ui.completion.usePlaceholders': v:true,
216+
\ 'ui.semanticTokens': v:true,
217+
\ 'ui.codelenses': {
218+
\ 'gc_details': v:false,
219+
\ 'regenerate_cgo': v:false,
220+
\ 'generate': v:false,
221+
\ 'test': v:false,
222+
\ 'tidy': v:false,
223+
\ 'upgrade_dependency': v:false,
224+
\ 'vendor': v:false,
225+
\ },
226+
\ }
227+
```
228+
229+
* You'll want to replace `-bazel-mypkg` with your package.
230+
* If you've put your `gopackagesdriver.sh` script somewhere other than
231+
`tools/gopackagesdriver.sh`, you'll need to update
232+
`MaybeSetGoPackagesDriver` accordingly.
233+
234+
### Sublime Text
235+
Here is a sample `.sublime-project`:
236+
```json
237+
{
238+
"folders": [
239+
{
240+
"path": ".",
241+
"folder_exclude_patterns": ["bazel-*"]
242+
}
243+
],
244+
"settings": {
245+
"lsp_format_on_save": true,
246+
"LSP": {
247+
"gopls": {
248+
"enabled": true,
249+
"command": ["~/go/bin/gopls"],
250+
"selector": "source.go",
251+
"settings": {
252+
"gopls.workspaceFiles": [
253+
"**/BUILD",
254+
"**/WORKSPACE",
255+
"**/*.{bzl,bazel}",
256+
],
257+
"gopls.directoryFilters": [
258+
"-bazel-bin",
259+
"-bazel-out",
260+
"-bazel-testlogs",
261+
"-bazel-mypkg",
262+
],
263+
"gopls.allowImplicitNetworkAccess": false,
264+
"gopls.usePlaceholders": true,
265+
"gopls.gofumpt": true,
266+
"gopls.local": "github.com/my/mypkg",
267+
"gopls.semanticTokens": true,
268+
"gopls.codelenses": {
269+
"gc_details": false,
270+
"regenerate_cgo": false,
271+
"generate": false,
272+
"test": false,
273+
"tidy": false,
274+
"upgrade_dependency": false,
275+
"vendor": false
276+
}
277+
},
278+
"env": {
279+
"GOPACKAGESDRIVER": "./tools/gopackagesdriver.sh"
280+
}
281+
}
282+
}
283+
}
284+
}
285+
```
286+
287+
### Helix Editor
288+
Here is a sample `.helix/languages.toml`:
289+
```toml
290+
[language-server.gopls.config]
291+
"build.workspaceFiles" = ["**/BUILD", "**/WORKSPACE", "**/*.{bzl,bazel}"]
292+
"build.directoryFilters" = [
293+
"-bazel-bin",
294+
"-bazel-out",
295+
"-bazel-testlogs",
296+
"-bazel-mypkg",
297+
]
298+
"formatting.gofumpt" = true
299+
"formatting.local" = "github.com/my/mypkg"
300+
"ui.completion.usePlaceholders" = true
301+
"ui.semanticTokens" = true
302+
"ui.codelenses" = { gc_details = false, generate = false, regenerate_cgo = false, test = false, tidy = false, upgrade_dependency = false, vendor = false }
303+
```
304+
305+
### Zed
306+
307+
In `.zed/settings.json` (top right-hand hamburger menu -> "Open Project Settings")
308+
309+
```jsonc
310+
{
311+
"lsp": {
312+
"gopls": {
313+
"binary": {
314+
"env": {
315+
// See https://github.com/bazel-contrib/rules_go/wiki/Editor-setup
316+
"GOPACKAGESDRIVER": "./tools/gopackagesdriver.sh"
317+
}
318+
}
319+
}
320+
}
321+
}
322+
```
323+
324+
Other Go-related settings at https://zed.dev/docs/languages/go
325+
326+
## Environment variables
327+
The package driver has a few environment configuration variables, although most won't
328+
need to configure them:
329+
- `GOPACKAGESDRIVER_BAZEL`: bazel binary, defaults to `bazel`
330+
- `BUILD_WORKSPACE_DIRECTORY`: directory of the bazel workspace (auto detected when using a launcher script because it invokes `bazel run`)
331+
- `GOPACKAGESDRIVER_BAZEL_FLAGS` which will be passed to `bazel` invocations
332+
- `GOPACKAGESDRIVER_BAZEL_QUERY_FLAGS` which will be passed to `bazel query`
333+
invocations
334+
- `GOPACKAGESDRIVER_BAZEL_QUERY_SCOPE` which specifies the scope for `importpath` queries (since `gopls` only issues `file=` queries, so **use if you know what you're doing!**)
335+
- `GOPACKAGESDRIVER_BAZEL_BUILD_FLAGS` which will be passed to `bazel build`
336+
invocations
337+
338+
## Debugging
339+
It is possible to debug driver issues by calling it directly and looking at the errors
340+
in the outputs:
341+
```
342+
$ echo {} | ./tools/gopackagesdriver.sh file=relative/path.go
343+
```
344+
345+
## Limitations
346+
- CGo completion may not work, but at least it's not explicitly supported.
347+
- Errors are not handled

0 commit comments

Comments
 (0)