:lang cc

C > C++ == 1

1. Description

This module adds support for the C-family of languages: C, C++, and Objective-C.

  • Code completion (company-irony)
  • eldoc support (irony-eldoc)
  • Syntax-checking (flycheck-irony)
  • Code navigation (rtags)
  • File Templates (c-mode, c++-mode)
  • Snippets (cc-mode, c-mode, c++-mode)
  • Several improvements to C++11 indentation and syntax highlighting.

1.2. Module flags

+lsp
Enable LSP support for c-mode, c++-mode, and objc-mode. Disables irony + rtags. Requires :tools lsp and a langserver (supports ccls, cquery, and clang v9+).

1.4. TODO Hacks

No hacks documented for this module.

2. Prerequisites

This module’s requirements change depending on how you use it.

  • If +lsp is enabled, you need one of clangd v9+ or ccls.
  • If +lsp is not enabled, you need irony-server and rtags.
  • Other features in this module depend on:
    • (optional) glslangValidator, for GLSL completion in glsl-mode
    • (optional) cmake, for code completion in cmake-mode
  • You will need a C/C++ compiler, like gcc or clang.

2.1. LSP servers

lsp-mode and eglot support a few LSP servers, but clangd and ccls are recommended.

clangd (must be v9 or newer)
clangd is included with llvm which should be available through your OS’ package manager.
  • Linux:
    • Debian 11 & Ubuntu 20.10: $ apt-get install clangd-11
    • Fedora & CentOS/RHEL 8+: $ dnf install clang-tools-extra
    • openSUSE: $ zypper install clang
    • Arch: $ pacman -S clang
  • BSDs:
    • NetBSD & OpenBSD: $ pkg_add clang-tools-extra
  • macOS: $ brew install llvm // 1GB+ installation! May take a while!
  • Windows: use the win64 installer from LLVM’s GitHub release page.
ccls
Available in many OS’ package managers as ccls. Otherwise, there are alternative install methods listed in the project’s wiki.
cmake-language-server
available through pip on most distributions

2.2. irony-server

Irony powers the code completion, eldoc and syntax checking systems.

After installing its dependencies (Clang and CMake), run M-x irony-install-server in Emacs.

2.2.1. macOS

Due to linking issues, macOS users must compile irony-server manually:

# ⎘
$ brew install cmake
$ brew install llvm
$ git clone https://github.com/Sarcasm/irony-mode irony-mode
# ⎘
$ mkdir irony-mode/server/build
$ pushd irony-mode/server/build

$ DEST="$HOME/.emacs.d/.local/etc/irony-server/"
$ cmake -DCMAKE_PREFIX_PATH=/usr/local/opt/llvm \
	-DCMAKE_INSTALL_RPATH_USE_LINK_PATH=ON \
	-DCMAKE_INSTALL_PREFIX="$DEST" ../
$ cmake --build . --use-stderr --config Release --target install

$ install_name_tool -change @rpath/libclang.dylib \
      /usr/local/opt/llvm/lib/libclang.dylib \
      "$DEST/bin/irony-server"

# Cleanup
$ popd
$ rm -rf irony-mode

2.3. rtags

Code navigation requires an rtags server (rdm) installed. This should be available through your OS’s package manager.

This module will auto-start rdm when you open C/C++ buffers (so long as one isn’t already running). If you prefer to run it yourself:

# ⎘
$ rdm &
$ rc -J $PROJECT_ROOT  # loads PROJECT_ROOT's compile_commands.json

3. TODO Usage

This module has no usage documentation yet. Write some?

4. Configure

4.1. Project compile settings

By default, a set of default compile settings are defined in +cc-default-compiler-options for C, C++ and Objective C. Irony, rtags and flycheck will fall back to these. This variable does nothing for LSP users.

For a more universal solution: both LSP servers and irony will recognize a compilation database (a compile_commands.json file). There are many ways to generate one. Here is an example using CMake and bear:

# ⎘
# For CMake projects
$ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
# ⎘
# For non-CMake projects
$ make clean
$ bear make

Use M-x +cc/reload-compile-db to reload your compile db in an already-open C/C++/ObjC buffer.

4.1.1. Known issues with bear on macOS

MacOS’ System Integrity Protection (SIP) might interfere with bear if make is under /usr/bin/ which results in an empty compilation database.

From the bear readme:

Security extension/modes on different operating systems might disable library preloads. This case Bear behaves normally, but the result compilation database will be empty. (Please make sure it’s not the case when reporting bugs.) Notable examples for enabled security modes are: OS X 10.11 (check with csrutil status | grep ’System Integrity Protection’), and Fedora, CentOS, RHEL (check with sestatus | grep ’SELinux status’).

Workaround could be to disable the security feature while running Bear. (This might involve reboot of your computer, so might be heavy workaround.) Another option if the build tool is not installed under certain directories. Or use tools which are using compiler wrappers. (It injects a fake compiler which does record the compiler invocation and calls the real compiler too.) An example for such tool might be scan-build. The build system shall respect CC and CXX environment variables.

A workaround might be to install make via Homebrew which puts gmake under /usr/local/.

# ⎘
$ brew install make
# ⎘
$ make clean
$ bear gmake

Additional info:

4.2. Configure LSP servers

Search for your combination of (LSP client package, LSP server). You are using lsp-mode by default, eglot if you have :tools lsp +eglot active in your init.el file.

4.2.1. LSP-mode with clangd

# ⎘
(setq lsp-clients-clangd-args '("-j=3"
				"--background-index"
				"--clang-tidy"
				"--completion-style=detailed"
				"--header-insertion=never"
				"--header-insertion-decorators=0"))
(after! lsp-clangd (set-lsp-priority! 'clangd 2))

This will both set your clangd flags and choose clangd as the default LSP server everywhere clangd can be used.

4.2.2. LSP-mode with ccls

# ⎘
(after! ccls
  (setq ccls-initialization-options '(:index (:comments 2) :completion (:detailedLabel t)))
  (set-lsp-priority! 'ccls 2)) ; optional as ccls is the default in Doom

This will both set your ccls flags and choose ccls as the default server. CCLS documentation lists available options, use t for true, :json-false for false, and :json-null for null.

4.2.3. Eglot with clangd

# ⎘
(set-eglot-client! 'cc-mode '("clangd" "-j=3" "--clang-tidy"))

This will both set your clangd flags and choose clangd as the default server (if it is the last set-eglot-client! 'cc-mode in your config).

4.2.4. Eglot with ccls

# ⎘
(set-eglot-client! 'cc-mode '("ccls" "--init={\"index\": {\"threads\": 3}}"))

This will both set your ccls flags and choose ccls as the default server (if it is the last set-eglot-client! 'cc-mode in your config). CCLS documentation lists available options

5. Troubleshooting

There are no known problems with this module. Report one?

6. Appendix

6.1. Eglot specific bindings

When using +lsp and :tools lsp +eglot, lsp-mode is replaced with eglot, and an additional function to get inheritance type hierarchy is added:

Binding Description
<localleader> c t Display inheritance type hierarchy (upwards)
<prefix> <localleader> c t Display inheritance type hierarchy (downwards)