Repository files navigation

emacs-ycmd is a client forycmd,the code completion system. It takes care of managing a ycmd serverand fetching completions from that server.

emacs-ycmd comprises a core set of functionality for communicating with ycmd as well as integration with the Emacs completion frameworkcompany-mode.

A lot of the concepts behind emacs-ycmd are actually concepts fromycmd itself, so if you feel lost you might readthe ycmd documentation and/or thethe original YouCompleteMe documentation.

Important: Theycmd package itself doesn't provide a real UI for selecting and inserting completions into your files. For that you need to usecompany-ycmd or another "completion framework".

First make sure thatycmd is installed on your system. Seethe ycmd instructions for more details.

To useycmd-mode in all supported modes, add the following to your emacs config:

(require'ycmd)(add-hook'after-init-hook#'global-ycmd-mode)

Or addycmd-mode to a specific supported mode:

(require'ycmd)(add-hook'c++-mode-hook'ycmd-mode)

Use the variableycmd-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/"))

NB: We do not do filename expansion on the elements ofycmd-server-command. Asa result, paths using "~" to represent the home directory will not workproperly; you need to expand them yourself. For example:

(set-variable'ycmd-server-command `("python" ,(file-truename"~/.emacs.d/ycmd/ycmd/")))

If you've got aglobal ycmd configuration, specify that in youremacs configuration by settingycmd-global-config:

(set-variable'ycmd-global-config"/path/to/global_config.py")

Spacemacs users: Note that if you don't setycmd-global-config, spacemacswill set it for you. This is not always what you want! See the spacemacs ycmddocumentation for more info.

If you've got project-specific ycmd configurations (almost certainlycalled.ycm_extra_conf.py), and if you want them automaticallyloaded by ycmd as needed (which you probably do), then you canwhitelist them by adding entries toycmd-extra-conf-whitelist. Forexample, this will allow automatic loading of all.ycm_extra_conf.pyfiles anywhere under~/my_projects

(set-variable'ycmd-extra-conf-whitelist '("~/my_projects/*"))

Alternatively, you can setycmd-extra-conf-handler to control howycmd.el deals with non-whitelisted extra configs. By default this isset to'ask, meaning it will ask the user each time one is encountered. Theother options are'ignore, in which case the extra config will beignored, and'load, in which case the extra config will be loaded.

Now a ycmd server will be automatically launched whenever it'sneeded. Generally, this means whenever you visit a file with asupported major mode. You should not normally need to manually startor stop a ycmd server.

With a server running, you can now get completions for a point in afile usingycmd-get-completions. This doesn't actually insert thecompletions; it just fetches them from the server. It's not even aninteractive function, so you can't really call it while editing. Ifyou just want to see the possible completions at a point, you can tryycmd-display-completions which will dump a raw completion structinto a buffer. This is more of a debugging tool than anything.

It is recommended to usecompany-mode for completion, however there is basic support for Emacs' built-in completion mechanism.

(defunycmd-setup-completion-at-point-function ()"Setup`completion-at-point-functions' for`ycmd-mode'."  (add-hook'completion-at-point-functions#'ycmd-complete-at-pointnil:local))(add-hook'ycmd-mode-hook#'ycmd-setup-completion-at-point-function)

More likely, you'll want to use a completion framework likecompany-mode to manage the completions for you. Here's how to dothat:

(require'company-ycmd)(company-ycmd-setup)

After this you can use your standardcompany-mode keybindings to docompletion.

There have been some reports thatycmd.el doesn't work 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 forycmd.el to force unbuffered output.

In any event, if you are facing problems with ycmd not starting and/or hanging Emacs, try adding-u to yourycmd-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 useycmd as a backend forflycheck. With this enabled, wheneverycmd parses a file theresults will be passed toflycheck for display. This is a reallynice way to get quick feedback on problems in your code.

The simple way to enableflycheck integration is to useflycheck-ycmd-setup:

(require'flycheck-ycmd)(flycheck-ycmd-setup)

This will make sure thatflycheck sees the parse results, and thattheflycheck-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 useflycheck-ycmd-setup or otherwise putycmd at the front offlycheck-checkers, flycheck will use the ycmd checker for every buffer inycmd-mode. This may not be what you want. For example, even though ycmdsupports completion (and, thus, flycheck) for Python, you may wish to usepyflakes for flychecking Python code.

To disable ycmd-based flychecking for specific modes, you can modifytheflycheck-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 inpython-mode. Sinceflycheck-disabled-checkers is buffer-local, the ycmd-based checkerwill still be available for other modes.

In some cases you may see thatcompany andflycheck 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. withemacs -nw.

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 seetheemacs-ycmd defect related to this as well asthe rootflycheck issue.

ycmd-eldoc adds eldoc support forycmd-mode buffers.

(require'ycmd-eldoc)(add-hook'ycmd-mode-hook'ycmd-eldoc-setup)

Note: eldoc messages will only be shown for functions which are retrieved via semantic completion.

emacs-ycmd reports found errors through emacs buttons; to integrate those withnext-error prepend something like(require 'ycmd-next-error) before require'ing ycmd (after adding thecontrib directory to yourload-path).

In some common configurationsemacs-ycmd can produce lots of messages, andsome people find these noisy and distracting. If you're seeing a lot of messageslikeContacting host: 127.0.0.1:NNNNN and you'd like to quiet them, seturl-show-status tonil. This can effect non-ycmd-related buffers, soconsider 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 quietthem, you can setrequest-message-level to-1.

Seeissue #173 for theinitial discussion of this topic.

emacs-ycmd comes with a number of tests that you can run. This is mostlyuseful for developers. They are built withert, so you can run them using anytechnique thatert provides. For example:

(require'ycmd-test)(ert-run-tests-interactively"ycmd-test")

It is also possible to run the tests on the command-line with the Makefileprovided in this repository. Before running test, you need to install theCask in order to be able to install the packagedependencies.

You can do this by running

make deps

The other thing that is required is to have theycmd folder right next toemacs-ycmd (../ycmd).

To run the tests:

maketest

It is also possible to have theycmd server at a different location. In thatcase the path needs to be passed to themake command explicitly:

make YCMDPATH='/path/to/ycmd/ycmd'test

Make sure that you provide the path to the ycmd module and not the ycmd rootdirectory.