spacemacs/layers/+lang/go/README.org

#+TITLE: GO layer

[[file:img/go.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#pre-requisites][Pre-requisites]]
  - [[#layer][Layer]]
- [[#configuration][Configuration]]
  - [[#indentation][Indentation]]
  - [[#tests][Tests]]
  - [[#guru][Guru]]
  - [[#autocomplete][Autocomplete]]
- [[#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 go to Spacemacs.

** Features:
- gofmt/goimports on file save
- Auto-completion using [[https://github.com/nsf/gocode/tree/master/emacs][go-autocomplete]] (with the =auto-completion= layer)
- Source analysis using [[https://docs.google.com/document/d/1_Y9xCEMj5S-7rv2ooHpZNH15JgRT5iM742gJkw5LtmQ][go-guru]]
- Refactoring with [[http://gorefactor.org/][godoctor]]
- Edit struct field tag with [[https://github.com/fatih/gomodifytags][gomodifytags]]
- Linting with flycheck's built-in checkers or flycheck-gometalinter
- Coverage profile visualization

* Install
** Pre-requisites
You will need =gocode=, =gogetdoc=, =godef= and =godoctor=:

#+BEGIN_SRC sh
  go get -u -v github.com/nsf/gocode
  go get -u -v github.com/rogpeppe/godef
  go get -u -v golang.org/x/tools/cmd/guru
  go get -u -v golang.org/x/tools/cmd/gorename
  go get -u -v golang.org/x/tools/cmd/goimports
  go get -u -v github.com/zmb3/gogetdoc
#+END_SRC

If you wish to use =gometalinter= set the value of =go-use-gometalinter= to t:

#+begin_src emacs-lisp
  (go :variables go-use-gometalinter t)
#+end_src

and install the tool:

#+BEGIN_SRC sh
  go get -u -v github.com/alecthomas/gometalinter
  gometalinter --install --update
#+END_SRC

For more information read [[https://github.com/alecthomas/gometalinter/blob/master/README.md][gometalinter README.md]]
and [[https://github.com/favadi/flycheck-gometalinter/blob/master/README.md][flycheck-gometalinter README.md]]

If you wish to use =godoctor= for refactoring, install it too:

#+BEGIN_SRC sh
  go get -u -v github.com/godoctor/godoctor
  go install github.com/godoctor/godoctor
#+END_SRC

If you want to use =gomodifytags= to edit field tags, install it too:

#+BEGIN_SRC sh
  go get -u -v github.com/fatih/gomodifytags
#+END_SRC

Make sure that the =gocode= executable is in your PATH. 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.

** 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.

* Configuration
By default, go buffers are run through =gofmt= on save. To use a different
formatter, set the value of =gofmt-command=, e.g.

#+begin_src emacs-lisp
  (setq gofmt-command "goimports")
#+end_src

or

#+begin_src emacs-lisp
  (go :variables gofmt-command "goimports")
#+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

** Tests
If you're using =gocheck= in your project you can use the
=go-use-gocheck-for-testing= variable to enable suite testing and to get single
function testing to work.

=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=.

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

** Guru
Go Oracle has been deprecated as of October 1, 2016, it's replacement is =go-guru=.

If you would like to use the =goguru= bindings in your work, you will need to
install it, and 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 with =-= to exclude a package from
searching.

In addition, =GOPATH= must be set prior to =go-guru= initialization.

** Autocomplete
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 build-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 independent on where
they have been added. This is also the choice recommended from =go-mode.el=.

To choose =gocode= nothing more needs to be done. To use =gogetdoc= you need to set

#+begin_src emacs-lisp
  (go :variables godoc-at-point-function 'godoc-gogetdoc)
#+end_src

in your =dotfile=.

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 =go install ./...= command on every
  file change.

* Working with Go
** Go commands (start with =m=):

| Key Binding | Description                                                                           |
|-------------+---------------------------------------------------------------------------------------|
| ~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 i a~ | add import                                                                            |
| ~SPC m i g~ | goto imports                                                                          |
| ~SPC m i r~ | remove unused import                                                                  |
| ~SPC m h h~ | godoc at point                                                                        |
| ~SPC m r n~ | go rename                                                                             |
| ~SPC m t p~ | run "go test" for the current package                                                 |
| ~SPC m t P~ | run "go test" for the current package and all packages under it                       |
| ~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                    |
| ~SPC m r F~ | Remove field tags                 |
| ~SPC m r n~ | Rename (with =godoctor=)          |
| ~SPC m r N~ | Rename (with =go-rename=)         |
| ~SPC m r t~ | Toggle declaration and assignment |