doomemacs/modules/lang/cc

:lang cc

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
  • LSP servers
  • :editor format
• Usage
  • Eglot-specific bindings
• Configure
  • Project compile settings
    • Known issues with bear on macOS
  • Configure LSP servers
    • LSP-mode with clangd
    • LSP-mode with ccls
    • Eglot with clangd
    • Eglot with ccls
• Troubleshooting
• Frequently asked questions
• Appendix

Description   unfold

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

Through LSP, this module offers:

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

Maintainers

• @hlissner

Become a maintainer?

Module flags

lsp

Enable LSP support for c-mode, c++-mode, and objc-mode. Requires doom-module::tools lsp and a langserver (supports clangd, ccls, and cquery).

+tree-sitter

Leverages tree-sitter for better syntax highlighting and structural text editing. Requires doom-module::tools tree-sitter.

Packages

• doom-package:cmake-mode
• doom-package:cuda-mode
• doom-package:demangle-mode
• doom-package:disaster

• doom-package:glsl-mode

  • doom-package:company-glsl
• doom-package:modern-cpp-font-lock unless doom-module:+tree-sitter
• doom-package:opencl-mode

• if doom-module:+lsp

  • doom-package:ccls if doom-module::tools lsp -eglot

Hacks

No hacks documented for this module.

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

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

• If doom-module:+lsp is enabled, you need one of clangd v9+ or ccls.

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

LSP servers

lsp-mode and eglot support a few LSP servers, but clangd is recommend:

clangd (must be v9 or newer)

clangd is included with llvm which should be available through your OS' package manager.

• Linux:

  • Debian & Ubuntu: $ apt-get install clangd
  • 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

:editor format

The formatter used is doom-executable:clang-format which should be installed alongside clang.

For more info, see doom-module::editor format.

TODO Usage

󱌣 This module's usage documentation is incomplete. Complete it?

1. Enable this module.
2. Enable the +lsp flag for the appropriate modules you want LSP support for (e.g. :lang (python +lsp) or :lang (rust +lsp)),
3. Install the prerequisite LSP servers through your package manager or other means. You can find a list of supported servers on the lsp-mode project page.
4. Run $ doom sync on the command line and restart Emacs.

Eglot-specific bindings

When using doom-module:+lsp and doom-module::tools lsp +eglot, doom-package:lsp-mode is replaced with doom-package: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)

TODO Configure

󱌣 This module's configuration documentation is incomplete. Complete it?

Project compile settings

LSP servers and Flycheck 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

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:

• Empty compilation database with compiler in /usr/local
• Workaround for 'Empty compilation database on OS X Captain

Configure LSP servers

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

LSP-mode with clangd

;;; add to $DOOMDIR/config.el
(after! lsp-clangd
  (setq lsp-clients-clangd-args
        '("-j=3"
          "--background-index"
          "--clang-tidy"
          "--completion-style=detailed"
          "--header-insertion=never"
          "--header-insertion-decorators=0"))
  (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.

LSP-mode with ccls

;;; add to $DOOMDIR/config.el
(after! ccls
  (setq ccls-initialization-options '(:index (:comments 2) :completion (:detailedLabel t)))
  (set-lsp-priority! 'ccls 1))

This will prioritize ccls over clangd, if both are present on your system. Also feel free to tweak var:ccls-initialization-options to reconfigure it (CCLS documentation lists available options; use t for true, :json-false for false, and :json-null for null).

Eglot with clangd

clangd will work with Eglot out of the box, but to customize its startup command, use fn:set-eglot-client!:

;;; add to $DOOMDIR/config.el
(after! cc-mode
  (set-eglot-client! 'cc-mode '("clangd" "-j=3" "--clang-tidy")))

Eglot with ccls

ccls will work with Eglot out of the box, but to customize its startup command, use fn:set-eglot-client!:

;;; add to $DOOMDIR/config.el
(after! cc-mode
  (set-eglot-client! 'cc-mode '("ccls" "--init={\"index\": {\"threads\": 3}}")))

CCLS documentation lists available options

Troubleshooting

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

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

󱌣 This module has no appendix yet. Write one?