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

#+TITLE: C/C++ layer

[[file:img/ccpp.jpg]]
[[file:img/cmake.png]]

* 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]]
  - [[#cmake-configuration][CMake configuration]]
  - [[#rtags-configuration][RTags configuration]]
  - [[#enable-google-set-c-style][Enable google-set-c-style]]
- [[#key-bindings][Key Bindings]]
  - [[#debugging-realgud][Debugging (realgud)]]
  - [[#formatting-clang-format][Formatting (clang-format)]]
  - [[#rtags][RTags]]

* Description
This layer adds configuration for C/C++ language as well support for [[https://cmake.org/][CMake]]
scripts.

** 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]]
- Support for CMake configure/build (with limited support for other build systems),
  automatic generation of =compile_commands.json= (compile flags), on-the-fly configuration
  of flycheck, company-clang and RTags (if installed) with [[https://github.com/atilaneves/cmake-ide][cmake-ide]] .

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

** CMake configuration
To enable CMake projects support set the layer variable =c-c++-enable-cmake-ide-support=
to =t= in the dotfile:

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

=cmake-ide= plugin has several useful configuration options.

To configure project you need to create =.dir-locals.el= file. In case of using
make as CMake backend you can use =helm-make= to select required build target.

Here is a sample configuration. This configuration forces =cmake-ide= to use the
local directory and pass that directory to =helm-make=. Such config allows to
build your project with ~SPC c c~ key binding.

#+BEGIN_SRC emacs-lisp
((nil .
      ((cmake-ide-project-dir . "~/Project")
       (cmake-ide-build-dir . "~/Project/build")
       (cmake-ide-cmake-opts . "-DCMAKE_BUILD_TYPE=Debug")
       (helm-make-build-dir . "build")
       (helm-make-arguments . "-j7"))))
#+END_SRC

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

** 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 emacs-lisp

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 emacs-lisp

* 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.                                     |
| ~SPC m p c~ | Run CMake and set compiler flags for auto-completion and flycheck       |
| ~SPC m p C~ | Run CMake if compilation database JSON file is not found                |
| ~SPC m p d~ | Remove file connected to current buffer and kill buffer, then run CMake |
| ~SPC m c c~ | Compile project                                                         |

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

** Debugging (realgud)

 | Key Binding | Description     |
 |-------------+-----------------|
 | ~SPC m d d~ | open cmd buffer |
 | ~SPC m d e~ | eval variable   |
 | ~s~         | step over       |
 | ~i~         | step into       |
 | ~b~         | set break       |
 | ~B~         | unset break     |
 | ~o~         | step out        |
 | ~c~         | continue        |
 | ~e~         | eval variable   |
 | ~r~         | restart         |
 | ~q~         | quit debug      |
 | ~S~         | goto cmd buffer |

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