Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

287 lines (234 sloc) 12.166 kb
*clang_complete.txt* For Vim version 7.3. Last change: 2011 Jun 04
clang_complete plugin documentation
clang_complete plugin *clang_complete*
1. Description |clang_complete-description|
2. Completion kinds |clang_complete-compl_kinds|
3. Configuration |clang_complete-configuration|
4. Options |clang_complete-options|
5. Known issues |clang_complete-issues|
6. PCH |clang_complete-pch|
7. cc_args.py script |clang_complete-cc_args|
8. To do |clang_complete-todo|
9. License |clang_complete-license|
Author: Xavier Deguillard <deguilx@gmail.com> *clang_complete-author*
==============================================================================
1. Description *clang_complete-description*
This plugin use clang for accurately completing C and C++ code.
Note: This plugin is incompatible with omnicppcomplete due to the
unconditionnaly set mapping done by omnicppcomplete. So don't forget to
suppress it before using this plugin.
==============================================================================
2. Completion kinds *clang_complete-compl_kinds*
Because libclang provides a lot of information about completion, there are
some additional kinds of completion along with standard ones (see >
:help complete-items
for details):
'+' - constructor
'~' - destructor
'e' - enumerator constant
'a' - parameter ('a' from "argument") of a function, method or template
'u' - unknown or buildin type (int, float, ...)
'n' - namespace or its alias
'p' - template ('p' from "pattern")
==============================================================================
3. Configuration *clang_complete-configuration*
Each project can have a .clang_complete at his root, containing the compiler
options. This is useful if you're using some non-standard include paths or
need to specify particular architecture type, frameworks to use, path to
precompiled headers, precompiler definitions etc.
Compiler options should go on individual lines (multiple options on one line
can work sometimes too, but since there are some not obvious conditions for
that, it's better to have one option per line).
Linking isn't performed during completion, so one doesn't need to specify any
of linker arguments in .clang_complete file. They will lead to completion
failure when using clang executable and will be completely ignored by
libclang.
Example .clang_complete file: >
-DDEBUG
-include ../config.h
-I../common
-I/usr/include/c++/4.5.3/
-I/usr/include/c++/4.5.3/x86_64-slackware-linux/
<
==============================================================================
4. Options *clang_complete-options*
*clang_complete-auto_select*
*g:clang_auto_select*
If equal to 0, nothing is selected.
If equal to 1, automatically select the first entry in the popup menu, but
without inserting it into the code.
If equal to 2, automatically select the first entry in the popup menu, and
insert it into the code.
Default: 0
*clang_complete-complete_auto*
*g:clang_complete_auto*
If equal to 1, automatically complete after ->, ., ::
Default: 1
*clang_complete-copen*
*g:clang_complete_copen*
If equal to 1, open quickfix window on error.
Default: 0
*clang_complete-hl_errors*
*g:clang_hl_errors*
If equal to 1, it will highlight the warnings and errors the same way clang
does it.
Default: 1
*clang_complete-periodic_quickfix*
*g:clang_periodic_quickfix*
If equal to 1, it will periodically update the quickfix window.
Default: 0
Note: You could use the g:ClangUpdateQuickFix() to do the same with a mapping.
*clang_complete-snippets*
*g:clang_snippets*
If equal to 1, it will do some snippets magic after a ( or a , inside function
call. Not currently fully working.
Default: 0
*clang_complete-snippets_engine*
*g:clang_snippets_engine*
The snippets engine (clang_complete, snipmate, ultisnips... see the snippets
subdirectory).
Default: "clang_complete"
*clang_complete-conceal_snippets*
*g:clang_conceal_snippets*
If equal to 1, vim will use vim 7.3 conceal feature to hide <# and #> which
delimit a snippets.
Default: 1 (0 if conceal not available)
Note: See concealcursor and conceallevel for conceal configuration.
*clang_complete-exec*
*g:clang_exec*
Name or path of clang executable.
Note: Use this if clang has a non-standard name, or isn't in the path.
Default: "clang"
*clang_complete-user_options*
*g:clang_user_options*
Option added at the end of clang command. Useful if you want to filter the
result, or do other stuffs. To ignore the error code returned by clang, set
|g:clang_exec| to `"clang` and |g:clang_user_options| to `2>/dev/null || exit
0"` if you're on *nix, or `2>NUL || exit 0"` if you are on windows.
Default: ""
*clang_complete-auto_user_options*
*g:clang_auto_user_options*
Set sources for user options passed to clang. Available sources are:
- path - use &path content as list of include directories (relative paths are
ignored);
- .clang_complete - use information from .clang_complete file Multiple options
are separated by comma;
- {anything} else will be treaded as a custom option source in the following
manner: clang_complete will try to load autoload-function named
getopts#{anything}#getopts, which then will be able to modify
b:clang_user_options variable. See help on |autoload| if you don't know
what it is.
An example of custom option sources is bundled with clang_complete and called
"gcc". This source runs gcc to get a list of include paths. The list of
include paths for each of supported filetypes (c, cpp, objc and objcpp) is
cached on a disk and can be removed by calling ClearGCCIncludeCaches()
function (for changes to take affect one needs to reread buffers using the
:edit command or something equivalent).
Default: "path, .clang_complete, gcc"
*clang_complete-use_library*
*g:clang_use_library*
Instead of calling the clang/clang++ tool use libclang directly. This gives
access to many more clang features. Furthermore it automatically caches all
includes in memory. Updates after changes in the same file will therefore be a
lot faster.
Default: 0
*clang_complete-library_path*
*g:clang_library_path*
If libclang.[dll/so/dylib] is not in your library search path, set this to the
absolute path where libclang is available.
Default: ""
*clang_complete-sort_algo*
*g:clang_sort_algo*
How results are sorted (alpha, priority, none). Currently only works with
libclang.
Default: "priority"
*clang_complete-complete_macros*
*g:clang_complete_macros*
If clang should complete preprocessor macros and constants.
Default: 0
*clang_complete-complete_patterns*
*g:clang_complete_patterns*
If clang should complete code patterns, i.e loop constructs etc.
Defaut: 0
==============================================================================
5. Known issues *clang_complete-issues*
If you find that completion is slow, please read the |clang_complete-pch|
section below.
If you get following error message while trying to complete anything: >
E121: Undefined variable: b:should_overload
it means that your version of Vim is too old (this is an old bug and it has
been fixed with one of patches for Vim 7.2) and you need to update it.
If clang is not able to compile your file, it cannot complete anything. Since
clang is not supporting every C++0x features, this is normal if it can do any
completion on C++0x file.
There is no difference in clang's output between private methods/members and
public ones. Which means that I cannot filter private methods on the
completion list.
==============================================================================
6. PCH *clang_complete-pch*
In case you can not or you do not want to install libclang, a precompiled
header file is another way to accelerate compilation, and so, to accelerate
the completion. It is however more complicated to install and is still slower
than the use of libclang.
Here is how to create the <vector> pch, on linux (OSX users may use
-fnext-runtime instead of -fgnu-runtime): >
clang -x c++-header /path/to/c++/vector -fno-exceptions -fgnu-runtime \
-o vector.pch
You just have to insert it into your .clang_complete: >
echo '-include-pch /path/to/vector.pch -fgnu-runtime' >> .clang_complete
<
One of the major problem is that you cannot include more that one pch, the
solution is to put the system headers or non changing headers into another
header and then compile it to pch: >
echo '#include <iostream>\n#include <vector>' > pchheader.h
clang -x c++-header ./pchheader.h -fno-exceptions -fnu-runtime \
-o ./pchheader.pch
And then add it to the .clang_complete file.
==============================================================================
7. cc_args.py script *clang_complete-cc_args*
This script, installed at ~/.vim/bin/cc_args.py, could be used to generate or
update the .clang_complete file. It works similar to gccsence's gccrec and
simply stores -I and -D arguments passed to the compiler in the
.clang_complete file. Just add the cc_args.py script as the first argument of
the compile command. You should do that every time compile options have
changed.
Example (we need -B flag to force compiling even if project is up to date): >
make CC='~/.vim/bin/cc_args.py gcc' CXX='~/.vim/bin/cc_args.py g++' -B
After running this command, .clang_complete will be created or updated with
new options. If you don't want to update an existing configuration file,
delete it before running make.
==============================================================================
8. To do *clang_complete-todo*
- Write some unit tests
- clang vs libclang accuracy for complex completions
- clang vs libclang timing
- Explore "jump to declaration/definition" with libclang FGJ
- Think about supertab (<C-X><C-U> with supertab and clang_auto_select)
- Parse fix-its and do something useful with it
==============================================================================
9. License *clang_complete-license*
Copyright (c) 2010, 2011, Xavier Deguillard
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of Xavier Deguillard nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL XAVIER DEGUILLARD BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: This license does not cover the files that come from the LLVM project,
namely, cindex.py and __init__.py, which are covered by the LLVM license.
vim:tw=78:ts=8:ft=help:norl:
Jump to Line
Something went wrong with that request. Please try again.