README.md
1## An autocompletion daemon for the Go programming language
2
3Now support Go1.11 Go modules.
4
5Gocode is a helper tool which is intended to be integrated with your source code editor, like vim, neovim and emacs. It provides several advanced capabilities, which currently includes:
6
7 - Context-sensitive autocompletion
8
9It is called *daemon*, because it uses client/server architecture for caching purposes. In particular, it makes autocompletions very fast. Typical autocompletion time with warm cache is 30ms, which is barely noticeable.
10
11Also watch the [demo screencast](http://nosmileface.ru/images/gocode-demo.swf).
12
13
14
15
16
17### Setup
18
19 1. You should have a correctly installed Go compiler environment and your personal workspace ($GOPATH). If you have no idea what **$GOPATH** is, take a look [here](http://golang.org/doc/code.html). Please make sure that your **$GOPATH/bin** is available in your **$PATH**. This is important, because most editors assume that **gocode** binary is available in one of the directories, specified by your **$PATH** environment variable. Otherwise manually copy the **gocode** binary from **$GOPATH/bin** to a location which is part of your **$PATH** after getting it in step 2.
20
21 Do these steps only if you understand why you need to do them:
22
23 `export GOPATH=$HOME/goprojects`
24
25 `export PATH=$PATH:$GOPATH/bin`
26
27 2. Then you need to get the appropriate version of the gocode, for 6g/8g/5g compiler you can do this:
28
29 `go get -u github.com/nsf/gocode` (-u flag for "update")
30
31 Windows users should consider doing this instead:
32
33 `go get -u -ldflags -H=windowsgui github.com/nsf/gocode`
34
35 That way on the Windows OS gocode will be built as a GUI application and doing so solves hanging window issues with some of the editors.
36
37 3. Next steps are editor specific. See below.
38
39### Vim setup
40
41#### Vim manual installation
42
43Note: As of go 1.5 there is no $GOROOT/misc/vim script. Suggested installation is via [vim-go plugin](https://github.com/fatih/vim-go).
44
45In order to install vim scripts, you need to fulfill the following steps:
46
47 1. Install official Go vim scripts from **$GOROOT/misc/vim**. If you did that already, proceed to the step 2.
48
49 2. Install gocode vim scripts. Usually it's enough to do the following:
50
51 2.1. `vim/update.sh`
52
53 **update.sh** script does the following:
54
55 #!/bin/sh
56 mkdir -p "$HOME/.vim/autoload"
57 mkdir -p "$HOME/.vim/ftplugin/go"
58 cp "${0%/*}/autoload/gocomplete.vim" "$HOME/.vim/autoload"
59 cp "${0%/*}/ftplugin/go/gocomplete.vim" "$HOME/.vim/ftplugin/go"
60
61 2.2. Alternatively, you can create symlinks using symlink.sh script in order to avoid running update.sh after every gocode update.
62
63 **symlink.sh** script does the following:
64
65 #!/bin/sh
66 cd "${0%/*}"
67 ROOTDIR=`pwd`
68 mkdir -p "$HOME/.vim/autoload"
69 mkdir -p "$HOME/.vim/ftplugin/go"
70 ln -s "$ROOTDIR/autoload/gocomplete.vim" "$HOME/.vim/autoload/"
71 ln -s "$ROOTDIR/ftplugin/go/gocomplete.vim" "$HOME/.vim/ftplugin/go/"
72
73 3. Make sure vim has filetype plugin enabled. Simply add that to your **.vimrc**:
74
75 `filetype plugin on`
76
77 4. Autocompletion should work now. Use `<C-x><C-o>` for autocompletion (omnifunc autocompletion).
78
79#### Using Vundle in Vim
80
81Add the following line to your **.vimrc**:
82
83`Plugin 'nsf/gocode', {'rtp': 'vim/'}`
84
85And then update your packages by running `:PluginInstall`.
86
87#### Using vim-plug in Vim
88
89Add the following line to your **.vimrc**:
90
91`Plug 'nsf/gocode', { 'rtp': 'vim', 'do': '~/.vim/plugged/gocode/vim/symlink.sh' }`
92
93And then update your packages by running `:PlugInstall`.
94
95#### Other
96
97Alternatively take a look at the vundle/pathogen friendly repo: https://github.com/Blackrush/vim-gocode.
98
99### Neovim setup
100#### Neovim manual installation
101
102 Neovim users should also follow `Vim manual installation`, except that you should goto `gocode/nvim` in step 2, and remember that, the Neovim configuration file is `~/.config/nvim/init.vim`.
103
104#### Using Vundle in Neovim
105
106Add the following line to your **init.vim**:
107
108`Plugin 'nsf/gocode', {'rtp': 'nvim/'}`
109
110And then update your packages by running `:PluginInstall`.
111
112#### Using vim-plug in Neovim
113
114Add the following line to your **init.vim**:
115
116`Plug 'nsf/gocode', { 'rtp': 'nvim', 'do': '~/.config/nvim/plugged/gocode/nvim/symlink.sh' }`
117
118And then update your packages by running `:PlugInstall`.
119
120### Emacs setup
121
122In order to install emacs script, you need to fulfill the following steps:
123
124 1. Install [auto-complete-mode](http://www.emacswiki.org/emacs/AutoComplete)
125
126 2. Copy **emacs/go-autocomplete.el** file from the gocode source distribution to a directory which is in your 'load-path' in emacs.
127
128 3. Add these lines to your **.emacs**:
129
130 (require 'go-autocomplete)
131 (require 'auto-complete-config)
132 (ac-config-default)
133
134Also, there is an alternative plugin for emacs using company-mode. See `emacs-company/README` for installation instructions.
135
136If you're a MacOSX user, you may find that script useful: https://github.com/purcell/exec-path-from-shell. It helps you with setting up the right environment variables as Go and gocode require it. By default it pulls the PATH, but don't forget to add the GOPATH as well, e.g.:
137
138```
139(when (memq window-system '(mac ns))
140 (exec-path-from-shell-initialize)
141 (exec-path-from-shell-copy-env "GOPATH"))
142```
143
144### Options
145
146You can change all available options using `gocode set` command. The config file uses json format and is usually stored somewhere in **~/.config/gocode** directory. On windows it's stored in the appropriate AppData folder. It's suggested to avoid modifying config file manually, do that using the `gocode set` command.
147
148`gocode set` lists all options and their values.
149
150`gocode set <option>` shows the value of that *option*.
151
152`gocode set <option> <value>` sets the new *value* for that *option*.
153
154 - *propose-builtins*
155
156 A boolean option. If **true**, gocode will add built-in types, functions and constants to autocompletion proposals. Default: **false**.
157
158 - *lib-path*
159
160 A string option. Allows you to add search paths for packages. By default, gocode only searches **$GOPATH/pkg/$GOOS_$GOARCH** and **$GOROOT/pkg/$GOOS_$GOARCH** in terms of previously existed environment variables. Also you can specify multiple paths using ':' (colon) as a separator (on Windows use semicolon ';'). The paths specified by *lib-path* are prepended to the default ones.
161
162 - *autobuild*
163
164 A boolean option. If **true**, gocode will try to automatically build out-of-date packages when their source files are modified, in order to obtain the freshest autocomplete results for them. This feature is experimental. Default: **false**.
165
166 - *force-debug-output*
167
168 A string option. If is not empty, gocode will forcefully redirect the logging into that file. Also forces enabling of the debug mode on the server side. Default: "" (empty).
169
170 - *package-lookup-mode*
171
172 A string option. If **go**, use standard Go package lookup rules. If **gb**, use gb-specific lookup rules. See https://github.com/constabulary/gb for details. Default: **go**.
173
174 - *close-timeout*
175
176 An integer option. If there have been no completion requests after this number of seconds, the gocode process will terminate. Defaults to 1800 (30 minutes).
177
178 - *unimported-packages*
179
180 A boolean option. If set to true, gocode will try to import certain known packages automatically for identifiers which cannot be resolved otherwise. Currently only a limited set of standard library packages are supported. Default: **false**.
181
182 - *partials*
183
184 A boolean option. If set to false, gocode will not filter autocompletion results based on entered prefix before the cursor. Instead it will return all available autocompletion results viable for a given context. Whether this option is set to true or false, gocode will return a valid prefix length for output formats which support it. Setting this option to a non-default value may result in editor misbehaviour. Default: **true**.
185
186 - *ignore-case*
187
188 A boolean option. If set to true, gocode will perform case-insensitive matching when doing prefix-based filtering. Default: **false**.
189
190 - *class-filtering*
191
192 A boolean option. Enables or disables gocode's feature where it performs class-based filtering if partial input matches corresponding class keyword: const, var, type, func, package. Default: **true**.
193
194### Debugging
195
196If something went wrong, the first thing you may want to do is manually start the gocode daemon with a debug mode enabled and in a separate terminal window. It will show you all the stack traces, panics if any and additional info about autocompletion requests. Shutdown the daemon if it was already started and run a new one explicitly with a debug mode enabled:
197
198`gocode close`
199
200`gocode -s -debug`
201
202Please, report bugs, feature suggestions and other rants to the [github issue tracker](http://github.com/nsf/gocode/issues) of this project.
203
204### Developing
205
206There is [Guide for IDE/editor plugin developers](docs/IDE_integration.md).
207
208If you have troubles, please, contact me and I will try to do my best answering your questions. You can contact me via <a href="mailto:no.smile.face@gmail.com">email</a>. Or for short question find me on IRC: #go-nuts @ freenode.
209
210### Misc
211
212 - It's a good idea to use the latest git version always. I'm trying to keep it in a working state.
213 - Use `go install` (not `go build`) for building a local source tree. The objects in `pkg/` are needed for Gocode to work.
214
){kind=link}
){kind=link}