doc/clang_complete.txt

   1 *clang_complete.txt*    For Vim version 7.3.  Last change: 2011 Jun 04
   2
   3
   4                   clang_complete plugin documentation
   5
   6
   7 clang_complete plugin                           *clang_complete*
   8
   9 1. Description          |clang_complete-description|
  10 2. Completion kinds     |clang_complete-compl_kinds|
  11 3. Configuration        |clang_complete-configuration|
  12 4. Options              |clang_complete-options|
  13 5. Known issues         |clang_complete-issues|
  14 6. PCH                  |clang_complete-pch|
  15 7. cc_args.py script    |clang_complete-cc_args|
  16 8. To do                |clang_complete-todo|
  17 9. License              |clang_complete-license|
  18
  19 Author: Xavier Deguillard <deguilx@gmail.com>   *clang_complete-author*
  20
  21 ==============================================================================
  22 1. Description                                  *clang_complete-description*
  23
  24 This plugin use clang for accurately completing C and C++ code.
  25
  26 Note: This plugin is incompatible with omnicppcomplete due to the
  27 unconditionnaly set mapping done by omnicppcomplete. So don't forget to
  28 suppress it before using this plugin.
  29
  30 ==============================================================================
  31 2. Completion kinds                             *clang_complete-compl_kinds*
  32
  33 Because libclang provides a lot of information about completion, there are
  34 some additional kinds of completion along with standard ones (see >
  35  :help complete-items
  36 for details):
  37  '+' - constructor
  38  '~' - destructor
  39  'e' - enumerator constant
  40  'a' - parameter ('a' from "argument") of a function, method or template
  41  'u' - unknown or buildin type (int, float, ...)
  42  'n' - namespace or its alias
  43  'p' - template ('p' from "pattern")
  44
  45 ==============================================================================
  46 3. Configuration                                *clang_complete-configuration*
  47
  48 Each project can have a .clang_complete at his root, containing the compiler
  49 options. This is useful if you're using some non-standard include paths. For
  50 simplicity, please don't put relative and absolute include path on the same
  51 line. It is not currently correctly handled.
  52
  53 ==============================================================================
  54 4. Options                                      *clang_complete-options*
  55
  56                                         *clang_complete-auto_select*
  57                                         *g:clang_auto_select*
  58 If equal to 0, nothing is selected.
  59 If equal to 1, automatically select the first entry in the popup menu, but
  60 without inserting it into the code.
  61 If equal to 2, automatically select the first entry in the popup menu, and
  62 insert it into the code.
  63 Default: 0
  64
  65                                         *clang_complete-complete_auto*
  66                                         *g:clang_complete_auto*
  67 If equal to 1, automatically complete after ->, ., ::
  68 Default: 1
  69
  70                                         *clang_complete-copen*
  71                                         *g:clang_complete_copen*
  72 If equal to 1, open quickfix window on error.
  73 Default: 0
  74
  75                                         *clang_complete-hl_errors*
  76                                         *g:clang_hl_errors*
  77 If equal to 1, it will highlight the warnings and errors the same way clang
  78 does it.
  79 Default: 1
  80
  81                                         *clang_complete-periodic_quickfix*
  82                                         *g:clang_periodic_quickfix*
  83 If equal to 1, it will periodically update the quickfix window.
  84 Default: 0
  85 Note: You could use the g:ClangUpdateQuickFix() to do the same with a mapping.
  86
  87                                         *clang_complete-snippets*
  88                                         *g:clang_snippets*
  89 If equal to 1, it will do some snippets magic after a ( or a , inside function
  90 call. Not currently fully working.
  91 Default: 0
  92
  93                                         *clang_complete-snippets_engine*
  94                                         *g:clang_snippets_engine*
  95 The snippets engine (clang_complete, snipmate, ultisnips... see the snippets
  96 subdirectory).
  97 Default: "clang_complete"
  98
  99                                         *clang_complete-conceal_snippets*
 100                                         *g:clang_conceal_snippets*
 101 If equal to 1, vim will use vim 7.3 conceal feature to hide <# and #> which
 102 delimit a snippets.
 103 Default: 1 (0 if conceal not available)
 104 Note: See concealcursor and conceallevel for conceal configuration.
 105
 106                                         *clang_complete-exec*
 107                                         *g:clang_exec*
 108 Name or path of clang executable.
 109 Note: Use this if clang has a non-standard name, or isn't in the path.
 110 Default: "clang"
 111
 112                                         *clang_complete-user_options*
 113                                         *g:clang_user_options*
 114 Option added at the end of clang command. Useful if you want to filter the
 115 result, or do other stuffs. To ignore the error code returned by clang, set
 116 |g:clang_exec| to `"clang` and |g:clang_user_options| to `2>/dev/null || exit
 117 0"` if you're on *nix, or `2>NUL || exit 0"` if you are on windows.
 118 Default: ""
 119
 120                                         *clang_complete-auto_user_options*
 121                                         *g:clang_auto_user_options*
 122 Set sources for user options passed to clang. Available sources are:
 123 - path - use &path content as list of include directories (relative paths are
 124   ignored)
 125 - .clang_complete - use information from .clang_complete file Multiple options
 126   are separated by comma.
 127 Default: "path, .clang_complete"
 128
 129                                         *clang_complete-use_library*
 130                                         *g:clang_use_library*
 131 Instead of calling the clang/clang++ tool use libclang directly. This gives
 132 access to many more clang features. Furthermore it automatically caches all
 133 includes in memory. Updates after changes in the same file will therefore be a
 134 lot faster.
 135 Default: 0
 136
 137                                         *clang_complete-library_path*
 138                                         *g:clang_library_path*
 139 If libclang.[dll/so/dylib] is not in your library search path, set this to the
 140 absolute path where libclang is available.
 141 Default: ""
 142
 143                                         *clang_complete-sort_algo*
 144                                         *g:clang_sort_algo*
 145 How results are sorted (alpha, priority). Currently only works with libclang.
 146 Default: "priority"
 147
 148                                         *clang_complete-complete_macros*
 149                                         *g:clang_complete_macros*
 150 If clang should complete preprocessor macros and constants.
 151 Default: 0
 152
 153                                         *clang_complete-complete_patterns*
 154                                         *g:clang_complete_patterns*
 155 If clang should complete code patterns, i.e loop constructs etc.
 156 Defaut: 0
 157
 158 ==============================================================================
 159 5. Known issues                                 *clang_complete-issues*
 160
 161 If you find that completion is slow, please read the |clang_complete-pch|
 162 section below.
 163
 164 If you get following error message while trying to complete anything: >
 165  E121: Undefined variable: b:should_overload
 166 it means that your version of Vim is too old (this is an old bug and it has
 167 been fixed with one of patches for Vim 7.2) and you need to update it.
 168
 169 If clang is not able to compile your file, it cannot complete anything. Since
 170 clang is not supporting every C++0x features, this is normal if it can do any
 171 completion on C++0x file.
 172
 173 There is no difference in clang's output between private methods/members and
 174 public ones. Which means that I cannot filter private methods on the
 175 completion list.
 176
 177 ==============================================================================
 178 6. PCH                                          *clang_complete-pch*
 179
 180 In case you can not or you do not want to install libclang, a precompiled
 181 header file is another way to accelerate compilation, and so, to accelerate
 182 the completion. It is however more complicated to install and is still slower
 183 than the use of libclang.
 184
 185 Here is how to create the <vector> pch, on linux (OSX users may use
 186 -fnext-runtime instead of -fgnu-runtime): >
 187  clang -x c++-header /path/to/c++/vector -fno-exceptions -fgnu-runtime \
 188     -o vector.pch
 189 You just have to insert it into your .clang_complete: >
 190  echo '-include-pch /path/to/vector.pch -fgnu-runtime' >> .clang_complete
 191 <
 192 One of the major problem is that you cannot include more that one pch, the
 193 solution is to put the system headers or non changing headers into another
 194 header and then compile it to pch: >
 195  echo '#include <iostream>\n#include <vector>' > pchheader.h
 196  clang -x c++-header ./pchheader.h -fno-exceptions -fnu-runtime \
 197     -o ./pchheader.pch
 198 And then add it to the .clang_complete file.
 199
 200 ==============================================================================
 201 7. cc_args.py script                            *clang_complete-cc_args*
 202
 203 This script, installed at ~/.vim/bin/cc_args.py, could be used to generate or
 204 update the .clang_complete file. It works similar to gccsence's gccrec and
 205 simply stores -I and -D arguments passed to the compiler in the
 206 .clang_complete file.  Just add the cc_args.py script as the first argument of
 207 the compile command. You should do that every time compile options have
 208 changed.
 209
 210 Example (we need -B flag to force compiling even if project is up to date): >
 211  make CC='~/.vim/bin/cc_args.py gcc' CXX='~/.vim/bin/cc_args.py g++' -B
 212 After running this command, .clang_complete will be created or updated with
 213 new options. If you don't want to update an existing configuration file,
 214 delete it before running make.
 215
 216 ==============================================================================
 217 8. To do                                                *clang_complete-todo*
 218
 219 - Write some unit tests
 220   - clang vs libclang accuracy for complex completions
 221   - clang vs libclang timing
 222 - Explore "jump to declaration/definition" with libclang FGJ
 223 - Think about supertab (<C-X><C-U> with supertab and clang_auto_select)
 224 - Parse fix-its and do something useful with it
 225
 226 ==============================================================================
 227 9. License                                      *clang_complete-license*
 228
 229 Copyright (c) 2010, 2011, Xavier Deguillard
 230 All rights reserved.
 231
 232 Redistribution and use in source and binary forms, with or without
 233 modification, are permitted provided that the following conditions are met:
 234     * Redistributions of source code must retain the above copyright
 235       notice, this list of conditions and the following disclaimer.
 236     * Redistributions in binary form must reproduce the above copyright
 237       notice, this list of conditions and the following disclaimer in the
 238       documentation and/or other materials provided with the distribution.
 239     * Neither the name of Xavier Deguillard nor the
 240       names of its contributors may be used to endorse or promote products
 241       derived from this software without specific prior written permission.
 242
 243 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 244 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 245 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 246 DISCLAIMED. IN NO EVENT SHALL XAVIER DEGUILLARD BE LIABLE FOR ANY
 247 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 248 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 249 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 250 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 251 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 252 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 253
 254 Note: This license does not cover the files that come from the LLVM project,
 255 namely, cindex.py and __init__.py, which are covered by the LLVM license.
 256
 257  vim:tw=78:ts=8:ft=help:norl: