Skip to content
A C/C++ minor mode for Emacs powered by libclang
Emacs Lisp C++ CMake Python C
Branch: master
Clone or download

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
screenshots move bundled ac plugin in standalone repository, bump docs Apr 21, 2014
server fix ClangConfig.cmake target without header search path, bump CMake >= 3 May 16, 2019
.dir-locals.el .dir-locals.el: syntax change Apr 27, 2014
.gitignore move elisp files in top directory and the server in its own directory Apr 21, 2014
.travis.yml CMake: remove unnecessary cruft May 15, 2019
CONTRIBUTING.md small documentation cleanup Jun 5, 2014
COPYING Add a small GPL header. Nov 4, 2011
README.md README: Add section about how to access newer versions of Clang/LLVM Dec 4, 2019
irony-cdb-clang-complete.el Use throw-catch to simplify. Prioritize compile_flags.txt Jan 30, 2020
irony-cdb-json.el irony-cdb: follow symbolic links for filename comparison (#542) Jul 3, 2019
irony-cdb-libclang.el irony: iotask for 'get-compile-options' Apr 25, 2017
irony-cdb.el irony-cdb: fix symbol quoting in documentation May 15, 2017
irony-completion.el add opt-in option to remove duplicates in completion menu [GH-503] Oct 30, 2018
irony-diagnostics.el irony: iotask for 'parse' and 'diagnostics' Apr 25, 2017
irony-iotask.el iotask: discard callback if has been killed [GH-427] Sep 20, 2017
irony-server.rst Add man page source in rst (reStructuredText) format (#441) Oct 2, 2017
irony-snippet.el irony-snippet: irony-snippet-available-p nil if yas-minor-mode is nil Aug 24, 2015
irony.el Release 1.4.0 Oct 9, 2019

README.md

Irony-Mode

A C/C++ minor mode powered by libclang

irony-mode is an Emacs minor-mode that aims at improving the editing experience for the C, C++ and Objective-C languages. It works by using a combination of an Emacs package and a C++ program (irony-server) exposing libclang.

Features:

Dependencies

Elisp dependencies

These dependencies will be installed automatically when using the standard installation procedure described below.

Package Comment
cl-lib Built-in since Emacs 24.3
json Built-in since Emacs 23.1
YASnippet Optional. May be used to provide post-completion expansion of function arguments

Irony-Server prerequisites

irony-server provides the libclang interface to irony-mode. It uses a simple protocol based on S-expression. This server, written in C++ and requires the following packages to be installed on your system:

Installation

The recommended way to install irony-mode and its dependencies is to use a package manager.

  • Using MELPA

      M-x package-install RET irony RET
    
  • Using apt on Debian ≥10 and derivatives

      sudo apt install elpa-irony
    

Accessing a newer Clang and LLVM Toolchain on Debian and derivatives

The backports mechanism is the recommended and officially supported method of accessing newer versions than Debian stable provides.

    sudo apt install -t $release_name-backports elpa-irony

If the llvm-toolchain backport is not new enough please use the following repository: LLVM Debian/Ubuntu nightly packages. This repository is maintained by Sylvestre Ledru, who is responsible for the official Debian package. His repository also supports Ubuntu and derivatives. When using this unofficial repository the MELPA package of irony-mode should be used in preference to the elpa-irony package.

Configuration

(add-hook 'c++-mode-hook 'irony-mode)
(add-hook 'c-mode-hook 'irony-mode)
(add-hook 'objc-mode-hook 'irony-mode)

(add-hook 'irony-mode-hook 'irony-cdb-autosetup-compile-options)

Windows considerations

irony-mode should work fine on Windows but there are some things to take care of first.

  • libclang.dll is expected to be available in the PATH or in Emacs' exec-path.

  • Emacs >= 24.4 is required. A bug in previous versions makes irony unuseable (Emacs bug #18420).

  • w32-pipe-read-delay default value of 50 should be changed. This should not cause any issue on today's version of Windows. The default value of 50 may be lowered in mainline Emacs in future versions, until then, I suggest to set it to 0.

  • w32-pipe-buffer-size, introduced by Emacs 25, can be set to a larger value than the default to improve irony-server communication performances (c.f. https://github.com/Sarcasm/irony-mode/issues/321). The variable to customize is irony-server-w32-pipe-buffer-size.

Windows configuration tweaks to add to your Emacs configuration:

;; Windows performance tweaks
;;
(when (boundp 'w32-pipe-read-delay)
  (setq w32-pipe-read-delay 0))
;; Set the buffer size to 64K on Windows (from the original 4K)
(when (boundp 'w32-pipe-buffer-size)
  (setq irony-server-w32-pipe-buffer-size (* 64 1024)))

Usage

On the first run, irony-mode will ask you to build and install irony-server. To do so, type M-x irony-install-server RET.

To tune irony-mode, use customize:

M-x customize-group RET irony RET

In order to provide context sensitive and accurate information, irony-mode needs to know about the compiler flags used to parse the current buffer. The best way to achieve this is to use a Compilation Database.

Compilation Database

In order to work correctly, irony-mode needs to know the compile flags. irony-cdb aims to provide as automatic as possible compile flags discovery, with minimal user input.

Please refer to irony-cdb-autosetup-compile-options and irony-cdb-compilation-databases.

Right now irony-cdb supports the following compilation databases:

  • JSON Compilation Database - A JSON formatted file generated by various build tools. The file is named compile_commands.json, it lists the compile options associated to each file in the project.

    • CMake >= 2.8.5 will generate a compilation database in the build directory when issuing the following command cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON <...>.

    • ninja >= 1.2 will generate a JSON Compilation Database when using the compdb tool.

    • Bear generates a JSON Compilation Database file by "monitoring" the build of a project. The typical usage for a make-based project will be bear -- make -B.

  • .clang_complete - A file at the root of your project containing the compilation flags, one per line. This is compatible with the with plugin Rip-Rip/clang_complete. If you want to generate the .clang_complete automatically, take a look at the cc_args.py documentation.

More detailed information on compilation database is available here:

FAQ

It's slow, why?

A bug in old version of Clang (at least '3.1-8') caused the completion to fail on the standard library types. To eliminate this bug an optimisation has been disabled in the parsing of a translation unit. This result in a slower parsing.

This only affect old versions of Clang (< 3.2), it is suggested to update your libclang installation if you want to take advantage of the optimizations.

libclang.so: cannot open shared object file...

Compiling irony-server succeed but you have the following message when you try to run the irony-server executable:

'irony-server: error while loading shared libraries: libclang.so: cannot open shared object file: No such file or directory

When libclang is installed in a non-standard location (one that is missing from the path list of the dynamic loader, see ld.so.conf) you can tell CMake to use the rpath when installing the target irony-server. To enable rpath in CMake use the following command:

cmake -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=ON <args...>

If you're running OS X, you can also use install_name_tool to explicitly tell irony-server where an appropriate version of libclang.dylib lives. For example, Homebrew (with brew install llvm --with-clang) will install a libclang.dylib library at /usr/local/opt/llvm/lib/libclang.dylib; you can instruct irony-server to use this with something like:

install_name_tool -change @rpath/libclang.dylib /usr/local/opt/llvm/lib/libclang.dylib irony-server
You can’t perform that action at this time.