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

#+TITLE: YCMD layer

* Table of Contents                                         :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#layer][Layer]]
  - [[#ycmd][YCMD]]
  - [[#other-requirements][Other Requirements]]
- [[#configuration][Configuration]]
  - [[#activating-ycmd-in-a-major-mode][Activating ycmd in a major mode]]
  - [[#getting-the-compilation-flags][Getting the compilation flags]]
- [[#functions][Functions]]
- [[#key-bindings][Key Bindings]]

* Description
This layer adds [[https://github.com/abingham/emacs-ycmd][emacs-ycmd]] support.

** Features:
- [[https://github.com/Valloric/YouCompleteMe][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 [[https://github.com/Valloric/ycmd#user-content-building][here]].
2) Set the =ycmd-server-command= variable to reflect the path to the installation:
  #+BEGIN_SRC emacs-lisp
  (setq ycmd-server-command '("python" "/path/to/YouCompleteMe/third_party/ycmd/ycmd"))
  #+END_SRC
  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:
  #+BEGIN_SRC emacs-lisp
  (setq ycmd-server-command (list "python" (file-truename "~/some/path")))
  #+END_SRC
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
   [[https://github.com/Valloric/YouCompleteMe/blob/master/README.md#c-family-semantic-completion][.ycm_extra_conf.py file]]. See [[#configuration][Configuration]] for more details.
4) Whitelist the file by adding the following to =.spacemacs=:
  #+BEGIN_SRC emacs-lisp
  ;; In this example we whitelist everything in the Develop folder
  (setq ycmd-extra-conf-whitelist '("~/Develop/*"))
  #+END_SRC
5) The completion is not going to work automatically until we actually force it:
  #+BEGIN_SRC emacs-lisp
  (setq ycmd-force-semantic-completion t)
  #+END_SRC

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

#+BEGIN_SRC emacs-lisp
(add-hook 'c++-mode-hook 'ycmd-mode)
#+END_SRC

** Getting the compilation flags
Spacemacs uses its own ycmd global configuration file. If you prefer, you can
write your own [[https://github.com/Valloric/YouCompleteMe/blob/master/README.md#user-content-c-family-semantic-completion][.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:

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

If your build system doesn't handle the creation of a compile_commands.json,
you can use tools such as [[https://github.com/rizsotto/Bear][Bear]] or [[https://pypi.python.org/pypi/scan-build][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:

#+BEGIN_SRC emacs-lisp
(global-set-key (kbd "<C-tab>") 'ycmd/manual-semantic-company-completer)
#+END_SRC

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