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

C/C++ layer

• Description
  • Features:
• Install
  • Layer
  • Backends
    • LSP
      • Features
      • External dependencies
        • clangd
        • ccls server
      • Configuration
        • Basic
        • Selecting an alternate LSP server
        • Path to LSP server executables
        • Semantic highlighting
        • Cache directory (absolute or relative)
        • Example dotspacemacs-configuration-layers entry
      • Completion
      • Debugger (dap integration)
        • Adapter selection
        • Microsoft adapter installation
        • CodeFreak adapter installation
        • LLDB adapter installation
    • rtags
      • External dependencies
      • Configuration
  • Default mode for header files
  • Organize file header includes on save
  • clang-format
  • Enable google-set-c-style
  • Newlines
  • Projectile sub-project adoption
• Key bindings
  • LSP
    • ccls
      • backend (language server)
      • goto
      • goto/hierarchy
      • goto/member
    • debugger
  • RTags
  • Additional key bindings
    • Disassemble
    • Formatting (clang-format)
    • Open matching files
    • Refactor

Description

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

Features:

• Multiple backends support:

  • LSP with either clangd or ccls
  • rtags (gtags)
  • emacs-ycmd
• Support for debuggers realgud and dap (with LSP backend)
• Support syntax checking via flycheck (syntax-checking layer required)
• Auto-completion via company (auto-completion layer required)
• Support code reformatting with clang-format.
• Support for disassembly of code with disaster.

• sematic layer integration:

  • Function or variable definition at the bottom
  • Current function cursor is at the top. See stickyfunc-demos for demos in some programming languages.
  • Support common refactoring with semantic-refactor. See srefactor-demos for demonstration of refactoring features.

• cscope layer integration:

  • code navigation

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.

Backends

Supported backends are:

• lsp-clangd using clangd LSP server
• lsp-ccls using ccls LSP server
• rtags using rtags
• ycmd using emacs-ycmd

To choose a default backend set the layer variable c-c++-backend:

  (c-c++ :variables c-c++-backend 'lsp-clangd)

Alternatively the lsp-clangd backend will be automatically chosen if the layer lsp is used and you did not specify any value for c-c++-backend.

Note: It is recommended to use a modern backend like the lsp ones.

The backend can be chosen on a per project basis using directory local variables (files named .dir-locals.el at the root of a project), an example is to use the lsp-ccls backend:

  ;;; Directory Local Variables
  ;;; For more information see (info "(emacs) Directory Variables")

  ((c++-mode (c-c++-backend . lsp-ccls)))

Note: you can easily add a directory local variable with SPC f v d.

LSP

LSP support is provided via the LSP layer, using one of two available backends (all based on libclang).

• clangd
• ccls

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 lsp
• Semantic highlighting (ccls or clangd)
• Cross-platform - functional on Windows, Linux and macOS.

External dependencies

Install one (or more) of the following (clangd is used by default):

clangd

Install clang using a binary distribution downloaded from the LLVM releases page or via your package manager. This is the default implementation that's used by the Emacs lsp-mode package and probably the easiest to install.

• clangd protocol extensions page

ccls server

Install the ccls server. See instructions. This is currently the most fully featured implementation, including semantic highlighting and some navigation/ introspection features that are not provided by clangd.

Note that prebuild binaries exist for most Linux distros and MacOS using Homebrew.

Configuration

Basic

To use the default clangd language server, select lsp-clangd 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-clangd)))

Selecting an alternate LSP server

To choose an alternate LSP server set the layer variable c-c++-backend to another supported backend, for instance lsp-ccls:

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

Path to LSP server executables

LSP expects to find the LSP server executables in your PATH. If you want to specify the location of an executable then you need to set the appropriate variable:

Server	Variable name
clangd	lsp-clients-clangd-executable
ccls	ccls-executable

Semantic highlighting

Currently only available for lsp-ccls and clangd. Semantic highlighting can precisely highlight identifiers.

Semantic highlighting is disabled by default. To enable it set the layer c-c++-lsp-enable-semantic-highlight to non-nil. It is possible to give a different color for each identifier by setting the variable to 'rainbow.

When semantic highlighting is enabled then the method that's used to highlight the text relies on Emacs' fastest font-lock mechanism. A more accurate but also slower method is to use overlays. To use overlays set the layer variable c-c++-lsp-semantic-highlight-method to 'overlay.

Cache directory (absolute or relative)

clangd cache directoy is .clangd and cannot be changed.

ccls default directory is .ccls-cache, it can be changed by setting the :cache option in the variable ccls-initialization-options.

See the full list of configuration options you can set at:

• 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-enable-semantic-highlight 'rainbow)))

Completion

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

Debugger (dap integration)

Adapter selection

To select the active adapters, configure the c-c++-dap-adapters layer variable. By default only the Microsoft extension is available.

Adapter	Supported debuggers	DAP mode
Microsoft	gdb, lldb, Visual Studio Debugger	dap-cpptools
CodeFreak	gdb, lldb	dap-gdb-lldb
LLVM Project	lldb	dap-lldb

Example configuration with two adapters selected:

  (setq-default dotspacemacs-configuration-layers
                '((c-c++ :variables
                         c-c++-dap-adapters '(dap-lldb dap-cpptools)))

Microsoft adapter installation

To install the debug adapter you may run M-x dap-cpptools-setup when you are on Linux.

CodeFreak adapter installation

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 the dap-gdb-lldb-path variable.

LLDB adapter installation

Install the lldb-vscode program. It usually comes with lldb from your distribution's package repository. Alternatively build directly following the official installation instructions.

Adjust the dap-lldb-debug-program variable to match the executable.

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.

Note: 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 the auto-completion layer is enabled). 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)))

Default mode for header files

The mode for header files is auto detected by `c-or-c++-mode' in Emacs > 26.1+. Older versions of Emacs will open header files in c-mode by default, you can open them in c++-mode by setting the variable c-c++-default-mode-for-headers as follow.

  (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 manual: dir-locals.

Organize file header includes on save

To organize the file header includes on save, set the layer variable c++-enable-organize-includes-on-save to t in the dotfile:

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

clang-format

clang-format allows for 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 in any of its parent directories. If no .clang-format file 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)))

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 need 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 ccls wikis, but should be more generally applicable.

Key bindings

LSP

The default key bindings for the LSP implementations are defined and documented in the LSP layer.

ccls

A [ccls] 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

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	find dead functions
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	display reference tree at point
SPC m g R	rename symbol
SPC m g s	print source arguments
SPC m g S	display summary
SPC m g t	symbol type
SPC m g T	taglist
SPC m g u	display include dependency tree
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

Additional key bindings

Disassemble

Key binding	Description
SPC m D	disaster: disassemble c/c++ code

Formatting (clang-format)

Key binding	Description
SPC m = =	format current region or buffer
SPC m = f	format current function

Open matching files

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)

Refactor

Key binding	Description
SPC m r .	srefactor: refactor thing at point.
SPC m r i	organize includes