spacemacs/layers/+tools/ycmd/README.org

YCMD layer

• Description
  • Features:
• Install
  • Layer
  • YCMD
  • Other Requirements
• Configuration
  • Activating ycmd in a major mode
  • Getting the compilation flags
• Functions
• Key bindings

Description

This layer adds emacs-ycmd support.

Features:

• YouCompleteMe based code-completion
• Integrations with company, flycheck, and eldoc

Install

Layer

To use this configuration layer, add it to your ~/.spacemacs. You will need to add ycmd to the existing dotspacemacs-configuration-layers list in this file.

YCMD

1. Install the ycm server. Installation instructions can be found here.

2. Set the ycmd-server-command variable to reflect the path to the installation:

     (setq ycmd-server-command '("python" "/path/to/YouCompleteMe/third_party/ycmd/ycmd"))

   Note that no filename expansions are done, so ~ -paths will not work out of the box. If you need expansions, you can use Emacs’s file-truename like this:

     (setq ycmd-server-command (list "python" (file-truename "~/some/path")))

3. By default, spacemacs configures ycmd for getting the compilation flags from either a compile_commands.json or a .clang_complete file and get additionnal flags from a .ycm_extra_flags file. If you do not like this behaviour, you can write your own .ycm_extra_conf.py file. See Configuration for more details.

4. Whitelist the file by adding the following to .spacemacs:

     ;; In this example we whitelist everything in the Develop folder
     (setq ycmd-extra-conf-whitelist '("~/Develop/*"))

5. The completion is not going to work automatically until we actually force it:

     (setq ycmd-force-semantic-completion t)

Other Requirements

This package requires the auto-completion layer in order to get actual completion. The syntax-checking layer is required for flycheck support.

Configuration

Activating ycmd in a major mode

By default this layer only activates ycmd for c++-mode and c-mode.

If you want ycmd support in other modes you might just want to add it for specific languages like:

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

Getting the compilation flags

Spacemacs uses its own ycmd global configuration file. If you prefer, you can write your own .ycm_extra_conf.py.

Spacemacs will search for a compile_command.json or fall back to a .clang_complete file in all parent directories of the current translation unit. Spacemacs will try to make up for missing files in the compile_commands.json using heuristics described in global_conf.py.

The user can provide additionnal flags by writing a .ycm_extra_flags in any parent directory of the current translation unit. This is particularly useful when cross-compiling.

Example .ycm_extra_flags:

  # Additionnal flags for ycmd
  --sysroot="/path/to/your/toolchain/libc" # if you are cross-compiling

If your build system doesn’t handle the creation of a compile_commands.json, you can use tools such as Bear or scan-build to generate it, which both work with almost any build system.

Functions

If company-ycmd is used, then a function ycmd/manual-semantic-company-completer is defined. This function is useful if you want to get semantic completions only when you press a keybinding; in larger projects ycmd may not be performant for as-you-type auto-completion to work well. You can bind it like so:

  (global-set-key (kbd "<C-tab>") 'ycmd/manual-semantic-company-completer)

This function will automatically cancel out of any active completers, and offer semantic completions. It will automatically make an exception when you are completing includes; these do not count as semantic completion so the exception is necessary for the key binding to work when completing includes.

Key bindings

Adds SPC m g g go to definition binding to c++-mode as well as SPC m g G for the more imprecise but faster version.