Note: This is a work in progress:
- documentation might not be up-to-date
- changes can break compability with earlier versions
- use at your own risk!
- open issues, fork-it and create pull-requests!
The easiest way to get irony-mode and its dependencies is to use el-get.
M-x el-get-install RET irony-mode RET
My irony-mode configuration for el-get can help you get started!
You are ready to go, you can jump to: Usage
Download and build
git >= 1.6.5 and later:
git clone --recursive git://github.com/Sarcasm/irony-mode.git
git < 1.6.5:
git clone git://github.com/Sarcasm/irony-mode.git git submodule update --init
cd irony-mode mkdir -p build cd build cmake .. && make -j 4 make install
Note: It is recommended to proceed to the installation step. This is not a
system-wide installation, it shouldn't require any privilege. The installation
step will help
irony.el to find the binary without additional configuration.
Recommended packages and versions:
|auto-complete||1.4||recommended||you can check the version in the auto-complete.el header|
|auto-complete fork||1.4||as-you-wish||conflicts w/ auto-complete AND popup, able to display detailed completions such as overloaded functions|
|JSON||All||needed||Built-in since Emacs 23, can be downloaded here: [json.el][json-el-ref]|
[json-el-ref]: http://cvs.savannah.gnu.org/viewvc/*checkout*/emacs/lisp/json.el?root=emacs) "json.el"
Add irony-mode to the load
(add-to-list 'load-path (expand-file-name "~/IRONY/MODE/PATH/elisp/"))
And fill-in a basic configuration as shown below in Auto Complete.
If you want the completion to work on a project you will probably need give some
information about the flags necessary to compile a file. The best way to achieve
this is to use a Compilation Database. Otherwise you
can always use the customizable variables:
M-x customize-group RET irony RET.
Note: If you want to force the reload of the flags on the server, you can
use the command
M-x irony-reload-flags. This shouldn't be necessary if you use
the compilation database plugin.
To enable a plugin call
(irony-enable 'plugin-name). To enable more than one
plugin at once call the same function with a list
(irony-enable '(plugin-1 plugin-2)).
Code completion with auto-complete.
(require 'auto-complete) (require 'yasnippet) (require 'irony) ;Note: hit `C-c C-b' to open build menu ;; the ac plugin will be activated in each buffer using irony-mode (irony-enable 'ac) ; hit C-RET to trigger completion (defun my-c++-hooks () "Enable the hooks in the preferred order: 'yas -> auto-complete -> irony'." ;; be cautious, if yas is not enabled before (auto-complete-mode 1), overlays ;; *may* persist after an expansion. (yas/minor-mode-on) (auto-complete-mode 1) ;; avoid enabling irony-mode in modes that inherits c-mode, e.g: php-mode (when (member major-mode irony-known-modes) (irony-mode 1))) (add-hook 'c++-mode-hook 'my-c++-hooks) (add-hook 'c-mode-hook 'my-c++-hooks)
Note: If my fork of
auto-complete is used you should be careful
to not have another installation of
both of them are present in my fork.
You can eval these lines in the
(let ((requirements (or (require 'auto-complete nil t) (require 'popup nil t)))) (message "You should remove both auto-complete and popup before using my fork of auto-complete"))
C-x C-e at the end of the expression to evaluate.
In order to work correctly,
irony-mode needs to know the compile flags. This
plugin allow aims to provide as automatic as possible compile flags discovery,
with minimum user input.
It works great with the following tools:
CMake >= 2.8.5
Ninja >= 1.2 - Use
ninja -t compdbto generate a compilation database for your project.
Bear - Bear is a tool that can generate a
compile_commands.jsonfile by "monitoring" the build of a project. The typical usage for a
makebased 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_completeautomatically, take a look there: cc_args.py documentation.
The JSON Compilation Database Format Specification page
might reference some new tools in the future supporting the
compile_commands.json format (such as
Bear described above).
irony-mode support that file format and hopefully it should work
out-of-the-box for such tool.
This is not really a plugin but something built-in irony-mode core, as such it
doesn't require any activation code. Just hit
C-c C-b to display the build
The menu should be self explanatory, if it's not the case open an issue please.
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.
How do I use a custom version of libclang?
On a system with multiple versions of libclang installed, it is possible to hint CMake in order to pick-up the preferred one. Two variables can be specified when invoking CMake:
LIBCLANG_INCLUDE_PATH=/path/to/libclang/include-dir: The path to the include directory that contains the header file clang-c/Index.h.
LIBCLANG_LIBRARY_PATH=/path/to/libclang/libraries: The path to the directory that contains the libclang library, e.g: libclang.so on Linux.
Example of a CMake invocation using a custom libclang installation:
mkdir build cd build cmake -DLIBCLANG_INCLUDE_PATH=~/llvm-3.4/include/ \ -DLIBCLANG_LIBRARY_PATH=~/llvm-3.4/lib/ ..
CMake doesn't find libclang...
When libclang is installed in a non-standard path CMake may produce the following error:
CMake Error at /usr/share/cmake-2.8/Modules/FindPackageHandleStandardArgs.cmake:108 (message): Could NOT find LibClang (missing: LibClang_LIBRARY LibClang_INCLUDE_DIR) Call Stack (most recent call first): /usr/share/cmake-2.8/Modules/FindPackageHandleStandardArgs.cmake:315 (FPHSAFAILURE_MESSAGE) cmake/FindLibClang.cmake:35 (find_package_handle_standard_args) server/CMakeLists.txt:4 (find_package)
This can be fixed by using the same method as described above, using a custom version of libclang.
Please report an issue if the include and library paths are the standard libclang installation paths on your system. Other users may benefit from these paths being handled natively by irony-mode.
I got an error due to 'stdarg.h'...
If by looking into the log file (
/tmp/irony.$$PID.log on Linux) you
can have the following error:
'stdarg.h' file not found
Assuming (otherwise it might be necessary to adjust the code):
- Clang version is 3.2
- Clang is installed in
You can use the following configuration:
;; The Clang installation missed the system include directory ;; "/usr/lib/clang/3.2/include/" (when (file-exists-p "/usr/lib/clang/3.2/include/") (setq irony-libclang-additional-flags '("-isystem" "/usr/lib/clang/3.2/include/")))
This is issue is a known problem:
Make sure that Clang is using its own <stddef.h>. It will be in a directory ending in
clang/3.2/include/where 3.2 is the version of clang that you are using. You may need to explicitly add it to your header search. Usually clang finds this directory relative to the executable with CompilerInvocation::GetResourcesPath(Argv0, MainAddr), but using just the libraries, it can't automatically find it.
libclang.so: cannot open shared object file...
irony-server succeed but you have the following message
when you try to run the
'irony-server: error while loading shared libraries: libclang.so: cannot open shared object file: No such file or directory
Maybe it's due to a non-standard location for your installation of
libclang. A path such as
/usr/local/lib might not be in the path
list of the dynamic loader (see ld.so.conf).
To solve this issue it is possible to build
irony-server with the
cmake -DUSE_RPATH=ON ..
auto-complete acts strangely, it tries to complete inside string literals...
In order to enable header completion, such as:
ac plugin allows
auto-complete to complete inside string
(setq ac-disable-faces (delq 'font-lock-string-face ac-disable-faces))
Please create an issue if you find this unacceptable.