spacemacs/layers/+lang/c-c++/README.org

#+TITLE: C/C++ layer

[[file:img/ccpp.jpg]]

* Table of Contents                     :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#layer][Layer]]
  - [[#default-mode-for-header-files][Default mode for header files]]
  - [[#clang-configuration][Clang Configuration]]
    - [[#clang-format][clang-format]]
    - [[#company-clang-and-flycheck][Company-clang and flycheck]]
  - [[#rtags-configuration][RTags configuration]]
  - [[#enable-google-set-c-style][Enable google-set-c-style]]
  - [[#newlines][Newlines]]
- [[#key-bindings][Key Bindings]]
  - [[#formatting-clang-format][Formatting (clang-format)]]
  - [[#rtags][RTags]]

* Description
This layer adds configuration for C/C++ language.

** Features:
- Support syntax checking via flycheck with Clang.
- Support for disassembly of code with [[https://github.com/jart/disaster][disaster]].
- Support code reformatting with [[http://clang.llvm.org/docs/ClangFormat.html][clang-format]].
- Display function or variable definition at the bottom. (when =semantic= layer
  is included)
- Display current function cursor is in at the top. See [[https://github.com/tuhdo/semantic-stickyfunc-enhance][stickyfunc-demos]] for
  demos in some programming languages. (when =semantic= layer is included)
- Support common refactoring with [[https://github.com/tuhdo/semantic-refactor][semantic-refactor]]. See [[https://github.com/tuhdo/semantic-refactor/blob/master/srefactor-demos/demos.org][srefactor-demos]] for
  demonstration of refactoring features. (when =semantic= layer is included)
- Support code navigation via cscope (when =cscope= layer is included) and gtags.
- Support auto-completion (when =auto-completion= layer is included) via
  company-clang (when =c-c++-enable-clang-support= is turned on), or
  company-ycmd (when =ycmd= layer is included).
- Support for [[https://github.com/realgud/realgud][realgud]] debugger.
- Support for [[https://github.com/Andersbakken/rtags][rtags]].

* Install
** Layer
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =c-c++= to the existing =dotspacemacs-configuration-layers= list in this
file.

*Note:* [[https://github.com/tuhdo/semantic-refactor][semantic-refactor]] is only available for Emacs 24.4+

** Default mode for header files
By default header files are opened in =c-mode=, you can open them in =c++-mode=
by setting the variable =c-c++-default-mode-for-headers= to =c++-mode=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((c-c++ :variables c-c++-default-mode-for-headers 'c++-mode)))
#+END_SRC

*Note:* To set the variable for a given project, create a directory local
variable at the root of your project. More info on directory local variables
can be found in the [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Directory-Local-Variables.html][dir-locals]].

** Clang Configuration
To enable Clang support, set the layer variable =c-c++-enable-clang-support=
to =t= in the dotfile:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((c-c++ :variables c-c++-enable-clang-support t)))
#+END_SRC

*** clang-format
[[http://clang.llvm.org/docs/ClangFormat.html][clang-format]] allows reformatting either a selected region of code
(=clang-format-region=) or a whole buffer (=clang-format-buffer=)
according to a style defined in a =.clang-format= file. This file
is either located in the same directory as the file being edited,
or any of its parent directories. If no =.clang-format= is found,
then a default style will be used.

To enable automatic buffer formatting on save, set the variable
=c-c++-enable-clang-format-on-save= to =t=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (c-c++ :variables c-c++-enable-clang-format-on-save t)))
#+END_SRC

*** Company-clang and flycheck
This layer adds some fancy improvements to =company-clang=. It includes a hook
to load a projects =.clang_complete= file, which is just a text file with one
clang flag per line, a format also used by other text editor clang plugins.

Not only does this allow proper autocomplete on projects with extra includes and
flags, but there is also support for flycheck so that it doesn’t complain about
missing header files.

** RTags configuration
To enable support for =rtags=, set the layer variable
=c-c++-enable-rtags-support= to =t= in your dotfile.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((c-c++ :variables c-c++-enable-rtags-support t)))
#+END_SRC

This will also enable =company-rtags= to be used as a backend for
auto-completion (when =auto-completion= layer is included).
To prevent this, while retaining the rest of Rtags functionality,
set the variable =c-c++-enable-rtags-support= to ='no-completion=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((c-c++ :variables c-c++-enable-rtags-support 'no-completion)))
#+END_SRC

** Enable google-set-c-style
If you have clang enabled with =clang-format= as described earlier in this page
you may not have a lot of neeed for =google-set-c-style= if you are already
using a mode based on Google mode for most of your projects.

However, if you don’t have (or want) =clang-format=, or if you have to do a lot
[[https://www.emacswiki.org/emacs/TrampMode][Tramp]] remote editing on systems that don’t have =clang-format= installed, you
may want =google-c-style= enabled and added to your common hooks.

To get =google-c-style= actually install itself into your C/C++ common hooks,
you need to have =c-c++-enable-google-style= defined to true when you load the
C-C++ lang in Spacemacs. In your =~/.spacemacs= file, a possible way that this
would look is that in your list of =dostpacemacs-configuration-layers= you have
an entry like

#+BEGIN_SRC emacs-lisp
  (c-c++ :variables
         c-c++-enable-google-style t)
#+END_SRC

Additionally, if you have =c-c++-enable-google-newline= variable set then
=`google-make-newline-indent= will be set as a =c-mode-common-hook=. You would
set that up like this:

#+BEGIN_SRC emacs-lisp
  (c-c++ :variables
         c-c++-enable-google-style t
         c-c++-enable-google-newline t)
#+END_SRC

** Newlines
You can enable the =Auto-newline= minor mode that automatically adds newlines
after certain characters by setting the =c-c++-enable-auto-newline= variable.

#+BEGIN_SRC emacs-lisp
  (c-c++ :variables
         c-c++-enable-auto-newline t)
#+END_SRC

* Key Bindings

| Key Binding | Description                                                   |
|-------------+---------------------------------------------------------------|
| ~SPC m g a~ | open matching file                                            |
|             | (e.g. switch between .cpp and .h, requires a project to work) |
| ~SPC m g A~ | open matching file in another window                          |
|             | (e.g. switch between .cpp and .h, requires a project to work) |
| ~SPC m D~   | disaster: disassemble c/c++ code                              |
| ~SPC m r~   | srefactor: refactor thing at point.                           |

*Note:* [[https://github.com/tuhdo/semantic-refactor][semantic-refactor]] is only available for Emacs 24.4+.

** Formatting (clang-format)

| Key Binding | Description                     |
|-------------+---------------------------------|
| ~SPC m = =~ | format current region or buffer |
| ~SPC m = f~ | format current function         |

** RTags

| Key Binding | Description                     |
|-------------+---------------------------------|
| ~SPC m g .~ | find symbol at point            |
| ~SPC m g ,~ | find references at point        |
| ~SPC m g ;~ | find file                       |
| ~SPC m g /~ | find all references at point    |
| ~SPC m g [~ | location stack back             |
| ~SPC m g ]~ | location stack forward          |
| ~SPC m g >~ | c++ tags find symbol            |
| ~SPC m g <~ | c++ tags find references        |
| ~SPC m g B~ | show rtags buffer               |
| ~SPC m g d~ | print dependencies              |
| ~SPC m g D~ | diagnostics                     |
| ~SPC m g e~ | reparse file                    |
| ~SPC m g E~ | preprocess file                 |
| ~SPC m g F~ | fixit                           |
| ~SPC m g G~ | guess function at point         |
| ~SPC m g h~ | print class hierarchy           |
| ~SPC m g I~ | c++ tags imenu                  |
| ~SPC m g L~ | copy and print current location |
| ~SPC m g M~ | symbol info                     |
| ~SPC m g O~ | goto offset                     |
| ~SPC m g p~ | set current project             |
| ~SPC m g R~ | rename symbol                   |
| ~SPC m g s~ | print source arguments          |
| ~SPC m g S~ | display summary                 |
| ~SPC m g T~ | taglist                         |
| ~SPC m g v~ | find virtuals at point          |
| ~SPC m g V~ | print enum value at point       |
| ~SPC m g X~ | fix fixit at point              |
| ~SPC m g Y~ | cycle overlays on screen        |