git clone 'git://github.com/abingham/emacs-ycmd.git'
emacs-ycmd is a client for ycmd, the code completion system. It takes care of managing a ycmd server and fetching completions from that server.
emacs-ycmd comprises a core set of functionality for communicating with ycmd as well as integration with emacs completion frameworks like company-mode and auto-complete-mode.
A lot of the concepts behind emacs-ycmd are actually concepts from ycmd itself, so if you feel lost you might read the ycmd documentation and/or the the original YouCompleteMe documentation.
First make sure that
ycmd is installed on your system. See the ycmd instructions for more details.
ycmd-mode in all supported modes, add the following to your emacs config:
(require 'ycmd) (add-hook 'after-init-hook #'global-ycmd-mode)
ycmd-mode to a specific supported mode:
(require 'ycmd) (add-hook 'c++-mode-hook 'ycmd-mode)
Use the variable
ycmd-server-command to specify how to run the server. It will typically be something like:
(set-variable 'ycmd-server-command '("python" "/path/to/ycmd/package"))
If you've got a global ycmd configuration, specify that in your
emacs configuration by setting
(set-variable 'ycmd-global-config "/path/to/global_config.py")
If you've got project-specific ycmd configurations (almost certainly
.ycm_extra_conf.py), and if you want them automatically
loaded by ycmd as needed (which you probably do), then you can
whitelist them by adding entries to
example, this will allow automatic loading of all
files anywhere under
(set-variable 'ycmd-extra-conf-whitelist '("~/my_projects/*"))
Alternatively, you can set
ycmd-extra-conf-handler to control how
ycmd.el deals with non-whitelisted extra configs. By default this is
'ask, meaning it will ask the user each time one is encountered. The
other options are
'ignore, in which case the extra config will be
'load, in which case the extra config will be loaded.
Now a ycmd server will be automatically launched whenever it's needed. Generally, this means whenever you visit a file with a supported major mode. You should not normally need to manually start or stop a ycmd server.
With a server running, you can now get completions for a point in a
ycmd-get-completions. This doesn't actually insert the
completions; it just fetches them from the server. It's not even an
interactive function, so you can't really call it while editing. If
you just want to see the possible completions at a point, you can try
ycmd-display-completions which will dump a raw completion struct
into a buffer. This is more of a debugging tool than anything.
More likely, you'll want to use a completion framework like
company-mode to manage the completions for you. Here's how to do
(require 'company-ycmd) (company-ycmd-setup)
After this you can use your standard
company-mode keybindings to do
There have been some reports that
ycmd.el doesn't work on Windows when Python's output is buffered. See, for example, issue #104. This is because we rely on the ycmd server printing out its host and port information in a timely (i.e. unbuffered) manner. We will almost certainly update the defaults for
ycmd.el to force unbuffered output.
In any event, if you are facing problems with ycmd not starting and/or hanging Emacs on Windows, try adding
-u to your
ycmd-server-command. For example:
(set-variable 'ycmd-server-command '("c:/path/to/python.exe" "-u" "c:/path/to/ycmd"))
flycheck-ycmd.el allows you to use
ycmd as a backend for
flycheck. With this enabled, whenever
ycmd parses a file the
results will be passed to
flycheck for display. This is a really
nice way to get quick feedback on problems in your code.
The simple way to enable
flycheck integration is to use
(require 'flycheck-ycmd) (flycheck-ycmd-setup)
This will make sure that
flycheck sees the parse results, and that
flycheck-ycmd backend is enabled.
If for some reason you want to do this manually, the instructions are like this:
(require 'flycheck-ycmd) ;; Make sure the flycheck cache sees the parse results (add-hook 'ycmd-file-parse-result-hook 'flycheck-ycmd--cache-parse-results) ;; Add the ycmd checker to the list of available checkers (add-to-list 'flycheck-checkers 'ycmd)
If you use
flycheck-ycmd-set or otherwise put
ycmd at the front of
flycheck-checkers, flycheck will use the ycmd checker for every
ycmd-mode. This may not be what you want. For example,
even though ycmd supports completion (and, thus, flycheck) for Python,
you may wish to use pyflakes for flychecking Python code.
To disable ycmd-based flychecking for specific modes, you can modify
flycheck-disabled-checkers list in your mode hook. For example:
(add-hook 'python-mode-hook (lambda () (add-to-list 'flycheck-disabled-checkers 'ycmd))
With this, the ycmd checker will be ignored in
flycheck-disabled-checkers is buffer-local, the ycmd-based checker
will still be available for other modes.
In some cases you may see that
flycheck interfere with one another. You can end up with strange completion artifacts in your buffers. This mostly seems to happen when you run emacs in “terminal mode”, i.e. with
The short answer for how to deal with this is:
(setq flycheck-indication-mode nil)
The slightly longer and probably better answer is:
(when (not (display-graphic-p))
(setq flycheck-indication-mode nil))
For a full explanation see the
emacs-ycmd defect related to this as well as the root
emacs-ycmd reports found errors through emacs buttons; to integrate those with
next-error prepend something like
(require 'ycmd-next-error) before require'ing ycmd (after adding the
contrib directory to your
In some common configurations
emacs-ycmd can produce lots of messages, and some people find these noisy and distracting. If you're seeing a lot of messages like
Contacting host: 127.0.0.1:NNNNN and you'd like to quiet them, set
nil. This can effect non-ycmd-related buffers, so consider using buffer-local settings if this worries you.
You might also see a flurry of messages like this:
REQUEST [error] Error (error) while connecting to http://127.0.0.1:38987/completions. REQUEST [error] Error (error) while connecting to http://127.0.0.1:38987/event_notification. [26 times]
These almost never indicate something you need to be concerned about. To quiet them, you can set
See issue #173 for the initial discussion of this topic.
emacs-ycmd comes with a number of tests that you can. This is mostly
useful for developers. They are built with
ert, so you can run them
using any technique that
ert provides. For example:
(require 'ycmd-test) (ert-run-tests-interactively "ycmd-test")