vim/YouCompleteMe
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Auto merge of #3088 - micbou:settings-docs, r=micbou

Browse Source 
[READY] Update C-family documentation

Update documentation to reflect the changes introduced by PRs https://github.com/Valloric/ycmd/pull/1035 and https://github.com/Valloric/ycmd/pull/1057.

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/valloric/youcompleteme/3088)
<!-- Reviewable:end -->
This commit is contained in:
zzbot 2018-07-25 11:49:35 -07:00 committed by GitHub
commit f379ec103f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 68 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@ -998,9 +998,8 @@ documentation][compdb]. In short:
[`.ycm_extra_conf.py`](#option-2-provide-the-flags-manually) below. [`.ycm_extra_conf.py`](#option-2-provide-the-flags-manually) below.
If no [`.ycm_extra_conf.py`](#option-2-provide-the-flags-manually) is found, If no [`.ycm_extra_conf.py`](#option-2-provide-the-flags-manually) is found,
and no [`ycm_global_ycm_extra_conf`](#the-gycm_global_ycm_extra_conf-option) is YouCompleteMe automatically tries to load a compilation database if there is
configured, YouCompleteMe automatically tries to load a compilation database if one.
one is found.
YCM looks for a file named `compile_commands.json` in the directory of the YCM looks for a file named `compile_commands.json` in the directory of the
opened file or in any directory above it in the hierarchy (recursively); when opened file or in any directory above it in the hierarchy (recursively); when
@ -1027,7 +1026,7 @@ directory.
If you don't have a compilation database, or aren't able to generate one, If you don't have a compilation database, or aren't able to generate one,
you have to tell YouCompleteMe how to compile your code some other way. you have to tell YouCompleteMe how to compile your code some other way.
Every c-family project is different. It is not possible for YCM to guess what Every C-family project is different. It is not possible for YCM to guess what
compiler flags to supply for your project. Fortunately, YCM provides a mechanism compiler flags to supply for your project. Fortunately, YCM provides a mechanism
for you to generate the flags for a particular file with _arbitrary complexity_. for you to generate the flags for a particular file with _arbitrary complexity_.
This is achieved by requiring you to provide a Python module which implements a This is achieved by requiring you to provide a Python module which implements a
@ -1036,13 +1035,17 @@ compiler flags to use to compile that file.
YCM looks for a `.ycm_extra_conf.py` file in the directory of the opened file or 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 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` found, it is loaded (only once!) as a Python module. YCM calls a `Settings`
method in that module which should provide it with the information necessary to 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 compile the current file. You can also provide a path to a global configuration
`.ycm_extra_conf.py` file, which will be used as a fallback. To prevent the file with the
execution of malicious code from a file you didn't write YCM will ask you once [`g:ycm_global_ycm_extra_conf`](#the-gycm_global_ycm_extra_conf-option) option,
per `.ycm_extra_conf.py` if it is safe to load. This can be disabled and you can which will be used as a fallback. To prevent the execution of malicious code
white-/blacklist files. See the _Options_ section for more details. from a file you didn't write YCM will ask you once per `.ycm_extra_conf.py` if
it is safe to load. This can be disabled and you can white-/blacklist files. See
the [`g:ycm_confirm_extra_conf`](#the-gycm_confirm_extra_conf-option) and
[`g:ycm_extra_conf_globlist`](#the-gycm_extra_conf_globlist-option) options
respectively.
This system was designed this way so that the user can perform any arbitrary 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 sequence of operations to produce a list of compilation flags YCM should hand
@ -1053,25 +1056,25 @@ This is so that the correct language is detected, particularly for header files.
Common values are `-x c` for C, `-x c++` for C++, `-x objc` for Objective-C, and Common values are `-x c` for C, `-x c++` for C++, `-x objc` for Objective-C, and
`-x cuda` for CUDA. `-x cuda` for CUDA.
To give you an impression, if your c++ project is trivial, and your usual To give you an impression, if your C++ project is trivial, and your usual
compilation command is: `g++ -Wall -Wextra -Werror -o FILE.o FILE.cc`, then the compilation command is: `g++ -Wall -Wextra -Werror -o FILE.o FILE.cc`, then the
following `.ycm_extra_conf.py` is enough to get semantic analysis from following `.ycm_extra_conf.py` is enough to get semantic analysis from
YouCompleteMe: YouCompleteMe:
```python ```python
def FlagsForFile( filename, **kwargs ): def Settings( **kwargs ):
return { return {
'flags': [ '-x', 'c++', '-Wall', '-Wextra', '-Werror' ], 'flags': [ '-x', 'c++', '-Wall', '-Wextra', '-Werror' ],
} }
``` ```
As you can see from the trivial example, YCM calls the `FlagsForFile` method, As you can see from the trivial example, YCM calls the `Settings` method which
passing it the file name. The `**kwargs` is for advanced users and can usually returns a dictionary with a single element `'flags'`. This element is a `list`
be ignored. The `FlagsForFile` function returns a dictionary with a single of compiler flags to pass to libclang for the current file. The absolute path of
element `'flags'`. This element is a `list` of compiler flags to pass to that file is accessible under the `filename` key of the `kwargs` dictionary.
libclang for the file `filename`. That's it! This is actually enough for most That's it! This is actually enough for most projects, but for complex projects
projects, but for complex projects it is not uncommon to integrate directly with it is not uncommon to integrate directly with an existing build system using the
an existing build system using the full power of the Python language. full power of the Python language.
For a more elaborate example, For a more elaborate example,
[see YCM's own `.ycm_extra_conf.py`][flags_example]. You should be able to use [see YCM's own `.ycm_extra_conf.py`][flags_example]. You should be able to use
@ -1920,14 +1923,14 @@ Supported in filetypes: `cs, go, java, javascript, python, rust, typescript`
#### The `ClearCompilationFlagCache` subcommand #### The `ClearCompilationFlagCache` subcommand
YCM caches the flags it gets from the `FlagsForFile` function in your YCM caches the flags it gets from the `Settings` function in your
`ycm_extra_conf.py` file unless you return them with the `do_cache` parameter `.ycm_extra_conf.py` file unless you return them with the `do_cache` parameter
set to `False`. It also caches the flags extracted from the compilation set to `False`. It also caches the flags extracted from the compilation
database. The cache is in memory and is never invalidated (unless you restart database. The cache is in memory and is never invalidated (unless you restart
the server with the `:YcmRestartServer` command). the server with the `:YcmRestartServer` command).
This command clears that cache entirely. YCM will then re-query your This command clears that cache entirely. YCM will then re-query your
`FlagsForFile` function or your compilation database as needed in the future. `Settings` function or your compilation database as needed in the future.
Supported in filetypes: `c, cpp, objc, objcpp, cuda` Supported in filetypes: `c, cpp, objc, objcpp, cuda`
@ -2471,28 +2474,28 @@ let g:ycm_seed_identifiers_with_syntax = 0
### The `g:ycm_extra_conf_vim_data` option ### The `g:ycm_extra_conf_vim_data` option
If you're using semantic completion for C-family files, this option might come If you're using semantic completion for C-family files, this option might come
handy; it's a way of sending data from Vim to your `FlagsForFile` function in handy; it's a way of sending data from Vim to your `Settings` function in
your `.ycm_extra_conf.py` file. your `.ycm_extra_conf.py` file.
This option is supposed to be a list of VimScript expression strings that are This option is supposed to be a list of VimScript expression strings that are
evaluated for every request to the [ycmd server][ycmd] and then passed to your evaluated for every request to the [ycmd server][ycmd] and then passed to your
`FlagsForFile` function as a `client_data` keyword argument. `Settings` function as a `client_data` keyword argument.
For instance, if you set this option to `['v:version']`, your `FlagsForFile` For instance, if you set this option to `['v:version']`, your `Settings`
function will be called like this: function will be called like this:
```python ```python
# The '704' value is of course contingent on Vim 7.4; in 7.3 it would be '703' # The '801' value is of course contingent on Vim 8.1; in 8.0 it would be '800'
FlagsForFile(filename, client_data = {'v:version': 704}) Settings( ..., client_data = { 'v:version': 801 } )
``` ```
So the `client_data` parameter is a dictionary mapping Vim expression strings to So the `client_data` parameter is a dictionary mapping Vim expression strings to
their values at the time of the request. their values at the time of the request.
The correct way to define parameters for your `FlagsForFile` function: The correct way to define parameters for your `Settings` function:
```python ```python
def FlagsForFile(filename, **kwargs): def Settings( **kwargs ):
``` ```
You can then get to `client_data` with `kwargs['client_data']`. You can then get to `client_data` with `kwargs['client_data']`.
@ -3326,7 +3329,7 @@ reading.
The workaround is to call `echo | clang -v -E -x c++ -` and look at the The workaround is to call `echo | clang -v -E -x c++ -` and look at the
paths under the `#include <...> search starts here:` heading. You should take paths under the `#include <...> search starts here:` heading. You should take
those paths, prepend `-isystem` to each individual path and append them all to those paths, prepend `-isystem` to each individual path and append them all to
the list of flags you return from your `FlagsForFile` function in your the list of flags you return from your `Settings` function in your
`.ycm_extra_conf.py` file. `.ycm_extra_conf.py` file.
See [issue #303][issue-303] for details. See [issue #303][issue-303] for details.
@ -3467,7 +3470,7 @@ This software is licensed under the [GPL v3 license][gpl].
[vim]: http://www.vim.org/ [vim]: http://www.vim.org/
[syntastic]: https://github.com/scrooloose/syntastic [syntastic]: https://github.com/scrooloose/syntastic
[lightline]: https://github.com/itchyny/lightline.vim [lightline]: https://github.com/itchyny/lightline.vim
[flags_example]: https://raw.githubusercontent.com/Valloric/ycmd/3ad0300e94edc13799e8bf7b831de8b57153c5aa/cpp/ycm/.ycm_extra_conf.py [flags_example]: https://raw.githubusercontent.com/Valloric/ycmd/66030cd94299114ae316796f3cad181cac8a007c/.ycm_extra_conf.py
[compdb]: http://clang.llvm.org/docs/JSONCompilationDatabase.html [compdb]: http://clang.llvm.org/docs/JSONCompilationDatabase.html
[subsequence]: https://en.wikipedia.org/wiki/Subsequence [subsequence]: https://en.wikipedia.org/wiki/Subsequence
[listtoggle]: https://github.com/Valloric/ListToggle [listtoggle]: https://github.com/Valloric/ListToggle

67
doc/youcompleteme.txt
View File

@ -1236,9 +1236,8 @@ documentation [50]. In short:
- If using GNU make, check out Bear [52]. - If using GNU make, check out Bear [52].
- For other build systems, check out '.ycm_extra_conf.py' below. - For other build systems, check out '.ycm_extra_conf.py' below.
If no '.ycm_extra_conf.py' is found, and no 'ycm_global_ycm_extra_conf' is If no '.ycm_extra_conf.py' is found, YouCompleteMe automatically tries to load
configured, YouCompleteMe automatically tries to load a compilation database if a compilation database if there is one.
one is found.
YCM looks for a file named 'compile_commands.json' in the directory of the YCM looks for a file named 'compile_commands.json' in the directory of the
opened file or in any directory above it in the hierarchy (recursively); when opened file or in any directory above it in the hierarchy (recursively); when
@ -1269,7 +1268,7 @@ Option 2: Provide the flags manually ~
If you don't have a compilation database, or aren't able to generate one, you If you don't have a compilation database, or aren't able to generate one, you
have to tell YouCompleteMe how to compile your code some other way. have to tell YouCompleteMe how to compile your code some other way.
Every c-family project is different. It is not possible for YCM to guess what Every C-family project is different. It is not possible for YCM to guess what
compiler flags to supply for your project. Fortunately, YCM provides a compiler flags to supply for your project. Fortunately, YCM provides a
mechanism for you to generate the flags for a particular file with _arbitrary mechanism for you to generate the flags for a particular file with _arbitrary
complexity_. This is achieved by requiring you to provide a Python module which complexity_. This is achieved by requiring you to provide a Python module which
@ -1278,13 +1277,15 @@ list of compiler flags to use to compile that file.
YCM looks for a '.ycm_extra_conf.py' file in the directory of the opened 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 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' found, it is loaded (only once!) as a Python module. YCM calls a 'Settings'
method in that module which should provide it with the information necessary to 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 compile the current file. You can also provide a path to a global configuration
'.ycm_extra_conf.py' file, which will be used as a fallback. To prevent the file with the |g:ycm_global_ycm_extra_conf| option, which will be used as a
execution of malicious code from a file you didn't write YCM will ask you once fallback. To prevent the execution of malicious code from a file you didn't
per '.ycm_extra_conf.py' if it is safe to load. This can be disabled and you write YCM will ask you once per '.ycm_extra_conf.py' if it is safe to load.
can white-/blacklist files. See the _Options_ section for more details. This can be disabled and you can white-/blacklist files. See the
|g:ycm_confirm_extra_conf| and |g:ycm_extra_conf_globlist| options
respectively.
This system was designed this way so that the user can perform any arbitrary 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 sequence of operations to produce a list of compilation flags YCM should hand
@ -1295,23 +1296,23 @@ This is so that the correct language is detected, particularly for header
files. Common values are '-x c' for C, '-x c++' for C++, '-x objc' for files. Common values are '-x c' for C, '-x c++' for C++, '-x objc' for
Objective-C, and '-x cuda' for CUDA. Objective-C, and '-x cuda' for CUDA.
To give you an impression, if your c++ project is trivial, and your usual To give you an impression, if your C++ project is trivial, and your usual
compilation command is: 'g++ -Wall -Wextra -Werror -o FILE.o FILE.cc', then the compilation command is: 'g++ -Wall -Wextra -Werror -o FILE.o FILE.cc', then the
following '.ycm_extra_conf.py' is enough to get semantic analysis from following '.ycm_extra_conf.py' is enough to get semantic analysis from
YouCompleteMe: YouCompleteMe:
> >
def FlagsForFile( filename, **kwargs ): def Settings( **kwargs ):
return { return {
'flags': [ '-x', 'c++', '-Wall', '-Wextra', '-Werror' ], 'flags': [ '-x', 'c++', '-Wall', '-Wextra', '-Werror' ],
} }
< <
As you can see from the trivial example, YCM calls the 'FlagsForFile' method, As you can see from the trivial example, YCM calls the 'Settings' method which
passing it the file name. The '**kwargs' is for advanced users and can usually returns a dictionary with a single element "'flags'". This element is a 'list'
be ignored. The 'FlagsForFile' function returns a dictionary with a single of compiler flags to pass to libclang for the current file. The absolute path
element "'flags'". This element is a 'list' of compiler flags to pass to of that file is accessible under the 'filename' key of the 'kwargs' dictionary.
libclang for the file 'filename'. That's it! This is actually enough for most That's it! This is actually enough for most projects, but for complex projects
projects, but for complex projects it is not uncommon to integrate directly it is not uncommon to integrate directly with an existing build system using
with an existing build system using the full power of the Python language. the full power of the Python language.
For a more elaborate example, see YCM's own '.ycm_extra_conf.py' [53]. You For a more elaborate example, see YCM's own '.ycm_extra_conf.py' [53]. You
should be able to use it _as a starting point_. **Don't** just copy/paste that should be able to use it _as a starting point_. **Don't** just copy/paste that
@ -2209,14 +2210,14 @@ Supported in filetypes: 'cs, go, java, javascript, python, rust, typescript'
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
The *ClearCompilationFlagCache* subcommand The *ClearCompilationFlagCache* subcommand
YCM caches the flags it gets from the 'FlagsForFile' function in your YCM caches the flags it gets from the 'Settings' function in your
'ycm_extra_conf.py' file unless you return them with the 'do_cache' parameter '.ycm_extra_conf.py' file unless you return them with the 'do_cache' parameter
set to 'False'. It also caches the flags extracted from the compilation set to 'False'. It also caches the flags extracted from the compilation
database. The cache is in memory and is never invalidated (unless you restart database. The cache is in memory and is never invalidated (unless you restart
the server with the |:YcmRestartServer| command). the server with the |:YcmRestartServer| command).
This command clears that cache entirely. YCM will then re-query your This command clears that cache entirely. YCM will then re-query your 'Settings'
'FlagsForFile' function or your compilation database as needed in the future. function or your compilation database as needed in the future.
Supported in filetypes: 'c, cpp, objc, objcpp, cuda' Supported in filetypes: 'c, cpp, objc, objcpp, cuda'
@ -2740,25 +2741,25 @@ Default: '0'
The *g:ycm_extra_conf_vim_data* option The *g:ycm_extra_conf_vim_data* option
If you're using semantic completion for C-family files, this option might come If you're using semantic completion for C-family files, this option might come
handy; it's a way of sending data from Vim to your 'FlagsForFile' function in handy; it's a way of sending data from Vim to your 'Settings' function in your
your '.ycm_extra_conf.py' file. '.ycm_extra_conf.py' file.
This option is supposed to be a list of VimScript expression strings that are This option is supposed to be a list of VimScript expression strings that are
evaluated for every request to the ycmd server [49] and then passed to your evaluated for every request to the ycmd server [49] and then passed to your
'FlagsForFile' function as a 'client_data' keyword argument. 'Settings' function as a 'client_data' keyword argument.
For instance, if you set this option to "['v:version']", your 'FlagsForFile' For instance, if you set this option to "['v:version']", your 'Settings'
function will be called like this: function will be called like this:
> >
# The '704' value is of course contingent on Vim 7.4; in 7.3 it would be '703' # The '801' value is of course contingent on Vim 8.1; in 8.0 it would be '800'
FlagsForFile(filename, client_data = {'v:version': 704}) Settings( ..., client_data = { 'v:version': 801 } )
< <
So the 'client_data' parameter is a dictionary mapping Vim expression strings So the 'client_data' parameter is a dictionary mapping Vim expression strings
to their values at the time of the request. to their values at the time of the request.
The correct way to define parameters for your 'FlagsForFile' function: The correct way to define parameters for your 'Settings' function:
> >
def FlagsForFile(filename, **kwargs): def Settings( **kwargs ):
< <
You can then get to 'client_data' with "kwargs['client_data']". You can then get to 'client_data' with "kwargs['client_data']".
@ -3596,7 +3597,7 @@ continue reading.
The workaround is to call 'echo | clang -v -E -x c++ -' and look at the paths The workaround is to call 'echo | clang -v -E -x c++ -' and look at the paths
under the '#include <...> search starts here:' heading. You should take those under the '#include <...> search starts here:' heading. You should take those
paths, prepend '-isystem' to each individual path and append them all to the paths, prepend '-isystem' to each individual path and append them all to the
list of flags you return from your 'FlagsForFile' function in your list of flags you return from your 'Settings' function in your
'.ycm_extra_conf.py' file. '.ycm_extra_conf.py' file.
See issue #303 [81] for details. See issue #303 [81] for details.
@ -3793,7 +3794,7 @@ References ~
[50] http://clang.llvm.org/docs/JSONCompilationDatabase.html [50] http://clang.llvm.org/docs/JSONCompilationDatabase.html
[51] https://ninja-build.org/manual.html [51] https://ninja-build.org/manual.html
[52] https://github.com/rizsotto/Bear [52] https://github.com/rizsotto/Bear
[53] https://raw.githubusercontent.com/Valloric/ycmd/3ad0300e94edc13799e8bf7b831de8b57153c5aa/cpp/ycm/.ycm_extra_conf.py [53] https://raw.githubusercontent.com/Valloric/ycmd/66030cd94299114ae316796f3cad181cac8a007c/.ycm_extra_conf.py
[54] https://github.com/rdnetto/YCM-Generator [54] https://github.com/rdnetto/YCM-Generator
[55] https://help.eclipse.org/oxygen/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fproject_description_file.html [55] https://help.eclipse.org/oxygen/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fproject_description_file.html
[56] https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html [56] https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html