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

C/C++ layer

• Description
  • Features:
• Install
  • Layer
  • Default mode for header files
  • Backends
    • RTags
      • External dependencies
      • Configuration
    • cquery / ccls (lsp backends)
      • Features:
      • External dependencies
        • cquery server
        • ccls server
      • Configuration
        • Basic
        • Setting path to backend executable
        • Semantic highlighting
        • Additional configuration options
        • Example dotspacemacs-configuration-layers entry
      • Completion
      • Debugger (dap integration)
  • Clang Configuration
    • clang-format
    • Company-clang and flycheck
  • Enable google-set-c-style
  • Newlines
  • Projectile sub-project adoption
• Key bindings
  • Formatting (clang-format)
  • RTags
  • cquery / ccls
    • backend (language server)
    • goto
      • goto/hierarchy
      • goto/member
  • debugger

Description

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

Features:

• Support syntax checking via flycheck with Clang.
• Support for disassembly of code with disaster.
• Support code reformatting with 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 stickyfunc-demos for demos in some programming languages. (when semantic layer is included)
• Support common refactoring with semantic-refactor. See 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 realgud debugger.
• Support for rtags.
• Support for cquery or ccls as an lsp backend.

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

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables c-c++-default-mode-for-headers 'c++-mode)))

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 dir-locals.

Backends

This layer supports the selection of one of 3 available backends for code navigation etc via the c-c++-backend configuration variable.

RTags

RTags is a well established clang-based source code indexing tool.

External dependencies

Install the RTags server via homebrew, the aur or from source according to the instructions here. N.B. RTags is not supported on Windows at the time of writing, although there is an open issue with some recent activity on github.

Configuration

To enable support for rtags, set the layer variable c-c++-backend:

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables c-c++-backend 'rtags)))

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++-rtags-completion to nil:

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables
                         c-c++-backend 'rtags
                         c-c++-enable-rtags-completion nil)))

cquery / ccls (lsp backends)

cquery and ccls are alternative implementations of the language server protocol based on libclang. They claim to be more efficient than existing tools at indexing large code bases.

Features:

• Cross references (definitions, references, base/derived classes/methods, type instances, …)
• Diagnostics
• Completion with company-lsp
• Semantic highlighting
• See more on https://github.com/cquery-project/cquery/wiki/Emacs
• Cross-platform - functional on Windows, Linux and OSX.

External dependencies

Install one (or both) of the following:

cquery server

Install the cquery server. Instructions.

ccls server

Install the ccls server. Instructions.

Configuration

Basic

Select either cquery or ccls as the c-c++ layer backend by adding the following to your dotfile:

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables c-c++-backend 'lsp-cquery))) ;or 'lsp-ccls

N.B. The LSP layer will be loaded automatically if either backend is selected.

Setting path to backend executable

The basic configuration above should work if the cquery/ccls executable folder is present in your path. If not, you can set the path explicitly.

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables
                         c-c++-backend 'lsp-cquery
                         c-c++-lsp-executable "/path/to/bin/cquery/or/ccls")))

If you need to expand ~ in the path, you can use file-truename like

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables
                         c-c++-backend 'lsp-cquery
                         c-c++-lsp-executable (file-truename "~/bin/cquery/or/ccls"))))

Semantic highlighting

Semantic highlighting is disabled by default. To enable, set the c-c++-lsp-sem-highlight-method variable to either 'font-lock or 'overlay. To enable the rainbow semantic highlighting colour theme, set c-c++-lsp-sem-highlight-rainbow to t.

Additional configuration options

Both lsp backends are configured to store their index cache in a subdirectory of .emacs.d/cache. This can be overridden by specifying an explicit c-c++-lsp-cache-dir. Setting this value to a relative path will cause the index cache to be placed in a subdirectory of your project root.

There are other initialization options such as the number of indexer threads, cache serialization format. They have good default values. See config.el of the layer and the backends' respective homepages for more info.

• Emacs section of cquery wiki
• Emacs section of ccls wiki

Example dotspacemacs-configuration-layers entry

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables
                         c-c++-adopt-subprojects t
                         c-c++-backend 'lsp-ccls
                         c-c++-lsp-executable (file-truename "~/dev/cpp/ccls/Release/ccls")
                         c-c++-lsp-sem-highlight-rainbow t)))

Completion

company-lsp provides completion functionality. Client-side cache and sorting have been disabled in favour of server, as recommended by cquery=/=ccls wikis.

Debugger (dap integration)

To install the debug adapter you may run M-x dap-gdb-lldb-setup when you are on Linux or download it manually from Native Debug and adjust dap-gdb-lldb-path.

Clang Configuration

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

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables c-c++-enable-clang-support t)))

N.B. do not set this option if either the cquery or ccls backend

clang-format

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:

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables c-c++-enable-clang-format-on-save t)))

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.

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

  (c-c++ :variables c-c++-enable-google-style t)

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:

  (c-c++ :variables c-c++-enable-google-style t
                    c-c++-enable-google-newline t)

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.

  (c-c++ :variables c-c++-enable-auto-newline t)

Projectile sub-project adoption

To prevent projectile from using subproject root when visiting files in a subproject, set c-c++-adopt-subprojects to t.

  (c-c++ :variables c-c++-adopt-subprojects t)

This is based on a recommendation on the cquery and ccls wikis, but should be more generally applicable.

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

cquery / ccls

The key bindings listed below are in addition to the default key bindings defined by the LSP layer. A [ccls] or [cquery] suffix indicates that the binding is for the indicated backend only.

backend (language server)

Key binding	Description
SPC m b f	refresh index (e.g. after branch change)
SPC m b p	preprocess file

goto

Key binding	Description
SPC m g &	find references (address)
SPC m g R	find references (read)
SPC m g W	find references (write)
SPC m g c	find callers
SPC m g C	find callees
SPC m g v	vars
SPC m g f	find file at point (ffap)
SPC m g F	ffap other window

goto/hierarchy

Key binding	Description
SPC m g h b	base class(es)
SPC m g h d	derived class(es) [ccls]
SPC m g h c	call hierarchy
SPC m g h C	call hierarchy (inv)
SPC m g h i	inheritance hierarchy
SPC m g h I	inheritance hierarchy (inv)

goto/member

Key binding	Description
SPC m g m h	member hierarchy
SPC m g m t	member types [ccls]
SPC m g m f	member functions [ccls]
SPC m g m v	member variables [ccls]

debugger

Key binding	Description
SPC m d d d	start debugging
SPC m d d l	debug last configuration
SPC m d d r	debug recent configuration
SPC m d c	continue
SPC m d i	step in
SPC m d o	step out
SPC m d s	next step
SPC m d v	inspect value at point
SPC m d r	restart frame
SPC m d .	debug transient state
SPC m d a	abandon current session
SPC m d A	abandon all process
SPC m d e e	eval
SPC m d e r	eval region
SPC m d e t	eval value at point
SPC m d S s	switch session
SPC m d S t	switch thread
SPC m d S f	switch frame
SPC m d I i	inspect
SPC m d I r	inspect region
SPC m d I t	inspect value at point
SPC m d b b	toggle a breakpoint
SPC m d b c	change breakpoint condition
SPC m d b l	change breakpoint log condition
SPC m d b h	change breakpoint hit count
SPC m d b a	add a breakpoint
SPC m d b d	delete a breakpoint
SPC m d b D	clear all breakpoints
SPC m d '_	Run debug REPL
SPC m d w l	list local variables
SPC m d w o	goto output buffer if present
SPC m d w s	list sessions
SPC m d w b	list breakpoints