973 lines
46 KiB
Plaintext
973 lines
46 KiB
Plaintext
*youcompleteme.txt* YouCompleteMe: a code-completion engine for Vim
|
|
|
|
===============================================================================
|
|
*youcompleteme-contents*
|
|
Contents ~
|
|
|
|
1. Introduction |youcompleteme-introduction|
|
|
2. Mac OS X super-quick installation |youcompleteme-mac-os-x-super-quick-installation|
|
|
3. Ubuntu Linux x64 super-quick installation |youcompleteme-ubuntu-linux-x64-super-quick-installation|
|
|
4. Full Installation Guide |youcompleteme-full-installation-guide|
|
|
5. User Guide |youcompleteme-user-guide|
|
|
1. General Usage |youcompleteme-general-usage|
|
|
2. Completion string ranking |youcompleteme-completion-string-ranking|
|
|
3. General Semantic Completion Engine Usage |youcompleteme-general-semantic-completion-engine-usage|
|
|
4. C-family Semantic Completion Engine Usage |youcompleteme-c-family-semantic-completion-engine-usage|
|
|
5. Syntastic integration |youcompleteme-syntastic-integration|
|
|
6. Writing New Semantic Completers |youcompleteme-writing-new-semantic-completers|
|
|
6. Commands |youcompleteme-commands|
|
|
1. The |YcmForceCompileAndDiagnostics| command
|
|
2. The |YcmDiags| command
|
|
3. The |YcmShowDetailedDiagnostic| command
|
|
4. The |YcmDebugInfo| command
|
|
7. Options |youcompleteme-options|
|
|
1. The |g:ycm_min_num_of_chars_for_completion| option
|
|
2. The |g:ycm_filetypes_to_completely_ignore| option
|
|
3. The |g:ycm_filetype_specific_completion_to_disable| option
|
|
4. The |g:ycm_allow_changing_updatetime| option
|
|
5. The |g:ycm_complete_in_comments_and_strings| option
|
|
6. The |g:ycm_collect_identifiers_from_comments_and_strings| option
|
|
7. The |g:ycm_add_preview_to_completeopt| option
|
|
8. The |g:ycm_autoclose_preview_window_after_completion| option
|
|
9. The |g:ycm_max_diagnostics_to_display| option
|
|
10. The |g:ycm_key_list_select_completion| option
|
|
11. The |g:ycm_key_list_previous_completion| option
|
|
12. The |g:ycm_key_invoke_completion| option
|
|
13. The |g:ycm_key_detailed_diagnostics| option
|
|
14. The |g:ycm_global_ycm_extra_conf| option
|
|
15. The |g:ycm_semantic_triggers| option
|
|
8. FAQ |youcompleteme-faq|
|
|
1. I get a linker warning regarding |libpython| on Mac when compiling YCM
|
|
2. I get a weird window at the top of my file when I use the semantic engine
|
|
3. It appears that YCM is not working
|
|
4. I cannot get the Syntastic integration to work
|
|
5. Sometimes it takes much longer to get semantic completions than normal
|
|
6. YCM auto-inserts completion strings I don't want!
|
|
7. I get a 'E227: mapping already exists for <blah>' error when I start Vim
|
|
8. I'm trying to use a Homebrew Vim with YCM and I'm getting segfaults
|
|
9. I have a Homebrew Python and/or MacVim; can't compile/SIGABRT when starting
|
|
10. I get 'LONG_BIT definition appears wrong for platform' when compiling
|
|
11. Why isn't YCM just written in plain VimScript, FFS?
|
|
12. Why does YCM demand such a recent version of Vim?
|
|
13. I get annoying messages in Vim's status area when I type
|
|
14. Nasty bugs happen if I have the |vim-autoclose| plugin installed
|
|
9. Contact |youcompleteme-contact|
|
|
10. License |youcompleteme-license|
|
|
|
|
===============================================================================
|
|
*youcompleteme-introduction*
|
|
Introduction ~
|
|
|
|
YouCompleteMe is a fast, as-you-type, fuzzy-search code completion engine for
|
|
Vim. It has several completion engines: an identifier-based engine that works
|
|
with every programming language, a semantic, Clang [1]-based engine that
|
|
provides native semantic code completion for C/C++/Objective-C/Objective-C++
|
|
(from now on referred to as "the C-family languages") and an omnifunc-based
|
|
completer that uses data from Vim's omnicomplete system to provide semantic
|
|
completions for many other languages (Python, Ruby, PHP etc.).
|
|
|
|
YouCompleteMe GIF demo, see reference [2]
|
|
|
|
Here's an explanation of what happens in the short GIF demo above.
|
|
|
|
First, realize that no keyboard shortcuts had to be pressed to get the list of
|
|
completion candidates at any point in the demo. The user just types and the
|
|
suggestions pop up by themselves. If the user doesn't find the completion
|
|
suggestions relevant and/or just wants to type, he can do so; the completion
|
|
engine will not interfere.
|
|
|
|
When the user sees a useful completion string being offered, he presses the
|
|
TAB key to accept it. This inserts the completion string. Repeated presses of
|
|
the TAB key cycle through the offered completions.
|
|
|
|
If the offered completions are not relevant enough, the user can continue
|
|
typing to further filter out unwanted completions.
|
|
|
|
A critical thing to notice is that the completion filtering is NOT based on
|
|
the input being a string prefix of the completion (but that works too). The
|
|
input needs to be a subsequence [3] match of a completion. This is a fancy way
|
|
of saying that any input characters need to be present in a completion string
|
|
in the order in which they appear in the input. So 'abc' is a subsequence of
|
|
'xaybgc', but not of 'xbyxaxxc'. After the filter, a complicated sorting
|
|
system ranks the completion strings so that the most relevant ones rise to the
|
|
top of the menu (so you usually need to press TAB just once).
|
|
|
|
All of the above works with any programming language because of the
|
|
identifier-based completion engine. It collects all of the identifiers in the
|
|
current file and other files you visit and searches them when you type
|
|
(identifiers are put into per-filetype groups).
|
|
|
|
The demo also shows the semantic engine in use. The current semantic engine
|
|
supports only C-family languages. When the user presses '.', '->' or '::'
|
|
while typing in insert mode, the semantic engine is triggered (it can also be
|
|
triggered with a keyboard shortcut; see the rest of the docs).
|
|
|
|
The last thing that you can see in the demo is YCM's integration with
|
|
Syntastic [4] (the little red X that shows up in the left gutter) if you are
|
|
editing a file with semantic engine support. As Clang compiles your file and
|
|
detects warnings or errors, they will be piped to Syntastic for display. You
|
|
don't need to save your file or press any keyboard shortcut to trigger this,
|
|
it "just happens" in the background.
|
|
|
|
In essence, YCM obsoletes the following Vim plugins because it has all of
|
|
their features plus extra:
|
|
|
|
- clang_complete
|
|
|
|
- AutoComplPop
|
|
|
|
- Supertab
|
|
|
|
- neocomplcache
|
|
|
|
===============================================================================
|
|
*youcompleteme-mac-os-x-super-quick-installation*
|
|
Mac OS X super-quick installation ~
|
|
|
|
Please refer to the full Installation Guide below; the following commands are
|
|
provided on a best-effort basis and may not work for you.
|
|
|
|
Install the latest version of MacVim [5]. Yes, MacVim. And yes, the latest.
|
|
|
|
If you don't use the MacVim GUI, it is recommended to use the Vim binary that
|
|
is inside the MacVim.app package ('MacVim.app/Contents/MacOS/Vim'). To ensure
|
|
it works correctly copy the 'mvim' script from the MacVim [5] download to your
|
|
local binary folder (for example '/usr/local/bin/mvim') and then symlink it:
|
|
>
|
|
ln -s /usr/local/bin/mvim vim
|
|
|
|
Install YouCompleteMe with Vundle [6].
|
|
|
|
Remember: YCM is a plugin with a compiled component. If you update YCM using
|
|
Vundle and the ycm_core library API has changed (happens rarely), YCM will
|
|
notify you to recompile it. You should then rerun the install process.
|
|
|
|
It's recommended that you have the latest Xcode installed along with the
|
|
latest Command Line Tools (that you install from within Xcode).
|
|
|
|
Install CMake. Preferably with Homebrew [7], but here's the stand-alone CMake
|
|
installer [8].
|
|
|
|
If you have installed a Homebrew Python and/or Homebrew MacVim, see the FAQ
|
|
for details.
|
|
|
|
Compiling YCM with semantic support for C-family languages:
|
|
>
|
|
cd ~/.vim/bundle/YouCompleteMe
|
|
./install.sh --clang-completer
|
|
|
|
Compiling YCM without semantic support for C-family languages:
|
|
>
|
|
cd ~/.vim/bundle/YouCompleteMe
|
|
./install.sh
|
|
|
|
That's it. You're done. Refer to the User Guide section on how to use YCM.
|
|
Don't forget that if you want the C-family semantic completion engine to work,
|
|
you will need to provide the compilation flags for your project to YCM. It's
|
|
all in the User Guide.
|
|
|
|
YCM comes with sane defaults for its options, but you still may want to take a
|
|
look at what's available for configuration. There are a few interesting
|
|
options that are conservatively turned off by default that you may want to
|
|
turn on.
|
|
|
|
===============================================================================
|
|
*youcompleteme-ubuntu-linux-x64-super-quick-installation*
|
|
Ubuntu Linux x64 super-quick installation ~
|
|
|
|
Please refer to the full Installation Guide below; the following commands are
|
|
provided on a best-effort basis and may not work for you.
|
|
|
|
Make sure you have Vim 7.3.584 with python2 support. At the time of writing,
|
|
the version of Vim shipping with Ubuntu is too old. You may need to compile
|
|
Vim from source [9] (don't worry, it's easy).
|
|
|
|
Install YouCompleteMe with Vundle [6].
|
|
|
|
Remember: YCM is a plugin with a compiled component. If you update YCM using
|
|
Vundle and the ycm_core library API has changed (happens rarely), YCM will
|
|
notify you to recompile it. You should then rerun the install process.
|
|
|
|
Install CMake. 'sudo apt-get install cmake'
|
|
|
|
Make sure you have Python headers installed: 'sudo apt-get install
|
|
python-dev'.
|
|
|
|
Compiling YCM with semantic support for C-family languages:
|
|
>
|
|
cd ~/.vim/bundle/YouCompleteMe
|
|
./install.sh --clang-completer
|
|
|
|
Compiling YCM without semantic support for C-family languages:
|
|
>
|
|
cd ~/.vim/bundle/YouCompleteMe
|
|
./install.sh
|
|
|
|
That's it. You're done. Refer to the User Guide section on how to use YCM.
|
|
Don't forget that if you want the C-family semantic completion engine to work,
|
|
you will need to provide the compilation flags for your project to YCM. It's
|
|
all in the User Guide.
|
|
|
|
YCM comes with sane defaults for its options, but you still may want to take a
|
|
look at what's available for configuration. There are a few interesting
|
|
options that are conservatively turned off by default that you may want to
|
|
turn on.
|
|
|
|
===============================================================================
|
|
*youcompleteme-full-installation-guide*
|
|
Full Installation Guide ~
|
|
|
|
These are the steps necessary to get YCM working on a Unix OS like Linux or
|
|
Mac OS X. My apologies to Windows users, but I don't have a guide for them.
|
|
The code is platform agnostic, so if everything is configured correctly, YCM
|
|
should work on Windows without issues (but as of writing, it's untested on
|
|
that platform).
|
|
|
|
See the FAQ if you have any issues.
|
|
|
|
Remember: YCM is a plugin with a compiled component. If you update YCM using
|
|
Vundle and the ycm_core library API has changed (happens rarely), YCM will
|
|
notify you to recompile it. You should then rerun the install process.
|
|
|
|
Please follow the instructions carefully. Read EVERY WORD.
|
|
|
|
- Ensure that your version of Vim is at least 7.3.584 and that it has support
|
|
for python2 scripting. Inside Vim, type ':version'. Look at the first two
|
|
to three lines of output; it should say 'Vi IMproved 7.3' and then below
|
|
that, 'Included patches: 1-X', where X will be some number. That number
|
|
needs to be 584 or higher. If your version of Vim is not recent enough, you
|
|
may need to compile Vim from source [9] (don't worry, it's easy). After you
|
|
have made sure that you have Vim 7.3.584+, type the following in Vim:
|
|
':echo has('python')'. The output should be 1. If it's 0, then get a
|
|
version of Vim with Python support.
|
|
|
|
- Install YCM with Vundle [6] (or Pathogen [10], but Vundle is a better idea).
|
|
With Vundle, this would mean adding a 'Bundle 'Valloric/YouCompleteMe' line
|
|
to your vimrc [11].
|
|
|
|
- [Complete this step ONLY if you care about semantic completion support for
|
|
C-family languages. Otherwise it's not neccessary.] Download the latest
|
|
version of 'libclang'. Clang is an open-source compiler that can compile
|
|
C/C++/Objective-C/Objective-C++. The 'libclang' library it provides is used
|
|
to power the YCM semantic completion engine for those languages. YCM needs
|
|
libclang version 3.2 or higher. You can use the system libclang only if you
|
|
are sure it is version 3.2 or higher, otherwise don't. Even if it is, I
|
|
recommend using the official binaries from llvm.org [12] if at all
|
|
possible. Make sure you download the correct archive file for your OS.
|
|
|
|
- Compile the 'ycm_core' plugin plugin (ha!) that YCM needs. This is the C++
|
|
engine that YCM uses to get fast completions. You will need to have 'cmake'
|
|
installed in order to generate the required makefiles. Linux users can
|
|
install cmake with their package manager ('sudo apt-get install cmake' for
|
|
Ubuntu) whereas other users can download and install [8] cmake from its
|
|
project site. Mac users can also get it through Homebrew [7] with 'brew
|
|
install cmake'. You also need to make sure you have Python headers
|
|
installed. On a Debian-like Linux distro, this would be 'sudo apt-get
|
|
install python-dev'. On Mac they should already be present. Here we'll
|
|
assume you installed YCM with Vundle. That means that the top-level YCM
|
|
directory is in '~/.vim/bundle/YouCompleteMe'. We'll create a new folder
|
|
where build files will be placed. Run the following: cd ~ mkdir ycm_build
|
|
cd ycm_build Now we need to generate the makefiles. If you DON'T care about
|
|
semantic support for C-family languages, run the following command in the
|
|
'ycm_build' directory: 'cmake -G "Unix Makefiles" . ~/.vim/bundle/YouCompleteMe/cpp'
|
|
If you DO care about semantic support for C-family languages, then your
|
|
'cmake' call will be a bit more complicated. We'll assume you downloaded a
|
|
binary distribution of LLVM+Clang from llvm.org in step 3 and that you
|
|
extracted the archive file to folder '~/ycm_temp/llvm_root_dir' (with
|
|
'bin', 'lib', 'include' etc. folders right inside that folder). With that
|
|
in mind, run the following command in the 'ycm_build' directory: 'cmake -G
|
|
"Unix Makefiles" -DPATH_TO_LLVM_ROOT=~/ycm_temp/llvm_root_dir .
|
|
~/.vim/bundle/YouCompleteMe/cpp' Now that makefiles have been generated,
|
|
simply run 'make ycm_core'. For those who want to use the system version of
|
|
libclang, you would pass '-DUSE_SYSTEM_LIBCLANG=ON' to cmake instead of the
|
|
'-DPATH_TO_LLVM_ROOT=...' flag. You could also force the use of a custom
|
|
libclang library with '-DEXTERNAL_LIBCLANG_PATH=/path/to/libclang.so' flag
|
|
(the library would end with '.dylib' on a Mac). Again, this flag would be
|
|
used instead of the other flags.
|
|
|
|
- [Complete this step ONLY if you care about semantic completion support for
|
|
C-family languages. Otherwise it's not neccessary.] Copy the libclang
|
|
library file into the 'YouCompleteMe/python' folder. The library file is
|
|
'libclang.so' on Linux and 'libclang.dylib' on Mac. We'll assume you
|
|
downloaded a binary distribution of LLVM+Clang from llvm.org in step 3 and
|
|
that you extracted the archive file to folder '~/ycm_temp/llvm_root_dir'
|
|
(with 'bin', 'lib', 'include' etc. folders right inside that folder). We'll
|
|
also assume you installed YCM with Vundle. That means that the top-level
|
|
YCM directory is in '~/.vim/bundle/YouCompleteMe'. On Linux, run: 'cp
|
|
~/ycm_temp/llvm_root_dir/lib/libclang.so ~/.vim/bundle/YouCompleteMe/python'
|
|
On Mac, run: 'cp ~/ycm_temp/llvm_root_dir/lib/libclang.dylib
|
|
~/.vim/bundle/YouCompleteMe/python' DO NOT FORGET THIS STEP. If you forget
|
|
to copy over 'libclang.so' version 3.2 into the 'YouCompleteMe/python'
|
|
folder then YCM will not work if you selected C-family support during YCM
|
|
compilation.
|
|
|
|
That's it. You're done. Refer to the User Guide section on how to use YCM.
|
|
Don't forget that if you want the C-family semantic completion engine to work,
|
|
you will need to provide the compilation flags for your project to YCM. It's
|
|
all in the User Guide.
|
|
|
|
YCM comes with sane defaults for its options, but you still may want to take a
|
|
look at what's available for configuration. There are a few interesting
|
|
options that are conservatively turned off by default that you may want to
|
|
turn on.
|
|
|
|
===============================================================================
|
|
*youcompleteme-user-guide*
|
|
User Guide ~
|
|
|
|
-------------------------------------------------------------------------------
|
|
*youcompleteme-general-usage*
|
|
General Usage ~
|
|
|
|
- If the offered completions are too broad, keep typing characters; YCM will
|
|
continue refining the offered completions based on your input.
|
|
|
|
- Use the TAB key to accept a completion and continue pressing TAB to cycle
|
|
through the completions. Use Shift-TAB to cycle backwards. Note that if
|
|
you're using console Vim (that is, not Gvim or MacVim) then it's likely
|
|
that the Shift-TAB binding will not work because the console will not pass
|
|
it to Vim. You can remap the keys; see the options section below.
|
|
|
|
-------------------------------------------------------------------------------
|
|
*youcompleteme-completion-string-ranking*
|
|
Completion string ranking ~
|
|
|
|
The subsequence filter removes any completions that do not match the input,
|
|
but then the sorting system kicks in. It's actually very complicated and uses
|
|
lots of factors, but suffice it to say that "word boundary" (WB) subsequence
|
|
character matches are "worth" more than non-WB matches. In effect, this means
|
|
given an input of "gua", the completion "getUserAccount" would be ranked
|
|
higher in the list than the "Fooguxa" completion (both of which are
|
|
subsequence matches). A word-boundary character are all capital characters,
|
|
characters preceded by an underscore and the first letter character in the
|
|
completion string.
|
|
|
|
-------------------------------------------------------------------------------
|
|
*youcompleteme-general-semantic-completion-engine-usage*
|
|
General Semantic Completion Engine Usage ~
|
|
|
|
- You can use Ctrl+Space to trigger the completion suggestions anywhere, even
|
|
without a string prefix. This is useful to see which top-level functions
|
|
are available for use.
|
|
|
|
-------------------------------------------------------------------------------
|
|
*youcompleteme-c-family-semantic-completion-engine-usage*
|
|
C-family Semantic Completion Engine Usage ~
|
|
|
|
- You really also want to install the latest version of the Syntastic [4] Vim
|
|
plugin. It has support for YCM and together they will provide you with
|
|
compile errors/warnings practically instantly and without saving the file.
|
|
|
|
YCM looks for a '.ycm_extra_conf.py' file in the directory of the opened file
|
|
or in any directory above it in the hierarchy (recursively); when the file is
|
|
found, it is loaded (only once!) as a Python module. YCM calls a
|
|
'FlagsForFile' method in that module which should provide it with the
|
|
information necessary to compile the current file. (You can also provide a
|
|
path to a global '.ycm_extra_conf.py' file and override this searching
|
|
behavior. See the Options section for more details.)
|
|
|
|
This system was designed this way so that the user can perform any arbitrary
|
|
sequence of operations to produce a list of compilation flags YCM should hand
|
|
to Clang.
|
|
|
|
See YCM's own '.ycm_extra_conf.py' [13] for details on how this works. You
|
|
should be able to use it as a starting point. Hint: just replace the strings
|
|
in the 'flags' variable with compilation flags necessary for your project.
|
|
That should be enough for 99% of projects.
|
|
|
|
Yes, Clang's 'CompilationDatabase' system [14] is also supported. Again, see
|
|
the above linked example file.
|
|
|
|
If Clang encounters errors when compiling the header files that your file
|
|
includes, then it's probably going to take a long time to get completions.
|
|
When the completion menu finally appears, it's going to have a large number of
|
|
unrelated completion strings (type/function names that are not actually
|
|
members). This is because Clang fails to build a precompiled preamble for your
|
|
file if there are any errors in the included headers and that preamble is key
|
|
to getting fast completions.
|
|
|
|
Call the ':YcmDiags' command to see if any errors or warnings were detected in
|
|
your file. Even better, use Syntastic.
|
|
|
|
-------------------------------------------------------------------------------
|
|
*youcompleteme-syntastic-integration*
|
|
Syntastic integration ~
|
|
|
|
YCM has explicit support for Syntastic [4] (and vice-versa) if you compiled
|
|
YCM with Clang support; this means that any diagnostics (errors or warnings)
|
|
that Clang encounters while compiling your file will be fed back to Syntastic
|
|
for display.
|
|
|
|
YCM will recompile your file in the background 'updatetime' (see ':h
|
|
updatetime' in Vim) milliseconds after you stop typing (to be specific, on
|
|
'CursorHold' and 'CursorHoldI' Vim events). YCM will change your 'updatetime'
|
|
value to be '2000' milliseconds (there's an option to tell it not to do this
|
|
if you wish).
|
|
|
|
The new diagnostics (if any) will be fed back to Syntastic the next time you
|
|
press any key on the keyboard. So if you stop typing and just wait for the new
|
|
diagnostics to come in, that will not work. You need to press some key for the
|
|
GUI to update.
|
|
|
|
Having to press a key to get the updates is unfortunate, but cannot be changed
|
|
due to the way Vim internals operate; there is no way that a background task
|
|
can update Vim's GUI after it has finished running. You have to press a key.
|
|
This will make YCM check for any pending diagnostics updates.
|
|
|
|
You can force a full, blocking compilation cycle with the ':YcmForceCompileAndDiagnostics'
|
|
command (you may want to map that command to a key; try putting 'nnoremap <F5>
|
|
:YcmForceCompileAndDiagnostics<CR>' in your vimrc). Calling this command will
|
|
force YCM to immediately recompile your file and display any new diagnostics
|
|
it encounters. Do note that recompilation with this command may take a while
|
|
and during this time the Vim GUI will be blocked.
|
|
|
|
After the errors are displayed by Syntastic, it will display a short
|
|
diagnostic message when you move your cursor to the line with the error. You
|
|
can get a detailed diagnostic message with the '<leader>d' key mapping (can be
|
|
changed in the options) YCM provides when your cursor is on the line with the
|
|
diagnostic.
|
|
|
|
You can also see the full diagnostic message for all the diagnostics in the
|
|
current file in Vim's 'locationlist', which can be opened with the ':lopen'
|
|
and ':lclose' commands. A good way to toggle the display of the 'locationlist'
|
|
with a single key mapping is provided by another (very small) Vim plugin
|
|
called ListToggle [15] (which also makes it possible to change the height of
|
|
the 'locationlist' window), also written by yours truly.
|
|
|
|
-------------------------------------------------------------------------------
|
|
*youcompleteme-writing-new-semantic-completers*
|
|
Writing New Semantic Completers ~
|
|
|
|
You have two options here: writing an 'omnifunc' for Vim's omnicomplete system
|
|
that YCM will then use through its omni-completer, or a custom completer for
|
|
YCM using the Completer API [16].
|
|
|
|
Here are the differences between the two approaches:
|
|
|
|
- You have to use VimScript to write the omnifunc, but get to use Python to
|
|
write for the Completer API; this by itself should make you want to use the
|
|
API.
|
|
|
|
- The Completer API is a much more powerful way to integrate with YCM and it
|
|
provides a wider set of features. For instance, you can make your Completer
|
|
query your semantic back-end in an asynchronous fashion, thus not blocking
|
|
Vim's GUI thread while your completion system is processing stuff. This is
|
|
impossible with VimScript. All of YCM's completers use the Completer API.
|
|
|
|
- Performance with the Completer API is better since Python executes faster
|
|
than VimScript.
|
|
|
|
If you want to use the 'omnifunc' system, see the relevant Vim docs with ':h
|
|
complete-functions'. For the Completer API, see the API docs [16].
|
|
|
|
If you want to upstream your completer into YCM's source, you should use the
|
|
Completer API.
|
|
|
|
===============================================================================
|
|
*youcompleteme-commands*
|
|
Commands ~
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *YcmForceCompileAndDiagnostics* command
|
|
|
|
Calling this command will force YCM to immediately recompile your file and
|
|
display any new diagnostics it encounters. Do note that recompilation with
|
|
this command may take a while and during this time the Vim GUI will be
|
|
blocked.
|
|
|
|
You may want to map this command to a key; try putting 'nnoremap <F5>
|
|
:YcmForceCompileAndDiagnostics<CR>' in your vimrc.
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *YcmDiags* command
|
|
|
|
Calling this command will fill Vim's 'locationlist' with errors or warnings if
|
|
any were detected in your file and then open it.
|
|
|
|
A better option would be to use Syntastic which will keep your 'locationlist'
|
|
up to date automatically and will also show error/warning notifications in
|
|
Vim's gutter.
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *YcmShowDetailedDiagnostic* command
|
|
|
|
This command shows the full diagnostic text when the user's cursor is on the
|
|
line with the diagnostic.
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *YcmDebugInfo* command
|
|
|
|
This will print out various debug information for the current file. Useful to
|
|
see what compile commands will be used for the file if you're using the
|
|
semantic completion engine.
|
|
|
|
===============================================================================
|
|
*youcompleteme-options*
|
|
Options ~
|
|
|
|
All options have reasonable defaults so if the plug-in works after
|
|
installation you don't need to change any options. These options can be
|
|
configured in your vimrc script [11] by including a line like this:
|
|
>
|
|
let g:ycm_min_num_of_chars_for_completion = 1
|
|
|
|
Note that after changing an option in your vimrc script [11] you have to
|
|
restart Vim for the changes to take effect.
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_min_num_of_chars_for_completion* option
|
|
|
|
This option controls the number of characters the user needs to type before
|
|
completion suggestions are triggered. For example, if the option is set to
|
|
'2', then when the user types a second alphanumeric character after a
|
|
whitespace character, completion suggestions will be triggered.
|
|
|
|
Default: '2'
|
|
>
|
|
let g:ycm_min_num_of_chars_for_completion = 2
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_filetypes_to_completely_ignore* option
|
|
|
|
This option controls for which Vim filetypes (see ':h filetype') should YCM be
|
|
turned off. The option value should be a Vim dictionary with keys being
|
|
filetype strings (like 'python', 'cpp' etc) and values being unimportant (the
|
|
dictionary is used like a hash set, meaning that only the keys matter). The
|
|
listed filetypes will be completely ignored by YCM, meaning that neither the
|
|
identifier-based completion engine nor the semantic engine will operate in
|
|
files of those filetypes.
|
|
|
|
You can get the filetype of the current file in Vim with ':set ft?'.
|
|
|
|
Default: '{notes: 1, markdown: 1, text: 1}'
|
|
>
|
|
let g:ycm_filetypes_to_completely_ignore = {
|
|
\ 'notes' : 1,
|
|
\ 'markdown' : 1,
|
|
\ 'text' : 1,
|
|
\}
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_filetype_specific_completion_to_disable* option
|
|
|
|
This option controls for which Vim filetypes (see ':h filetype') should the
|
|
YCM semantic completion engine be turned off. The option value should be a Vim
|
|
dictionary with keys being filetype strings (like 'python', 'cpp' etc) and
|
|
values being unimportant (the dictionary is used like a hash set, meaning that
|
|
only the keys matter). The listed filetypes will be ignored by the YCM
|
|
semantic completion engine, but the identifier-based completion engine will
|
|
still trigger in files of those filetypes.
|
|
|
|
Note that even if semantic completion is not turned off for a specific
|
|
filetype, you will not get semantic completion if the semantic engine does not
|
|
support that filetype. Currently, the semantic engine only supports the 'c',
|
|
'cpp', 'objc' and 'objcpp' filetypes.
|
|
|
|
You can get the filetype of the current file in Vim with ':set ft?'.
|
|
|
|
Default: '{}'
|
|
>
|
|
let g:ycm_filetype_specific_completion_to_disable = {}
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_allow_changing_updatetime* option
|
|
|
|
When this option is set to '1', YCM will change the 'updatetime' Vim option to
|
|
'2000' (see ':h updatetime'). This may conflict with some other plugins you
|
|
have (but it's unlikely). The 'updatetime' option is the number of
|
|
milliseconds that have to pass before Vim's 'CursorHold' (see ':h CursorHold')
|
|
event fires. YCM runs the completion engines' "file comprehension" systems in
|
|
the background on every such event; the identifier-based engine collects the
|
|
identifiers whereas the semantic engine compiles the file to build an AST.
|
|
|
|
The Vim default of '4000' for 'updatetime' is a bit long, so YCM reduces this.
|
|
Set this option to '0' to force YCM to leave your 'updatetime' setting alone.
|
|
|
|
Default: '1'
|
|
>
|
|
let g:ycm_allow_changing_updatetime = 1
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_complete_in_comments_and_strings* option
|
|
|
|
When this option is set to '1', YCM will show the completion menu even when
|
|
typing inside strings and comments.
|
|
|
|
Default: '0'
|
|
>
|
|
let g:ycm_complete_in_comments_and_strings = 0
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_collect_identifiers_from_comments_and_strings* option
|
|
|
|
When this option is set to '1', YCM's identifier completer will also collect
|
|
identifiers from strings and comments. Otherwise, the text in comments and
|
|
strings will be ignored.
|
|
|
|
Default: '0'
|
|
>
|
|
let g:ycm_collect_identifiers_from_comments_and_strings = 0
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_add_preview_to_completeopt* option
|
|
|
|
When this option is set to '1', YCM will add the 'preview' string to Vim's
|
|
'completeopt' option (see ':h completeopt'). If your 'completeopt' option
|
|
already has 'preview' set, there will be no effect. You can see the current
|
|
state of your 'completeopt' setting with ':set completeopt?' (yes, the
|
|
question mark is important).
|
|
|
|
When 'preview' is present in 'completeopt', YCM will use the 'preview' window
|
|
at the top of the file to store detailed information about the current
|
|
completion candidate (but only if the candidate came from the semantic
|
|
engine). For instance, it would show the full function prototype and all the
|
|
function overloads in the window if the current completion is a function name.
|
|
|
|
Default: '0'
|
|
>
|
|
let g:ycm_add_preview_to_completeopt = 0
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_autoclose_preview_window_after_completion* option
|
|
|
|
When this option is set to '1', YCM will auto-close the 'preview' window after
|
|
the user accepts the offered completion string. If there is no 'preview'
|
|
window triggered because there is no 'preview' string in 'completeopt', this
|
|
option is irrelevant. See the |g:ycm_add_preview_to_completeopt| option for
|
|
more details.
|
|
|
|
Default: '0'
|
|
>
|
|
let g:ycm_autoclose_preview_window_after_completion = 0
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_max_diagnostics_to_display* option
|
|
|
|
This option controls the maximum number of diagnostics shown to the user when
|
|
errors or warnings are detected in the file. This option is only relevant if
|
|
you are using the semantic completion engine and have installed the version of
|
|
the Syntastic plugin that supports YCM.
|
|
|
|
Default: '30'
|
|
>
|
|
let g:ycm_max_diagnostics_to_display = 30
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_key_list_select_completion* option
|
|
|
|
This option controls the key mappings used to select the first completion
|
|
string. Invoking any of them repeatedly cycles forward through the completion
|
|
list.
|
|
|
|
Some users like adding '<Enter>' to this list.
|
|
|
|
Default: '['<TAB>', '<Down>']'
|
|
>
|
|
let g:ycm_key_list_select_completion = ['<TAB>', '<Down>']
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_key_list_previous_completion* option
|
|
|
|
This option controls the key mappings used to select the previous completion
|
|
string. Invoking any of them repeatedly cycles backwards through the
|
|
completion list.
|
|
|
|
Note that one of the defaults is '<S-TAB>' which means Shift-TAB. That mapping
|
|
will probably only work in GUI Vim (Gvim or MacVim) and not in plain console
|
|
Vim because the terminal usually does not forward modifier key combinations to
|
|
Vim.
|
|
|
|
Default: '['<S-TAB>', '<Up>']'
|
|
>
|
|
let g:ycm_key_list_previous_completion = ['<S-TAB>', '<Up>']
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_key_invoke_completion* option
|
|
|
|
This option controls the key mapping used to invoke the completion menu for
|
|
semantic completion. By default, semantic completion is trigged automatically
|
|
after typing '.', '->' and '::' in insert mode (if semantic completion support
|
|
has been compiled in). This key mapping can be used to trigger semantic
|
|
completion anywhere. Useful for searching for top-level functions and classes.
|
|
|
|
Note that the default of '<C-Space>' means Ctrl-Space. Also note that the
|
|
default mapping will probably only work in GUI Vim (Gvim or MacVim) and not in
|
|
plain console Vim because the terminal usually does not forward modifier key
|
|
combinations to Vim.
|
|
|
|
Setting this option to an empty string will make sure no mapping is created.
|
|
|
|
Default: '<C-Space>'
|
|
>
|
|
let g:ycm_key_invoke_completion = '<C-Space>'
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_key_detailed_diagnostics* option
|
|
|
|
This option controls the key mapping used to show the full diagnostic text
|
|
when the user's cursor is on the line with the diagnostic. It basically calls
|
|
':YcmShowDetailedDiagnostic'.
|
|
|
|
Setting this option to an empty string will make sure no mapping is created.
|
|
|
|
Default: '<leader>d'
|
|
>
|
|
let g:ycm_key_detailed_diagnostics = '<leader>d'
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_global_ycm_extra_conf* option
|
|
|
|
Normally, YCM searches for a '.ycm_extra_conf.py' file for compilation flags
|
|
(see the User Guide for more details on how this works). You can use this
|
|
option to override this searching behavior by providing a full, absolute path
|
|
to a global '.ycm_extra_conf.py' file (although you can call the global file
|
|
whatever you want).
|
|
|
|
You can place such a global file anywhere in your filesystem.
|
|
|
|
Default: ''
|
|
>
|
|
let g:ycm_global_ycm_extra_conf = ''
|
|
|
|
-------------------------------------------------------------------------------
|
|
The *g:ycm_semantic_triggers* option
|
|
|
|
This option controls the character-based triggers for the various semantic
|
|
completion engines. The option holds a dictionary of key-values, where the
|
|
keys are Vim's filetype strings delimited by commas and values are lists of
|
|
strings, where the strings are the triggers.
|
|
|
|
A "trigger" is a sequence of one or more characters that trigger semantic
|
|
completion when typed. For instance, C++ ('cpp' filetype) has '.' listed as a
|
|
trigger. So when the user types 'foo.', the semantic engine will trigger and
|
|
serve 'foo''s list of member functions and variables. Since C++ also has '->'
|
|
listed as a trigger, the same thing would happen when the user typed 'foo->'.
|
|
|
|
Default: '[see next line]'
|
|
>
|
|
let g:ycm_semantic_triggers = {
|
|
\ 'c' : ['->', '.'],
|
|
\ 'objc' : ['->', '.'],
|
|
\ 'cpp,objcpp' : ['->', '.', '::'],
|
|
\ 'perl,php' : ['->'],
|
|
\ 'cs,java,javascript,d,vim,ruby,python,perl6,scala,vb,elixir' : ['.'],
|
|
\ 'lua' : ['.', ':'],
|
|
\ 'erlang' : [':'],
|
|
}
|
|
|
|
===============================================================================
|
|
*youcompleteme-faq*
|
|
FAQ ~
|
|
|
|
-------------------------------------------------------------------------------
|
|
I get a linker warning regarding *libpython* on Mac when compiling YCM
|
|
|
|
If the warning is 'ld: warning: path '/usr/lib/libpython2.7.dylib' following
|
|
-L not a directory', then feel free to ignore it; it's caused by a limitation
|
|
of CMake and is not an issue. Everything should still work fine.
|
|
|
|
-------------------------------------------------------------------------------
|
|
I get a weird window at the top of my file when I use the semantic engine ~
|
|
|
|
This is Vim's 'preview' window. Vim uses it to show you extra information
|
|
about something if such information is available. YCM provides Vim with such
|
|
extra information. For instance, when you select a function in the completion
|
|
list, the 'preview' window will hold that function's prototype and the
|
|
prototypes of any overloads of the function. It will stay there after you
|
|
select the completion so that you can use the information about the parameters
|
|
and their types to write the function call.
|
|
|
|
If you would like this window to auto-close after you select a completion
|
|
string, set the |g:ycm_autoclose_preview_window_after_completion| option to
|
|
'1' in your 'vimrc' file.
|
|
|
|
If you don't want this window to ever show up, add 'set completeopt-=preview'
|
|
to your 'vimrc'. Also make sure that the |g:ycm_add_preview_to_completeopt|
|
|
option is set to '0'.
|
|
|
|
-------------------------------------------------------------------------------
|
|
It appears that YCM is not working ~
|
|
|
|
In Vim, run ':messages' and carefully read the output. YCM will echo messages
|
|
to the message log if it encounters problems. It's likely you misconfigured
|
|
something and YCM is complaining about it.
|
|
|
|
Also, you may want to run the ':YcmDebugInfo' command; it will make YCM spew
|
|
out various debugging information, including the compile flags for the file if
|
|
the file is a C-family language file and you have compiled in Clang support.
|
|
|
|
-------------------------------------------------------------------------------
|
|
I cannot get the Syntastic integration to work ~
|
|
|
|
Try to update your version of Syntastic. At the time of writing (Jan 2013),
|
|
the YCM integration is very recent and it's likely that your version of
|
|
Syntastic does not have it.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Sometimes it takes much longer to get semantic completions than normal ~
|
|
|
|
This means that libclang (which YCM uses for C-family semantic completion)
|
|
failed to pre-compile your file's preamble. In other words, there was an error
|
|
compiling some of the source code you pulled in through your header files. I
|
|
suggest calling the ':YcmDiags' command to see what they were (even better,
|
|
have Syntastic installed and call ':lopen').
|
|
|
|
Bottom line, if libclang can't pre-compile your file's preamble because there
|
|
were errors in it, you're going to get slow completions because there's no AST
|
|
cache.
|
|
|
|
-------------------------------------------------------------------------------
|
|
YCM auto-inserts completion strings I don't want! ~
|
|
|
|
This means you probably have some mappings that interfere with YCM's internal
|
|
ones. Make sure you don't have something mapped to '<C-p>', '<C-x>' or '<C-u>'
|
|
(in insert mode).
|
|
|
|
YCM never selects something for you; it just shows you a menu and the user has
|
|
to explicitly select something. If something is being selected automatically,
|
|
this means there's a bug or a misconfiguration somewhere.
|
|
|
|
-------------------------------------------------------------------------------
|
|
I get a 'E227: mapping already exists for <blah>' error when I start Vim ~
|
|
|
|
This means that YCM tried to set up a key mapping but failed because you
|
|
already had something mapped to that key combination. The '<blah>' part of the
|
|
message will tell you what was the key combination that failed.
|
|
|
|
Look in the options section and see if which of the default mappings conflict
|
|
with your own. Then change that option value to something else so that the
|
|
conflict goes away.
|
|
|
|
-------------------------------------------------------------------------------
|
|
I'm trying to use a Homebrew Vim with YCM and I'm getting segfaults ~
|
|
|
|
Something (I don't know what) is wrong with the way that Homebrew configures
|
|
and builds Vim. I recommend using MacVim [5]. Even if you don't like the
|
|
MacVim GUI, you can use the Vim binary that is inside the MacVim.app package
|
|
(it's 'MacVim.app/Contents/MacOS/Vim') and get the Vim console experience.
|
|
|
|
-------------------------------------------------------------------------------
|
|
I have a Homebrew Python and/or MacVim; can't compile/SIGABRT when starting ~
|
|
|
|
You should probably run 'brew rm python; brew install python' to get the
|
|
latest fixes that should make YCM work with such a configuration. Also rebuild
|
|
Macvim then. If you still get problems with this, see issue #18 [17] for
|
|
suggestions.
|
|
|
|
-------------------------------------------------------------------------------
|
|
I get 'LONG_BIT definition appears wrong for platform' when compiling ~
|
|
|
|
Look at the output of your CMake call. There should be a line in it like the
|
|
following (with '.dylib' in place of '.so' on a Mac):
|
|
|
|
'-- Found PythonLibs: /usr/lib/libpython2.7.so (Required is at least version
|
|
"2.5")'
|
|
|
|
That would be the correct output. An example of incorrect output would be the
|
|
following:
|
|
|
|
'-- Found PythonLibs: /usr/lib/libpython2.7.so (found suitable version
|
|
"2.5.1", minimum required is "2.5")'
|
|
|
|
Notice how there's an extra bit of output there, the 'found suitable version
|
|
"<version>"' part, where '<version>' is not the same as the version of the
|
|
dynamic library. In the example shown, the library is version 2.7 but the
|
|
second string is version '2.5.1'.
|
|
|
|
This means that CMake found one version of Python headers and a different
|
|
version for the library. This is wrong. It can happen when you have multiple
|
|
versions of Python installed on your machine.
|
|
|
|
You should probably add the following flags to your cmake call (again, 'dylib'
|
|
instead of 'so' on a Mac):
|
|
|
|
'-DPYTHON_INCLUDE_DIR=/usr/include/python2.7 -DPYTHON_LIBRARY=/usr/lib/libpython2.7.so'
|
|
|
|
This will force the paths to the Python include directory and the Python
|
|
library to use. You may need to set these flags to something else, but you
|
|
need to make sure you use the same version of Python that your Vim binary is
|
|
built against, which is highly likely to be the system's default Python.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Why isn't YCM just written in plain VimScript, FFS? ~
|
|
|
|
Because of the identifier completion engine and subsequence-based filtering.
|
|
Let's say you have many dozens of files open in a single Vim instance (I often
|
|
do); the identifier-based engine then needs to store thousands (if not tens of
|
|
thousands) of identifiers in its internal data-structures. When the user
|
|
types, YCM needs to perform subsequence-based filtering on all of those
|
|
identifiers (every single one!) in less than 10 milliseconds.
|
|
|
|
I'm sorry, but that level of performance is just plain impossible to achieve
|
|
with VimScript. I've tried, and the language is just too slow. No, you can't
|
|
get acceptable performance even if you limit yourself to just the identifiers
|
|
in the current file and simple prefix-based fitering.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Why does YCM demand such a recent version of Vim? ~
|
|
|
|
During YCM's development several show-stopper bugs where encountered in Vim.
|
|
Those needed to be fixed upstream (and were). A few months after those bugs
|
|
were fixed, Vim trunk landed the 'pyeval()' function which improved YCM
|
|
performance even more since less time was spent serializing and deserializing
|
|
data between Vim and the embedded Python interpreter. A few critical bugfixes
|
|
for 'pyeval()' landed in Vim 7.3.584 (and a few commits before that).
|
|
|
|
-------------------------------------------------------------------------------
|
|
I get annoying messages in Vim's status area when I type ~
|
|
|
|
If you're referring to the 'User defined completion <bla bla> back at
|
|
original' and similar, then sadly there's no fix for those. Vim will emit them
|
|
no matter how hard I try to silence them.
|
|
|
|
You'll have to learn to ignore them. It's a shitty "solution", I know.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Nasty bugs happen if I have the *vim-autoclose* plugin installed
|
|
|
|
Use the delimitMate [18] plugin instead. It does the same thing without
|
|
conflicting with YCM.
|
|
|
|
===============================================================================
|
|
*youcompleteme-contact*
|
|
Contact ~
|
|
|
|
If you have questions, bug reports, suggestions, etc. please use the issue
|
|
tracker [19]. The latest version is available at http://valloric.github.com/YouCompleteMe/.
|
|
|
|
The author's homepage is http://val.markovic.io.
|
|
|
|
===============================================================================
|
|
*youcompleteme-license*
|
|
License ~
|
|
|
|
This software is licensed under the GPL v3 license [20]. Copyright 2012
|
|
Strahinja Val Markovic <val@markovic.io>.
|
|
|
|
===============================================================================
|
|
*youcompleteme-references*
|
|
References ~
|
|
|
|
[1] http://clang.llvm.org/
|
|
[2] http://i.imgur.com/0OP4ood.gif
|
|
[3] http://en.wikipedia.org/wiki/Subsequence
|
|
[4] https://github.com/scrooloose/syntastic
|
|
[5] http://code.google.com/p/macvim/#Download
|
|
[6] https://github.com/gmarik/vundle#about
|
|
[7] http://mxcl.github.com/homebrew/
|
|
[8] http://www.cmake.org/cmake/resources/software.html
|
|
[9] https://github.com/Valloric/YouCompleteMe/wiki/Building-Vim-from-source
|
|
[10] https://github.com/tpope/vim-pathogen#pathogenvim
|
|
[11] http://vimhelp.appspot.com/starting.txt.html#vimrc
|
|
[12] http://llvm.org/releases/download.html#3.2
|
|
[13] https://github.com/Valloric/YouCompleteMe/blob/master/cpp/ycm/.ycm_extra_conf.py
|
|
[14] http://clang.llvm.org/docs/JSONCompilationDatabase.html
|
|
[15] https://github.com/Valloric/ListToggle
|
|
[16] https://github.com/Valloric/YouCompleteMe/blob/master/python/completers/completer.py
|
|
[17] https://github.com/Valloric/YouCompleteMe/issues/18
|
|
[18] https://github.com/Raimondi/delimitMate
|
|
[19] https://github.com/Valloric/YouCompleteMe/issues?state=open
|
|
[20] http://www.gnu.org/copyleft/gpl.html
|
|
|
|
vim: ft=help
|