286 lines
13 KiB
Org Mode
286 lines
13 KiB
Org Mode
#+TITLE: Go layer
|
|
|
|
#+TAGS: general|layer|multi-paradigm|programming
|
|
|
|
[[file:img/go.png]]
|
|
|
|
* Table of Contents :TOC_5_gh:noexport:
|
|
- [[#description][Description]]
|
|
- [[#features][Features:]]
|
|
- [[#install][Install]]
|
|
- [[#layer][Layer]]
|
|
- [[#choosing-a-backend][Choosing a backend]]
|
|
- [[#pre-requisites][Pre-requisites]]
|
|
- [[#configuration][Configuration]]
|
|
- [[#execution][Execution]]
|
|
- [[#indentation][Indentation]]
|
|
- [[#autoformat][Autoformat]]
|
|
- [[#linting][Linting]]
|
|
- [[#tests][Tests]]
|
|
- [[#coverage][Coverage]]
|
|
- [[#guru][Guru]]
|
|
- [[#auto-completion][Auto-completion]]
|
|
- [[#lsp-backend][LSP backend]]
|
|
- [[#working-with-go][Working with Go]]
|
|
- [[#go-commands-start-with-m][Go commands (start with =m=):]]
|
|
- [[#go-guru][Go Guru]]
|
|
- [[#refactoring][Refactoring]]
|
|
|
|
* Description
|
|
This layer adds extensive support for the [[https://golang.org][Go]] programming language.
|
|
|
|
** Features:
|
|
- Run [[https://golang.org/cmd/gofmt/][gofmt]] / [[https://godoc.org/golang.org/x/tools/cmd/goimports][goimports]] on file save (see [[#autoformat][Autoformat]])
|
|
- Auto-completion using [[https://github.com/nsf/gocode/tree/master/emacs][go-autocomplete.el]], via the =auto-completion= layer (see [[#auto-completion][Auto-completion]])
|
|
- Source analysis using [[https://docs.google.com/document/d/1_Y9xCEMj5S-7rv2ooHpZNH15JgRT5iM742gJkw5LtmQ][go-guru]] (see [[#guru][Guru]])
|
|
- Refactoring with [[http://gorefactor.org/][godoctor]]
|
|
- Edit struct field tags with [[https://github.com/fatih/gomodifytags][gomodifytags]]
|
|
- Linting with flycheck's built-in checkers or [[https://github.com/golangci/golangci-lint][golangci-lint]] (see [[#linting][Linting]])
|
|
- Test generation via [[https://github.com/s-kostyaev/go-gen-test][go-gen-test]] (see [[#tests][Tests]])
|
|
- Coverage profile visualization (see [[#coverage][Coverage]])
|
|
- List packages faster with [[https://github.com/haya14busa/gopkgs][gopkgs]]
|
|
- Fill a structure with default values using the [[https://github.com/davidrjenni/reftools/tree/master/cmd/fillstruct][fillstruct]]
|
|
- LSP backend (see [[#lsp-backend][LSP backend]])
|
|
- Interactive debugger using [[https://github.com/emacs-lsp/dap-mode][dap-mode]]
|
|
|
|
* Install
|
|
** Layer
|
|
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
|
|
add =go= to the existing =dotspacemacs-configuration-layers= list in this file.
|
|
|
|
** Choosing a backend
|
|
To choose a default backend set the layer variable =go-backend=:
|
|
|
|
#+BEGIN_SRC elisp
|
|
(go :variables go-backend 'go-mode)
|
|
#+END_SRC
|
|
|
|
Alternatively the =lsp= backend will be automatically chosen if the layer =lsp=
|
|
is used and you did not specify any value for =go-backend=.
|
|
|
|
Backend can be chosen on a per project basis using directory local variables
|
|
(files named =.dir-locals.el= at the root of a project), an example to use the
|
|
=lsp= backend:
|
|
|
|
#+BEGIN_SRC elisp
|
|
;;; Directory Local Variables
|
|
;;; For more information see (info "(emacs) Directory Variables")
|
|
|
|
((go-mode (go-backend . lsp)))
|
|
#+END_SRC
|
|
|
|
*Note:* you can easily add a directory local variable with ~SPC f v d~.
|
|
|
|
** Pre-requisites
|
|
You will need =gocode=, =gogetdoc=, =godef=, =godoctor= and many others
|
|
to get all the goodies of this layer:
|
|
|
|
#+BEGIN_SRC sh
|
|
GO111MODULE=on go get -v golang.org/x/tools/gopls@latest
|
|
GO111MODULE=on CGO_ENABLED=0 go get -v -trimpath -ldflags '-s -w' github.com/golangci/golangci-lint/cmd/golangci-lint
|
|
go get -u -v golang.org/x/tools/cmd/godoc
|
|
go get -u -v golang.org/x/tools/cmd/goimports
|
|
go get -u -v golang.org/x/tools/cmd/gorename
|
|
go get -u -v golang.org/x/tools/cmd/guru
|
|
go get -u -v github.com/cweill/gotests/...
|
|
go get -u -v github.com/davidrjenni/reftools/cmd/fillstruct
|
|
go get -u -v github.com/fatih/gomodifytags
|
|
go get -u -v github.com/godoctor/godoctor
|
|
go get -u -v github.com/haya14busa/gopkgs/cmd/gopkgs
|
|
go get -u -v github.com/josharian/impl
|
|
go get -u -v github.com/mdempsky/gocode
|
|
go get -u -v github.com/rogpeppe/godef
|
|
go get -u -v github.com/zmb3/gogetdoc
|
|
#+END_SRC
|
|
|
|
Make sure that the executables are in your search =$PATH=. Note that they are
|
|
installed on =$(go env GOPATH)/bin=, or =$GOBIN= if that environment variable is
|
|
defined. For information about setting up =$PATH=, check out the corresponding
|
|
section in the FAQ (~SPC h f $PATH RET~).
|
|
|
|
For best results, make sure that the =auto-completion= and =syntax-checking=
|
|
layers are enabled as well.
|
|
|
|
* Configuration
|
|
** Execution
|
|
To run the current =main= package with command line arguments, set the value of
|
|
=go-run-args= as a file local variable, e.g.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
// Local Variables:
|
|
// go-run-args: "--output run.log"
|
|
// End:
|
|
#+END_SRC
|
|
|
|
** Indentation
|
|
By default, the tab width in Go mode is 8 spaces. To use a different value, set
|
|
the layer variable =go-tab-width=, e.g.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(go :variables go-tab-width 4)
|
|
#+END_SRC
|
|
|
|
If you're using =.editorconfig= in your project, set the value to nil to avoid
|
|
conflicts, i.e.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(go :variables go-tab-width nil)
|
|
#+END_SRC
|
|
|
|
** Autoformat
|
|
To run =gofmt= before save, set the value to a non-nil, i.e.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(go :variables go-format-before-save t)
|
|
#+END_SRC
|
|
|
|
To use a different formatter, set the value of =gofmt-command=, e.g.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(go :variables gofmt-command "goimports")
|
|
#+END_SRC
|
|
|
|
** Linting
|
|
If you wish to use =golangci-lint=, set the following layer variable to non-nil:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(go :variables go-use-golangci-lint t)
|
|
#+END_SRC
|
|
|
|
Check [[https://github.com/golangci/golangci-lint][golangci-lint]] and [[https://github.com/weijiangan/flycheck-golangci-lint][flycheck-golangci-lint]] for more details.
|
|
|
|
** Tests
|
|
If you're using =gocheck= or =testify= in your project you can use the
|
|
=go-use-gocheck-for-testing= or =go-use-testify-for-testing= variable to enable
|
|
suite testing and to get single function testing to work.
|
|
|
|
Tests are run in a compilation buffer displayed in a popup window that can be
|
|
closed by pressing ~C-g~ from any other window. The variable =go-test-buffer-name=
|
|
can be customized to set the output buffer name.
|
|
|
|
To provide additional arguments to =go test=, specify =go-use-test-args=.
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(go :variables go-use-test-args "-race -timeout 10s")
|
|
#+END_SRC
|
|
|
|
** Coverage
|
|
=go-coverage-display-buffer-func= controls how =go-coverage= should display
|
|
the coverage buffer. See [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Choosing-Window.html][display-buffer]] for a list of possible functions.
|
|
The default value is =display-buffer-reuse-window=.
|
|
|
|
** Guru
|
|
If you would like to use the =Go Guru= bindings in your work, in your project you
|
|
will need to set the scope with ~SPC m f o~. The scope is a comma separated set
|
|
of packages, and Go's recursive operator is supported. In addition, you can
|
|
prefix it with =-= to exclude a package from searching.
|
|
|
|
** Auto-completion
|
|
For auto-completion there are actually two choices. First there is the classic
|
|
=gocode=. This has been around for quite a long time now, however =gocode= has many
|
|
shortcomings, like not being able to show documentation for built-in objects or
|
|
being fully dependent on installed binary files to provide its suggestions.
|
|
|
|
A more modern and complete solution is provided by =gogetdoc=, which is able to
|
|
precisely detect all documentations in your go projects independently from where
|
|
they have been added. This is also the recommended choice from =go-mode.el=.
|
|
|
|
To choose =gocode= nothing more needs to be done. To use =gogetdoc= you need to set
|
|
the layer variable:
|
|
|
|
#+BEGIN_SRC emacs-lisp
|
|
(go :variables godoc-at-point-function 'godoc-gogetdoc)
|
|
#+END_SRC
|
|
|
|
If you choose to use =gocode= there are some suggestions to improve its results.
|
|
As =gocode= uses the output from installed binary files to provide its suggestions.
|
|
You have a few options to ensure you always get up to date suggestions:
|
|
- Run =go install ./...= in your package directory when you make a file change.
|
|
- Run =gocode set autobuild true= to have gocode attempt to run =go install ./...=
|
|
for you.
|
|
- You can configure your task runner to run the =go install ./...= command on every
|
|
file change.
|
|
|
|
** LSP backend
|
|
To enable the LSP backend, ensure that the =lsp= layer is enabled, and set the
|
|
layer variable =go-backend=:
|
|
|
|
#+BEGIN_SRC elisp
|
|
(go :variables go-backend 'lsp)
|
|
#+END_SRC
|
|
|
|
You can check [[https://www.github.com/emacs-lsp/lsp-mode/][lsp-mode]] for the gory details.
|
|
|
|
The backend can be chosen on a per project basis using directory local variables
|
|
(files named =.dir-locals.el= at the root of a project), an example is to use the
|
|
=go-mode= backend:
|
|
|
|
#+BEGIN_SRC elisp
|
|
;;; Directory Local Variables
|
|
;;; For more information see (info "(emacs) Directory Variables")
|
|
|
|
((go-mode (go-backend . go-mode)))
|
|
#+END_SRC
|
|
|
|
*Note:* you can easily add a directory local variable with ~SPC f v d~.
|
|
|
|
*** Debugger
|
|
|
|
Using the =dap= layer you'll get access to all the DAP key bindings, see the complete list of key bindings on the [[https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Btools/dap#key-bindings][dap layer description]].
|
|
|
|
* Working with Go
|
|
** Go commands (start with =m=):
|
|
|
|
| Key binding | Description |
|
|
|---------------+---------------------------------------------------------------------------------------|
|
|
| ~SPC m =~ | run "go fmt" |
|
|
| ~SPC m e b~ | go-play buffer |
|
|
| ~SPC m e d~ | download go-play snippet |
|
|
| ~SPC m e r~ | go-play region |
|
|
| ~SPC m g a~ | jump to matching test file or back from test to code file |
|
|
| ~SPC m g c~ | open a clone of the current buffer with a coverage info (=go tool cover -h= for help) |
|
|
| ~SPC m g g~ | go jump to definition |
|
|
| ~SPC m h h~ | godoc at point |
|
|
| ~SPC m i a~ | add import |
|
|
| ~SPC m i g~ | goto imports |
|
|
| ~SPC m i r~ | remove unused import |
|
|
| ~SPC m r n~ | go rename |
|
|
| ~SPC m t P~ | run "go test" for the current package and all packages under it |
|
|
| ~SPC m t g f~ | generate tests for all exported functions |
|
|
| ~SPC m t g F~ | generate tests for all functions |
|
|
| ~SPC m t g g~ | DWIM generate test for the function in the active region |
|
|
| ~SPC m t p~ | run "go test" for the current package |
|
|
| ~SPC m t s~ | run "go test" for the suite you're currently in (requires gocheck) |
|
|
| ~SPC m t t~ | run "go test" for the function you're currently in (while you're in a _.test.go file) |
|
|
| ~SPC m x x~ | run "go run" for the current 'main' package |
|
|
|
|
** Go Guru
|
|
|
|
| Key binding | Description |
|
|
|-------------+------------------------------------------------------|
|
|
| ~SPC m f <~ | go-guru show possible callers |
|
|
| ~SPC m f >~ | go-guru show call targets |
|
|
| ~SPC m f c~ | go-guru show channel sends/receives |
|
|
| ~SPC m f d~ | go-guru describe symbol at point |
|
|
| ~SPC m f e~ | go-guru show possible contants/types for error value |
|
|
| ~SPC m f f~ | go-guru show free variables |
|
|
| ~SPC m f i~ | go-guru show implements relation |
|
|
| ~SPC m f j~ | go-guru jump to symbol definition |
|
|
| ~SPC m f o~ | go-guru set analysis scope |
|
|
| ~SPC m f p~ | go-guru show what the select expression points to |
|
|
| ~SPC m f r~ | go-guru show referrers |
|
|
| ~SPC m f s~ | go-guru show callstack |
|
|
|
|
** Refactoring
|
|
|
|
| Key binding | Description |
|
|
|-------------+-----------------------------------------------------------------|
|
|
| ~SPC m r d~ | Add comment stubs |
|
|
| ~SPC m r e~ | Extract code as new function |
|
|
| ~SPC m r f~ | Add field tags (with =gomodifytags=) |
|
|
| ~SPC m r F~ | Remove field tags (with =gomodifytags=) |
|
|
| ~SPC m r i~ | Generate method stubs for implementing an interface (=go-impl=) |
|
|
| ~SPC m r n~ | Rename (with =godoctor=) |
|
|
| ~SPC m r N~ | Rename (with =go-rename=) |
|
|
| ~SPC m r s~ | Fill structure with default values (with =go-fillstruct=) |
|
|
| ~SPC m r t~ | Toggle declaration and assignment |
|