@ -25,22 +25,21 @@
3. [Recommended settings ](#settings )
4. [FAQ ](#faq )
4.1. [I installed syntastic but it isn't reporting any errors... ](#faqinfo )
4.2. [How can I check scripts written for different versions of Python? ](#faqpython )
4.3. [How can I check scripts written for different versions of Ruby? ](#faqruby )
4.4. [Are there any local checkers for HTML5 that I can use with syntastic? ](#faqhtml5 )
4.5. [The `perl` checker has stopped working... ](#faqperl )
4.6. [What happened to the `rustc` checker? ](#faqrust )
4.7. [What happened to the `tsc` checker? ](#faqtsc )
4.8. [What happened to the `xcrun` checker? ](#faqxcrun )
4.9. [I run a checker and the location list is not updated... ](#faqloclist )
4.9. [I run`:lopen` or `:lwindow` and the error window is empty... ](#faqloclist )
4.10. [How can I pass additional arguments to a checker? ](#faqargs )
4.11. [Syntastic supports several checkers for my filetype - how do I tell which one(s) to use? ](#faqcheckers )
4.12. [What is the difference between syntax checkers and style checkers? ](#faqstyle )
4.13. [I have enabled multiple checkers for the current filetype. How can I display all errors from all checkers together? ](#faqaggregate )
4.14. [How can I jump between the different errors without using the location list at the bottom of the window? ](#faqlnext )
4.15. [My favourite checker needs to load a configuration file from the project's root rather than the current directory... ](#faqconfig )
4.16. [The error window is closed automatically when I :quit the current buffer but not when I :bdelete it? ](#faqbdelete )
4.2. [Syntastic supports several checkers for my filetype, how do I tell it which one(s) to use? ](#faqcheckers )
4.3. [I have enabled multiple checkers for the current filetype. How can I display all errors from all checkers together? ](#faqaggregate )
4.4. [How can I pass additional arguments to a checker? ](#faqargs )
4.5. [I run a checker and the location list is not updated... ](#faqloclist )
4.5. [I run`:lopen` or `:lwindow` and the error window is empty... ](#faqloclist )
4.6. [How can I jump between the different errors without using the location list at the bottom of the window? ](#faqlnext )
4.7. [The error window is closed automatically when I `:quit` the current buffer but not when I `:bdelete` it? ](#faqbdelete )
4.8. [My favourite checker needs to load a configuration file from the project's root rather than the current directory... ](#faqconfig )
4.9. [What is the difference between syntax checkers and style checkers? ](#faqstyle )
4.10. [How can I check scripts written for different versions of Python? ](#faqpython )
4.11. [How can I check scripts written for different versions of Ruby? ](#faqruby )
4.12. [The `perl` checker has stopped working... ](#faqperl )
4.13. [What happened to the `rustc` checker? ](#faqrust )
4.14. [What happened to the `tsc` checker? ](#faqtsc )
4.15. [What happened to the `xcrun` checker? ](#faqxcrun )
5. [Resources ](#otherresources )
- - -
@ -106,9 +105,9 @@ version 7 or later with the "normal", "big", or "huge" feature sets should be
fine.
Syntastic should work with any modern plugin managers for Vim, such as
[NeoBundle][neobundle], [Pathogen][pathogen], [Vim-Addon-Manager][vam], [Vim-Plug][plug], or
[Vundle][vundle]. Instructions for installing syntastic with [Pathogen][pathogen] are
included below for completeness.
[NeoBundle][neobundle], [Pathogen][pathogen], [Vim-Addon-Manager][vam],
[Vim-Plug][plug], or [V undle][vundle]. Instructions for installing syntastic
with [Pathogen][pathogen] are included below for completeness.
Starting with Vim version 7.4.1486 you can also load syntastic using the
standard mechanism of packages, without the help of third-party plugin managers
@ -230,100 +229,85 @@ or the error output for a syntax checker may have changed. In this case, make
sure you have the latest version of the syntax checker installed. If it still
fails then post an [issue][bug_tracker] - or better yet, create a pull request.
< a name = "faqpython" > < / a >
__4.2. Q. How can I check scripts written for different versions of Python?__
A. Install a Python version manager such as [virtualenv][virtualenv]
or [pyenv][pyenv], activate the environment for the relevant version
of Python, and install in it the checkers you want to use. Set
`g:syntastic_python_checkers` accordingly in your `vimrc` , and run [Vim][vim]
from the virtual environment.
If you're starting Vim from a desktop manager rather than from a terminal you
might need to write wrapper scripts around your checkers, to activate the
virtual environment before running the actual checks. Then you'll need to
point the relevant `g:syntastic_python_<checker>_exec` variables to the wrapper
scripts.
< a name = "faqruby" > < / a >
__4.3. Q. How can I check scripts written for different versions of Ruby?__
A. Install a Ruby version manager such as [rvm][rvm] or [rbenv][rbenv],
activate the environment for the relevant version of Ruby, and install in it
the checkers you want to use. Set `g:syntastic_ruby_checkers` accordingly in
your `vimrc` , and run [Vim][vim] from the virtual environment.
< a name = "faqcheckers" > < / a >
If you're starting Vim from a desktop manager rather than from a terminal you
might need to write wrapper scripts around your checkers, to activate the
virtual environment before running the actual checks. Then you'll need to
point the relevant `g:syntastic_ruby_<checker>_exec` variables to the wrapper
scripts.
__4.2. Q. Syntastic supports several checkers for my filetype, how do I tell it
which one(s) to use?__
< a name = "faqhtml5" > < / a >
A. Add a line like this to your `vimrc` :
```vim
let g:syntastic_< filetype > _checkers = ['< checker-name > ']
```
__4.4. Q. Are there any local checkers for HTML5 that I can use with syntastic?__
To see the list of supported checkers for your filetype read the
[manual][checkers] (`:help syntastic-checkers` in Vim).
[HTML Tidy][tidy_old] has a fork named [HTML Tidy for HTML5][tidy]. It's a drop
in replacement, and syntastic can use it without changes. Just install it
somewhere and point `g:syntastic_html_tidy_exec` to its executable :
For example, Python has the following checkers, among others: `flake8` ,
`pyflakes` , `pylint` and a native `python` checker. To tell syntastic to use
`pylint` , you would use this setting:
```vim
let g:syntastic_html_tidy_exec = 'tidy5'
```
Alternatively, you can install [vnu.jar][vnu_jar] from the [validator.nu][vnu]
project and run it as a [HTTP server][vnu_server]:
```sh
$ java -Xss512k -cp /path/to/vnu.jar nu.validator.servlet.Main 8888
let g:syntastic_python_checkers = ['pylint']
```
Then you can configure syntastic to use it:
Checkers can be chained together like this:
```vim
let g:syntastic_html_validator_api = 'http://localhost:8888/'
let g:syntastic_php_checkers = ['php', 'phpcs', 'phpmd']
```
< a name = "faqperl" > < / a >
__4.5. Q. The `perl` checker has stopped working...__
This is telling syntastic to run the `php` checker first, and if no errors are
found, run `phpcs` , and then `phpmd` .
A. The `perl` checker runs `perl -c` against your file, which in turn
__executes__ any `BEGIN` , `UNITCHECK` , and `CHECK` blocks, and any `use`
statements in your file (cf. [perlrun][perlrun]). This is probably fine if you
wrote the file yourself, but it's a security problem if you're checking
third-party files. Since there is currently no way to disable this behaviour
while still producing useful results, the checker is now disabled by default.
To (re-)enable it, make sure the `g:syntastic_perl_checkers` list includes
`perl` , and set `g:syntastic_enable_perl_checker` to 1 in your `vimrc` :
You can also run checkers explicitly by calling `:SyntasticCheck <checker>` .
For example to run `phpcs` and `phpmd` :
```vim
let g:syntastic_enable_perl_checker = 1
:SyntasticCheck phpcs phpmd
```
< a name = "faqrust" > < / a >
This works for any checkers available for the current filetype, even if they
aren't listed in `g:syntastic_<filetype>_checkers` . You can't run checkers for
"foreign" filetypes though (e.g. you can't run, say, a Python checker if the
filetype of the current file is `php` ).
__4.6. Q. What happened to the `rustc` checker?__
< a name = "faqaggregate" > < / a >
A. It is now part of the [rust.vim][rust] plugin. If you install this plugin the
checker should be picked up automatically by syntastic.
__4.3. Q. I have enabled multiple checkers for the current filetype. How can I
display all errors from all checkers together?__
< a name = "faqtsc" > < / a >
A. Set `g:syntastic_aggregate_errors` to 1 in your `vimrc` :
```vim
let g:syntastic_aggregate_errors = 1
```
__4.7. Q. What happened to the `tsc` checker?__
See `:help syntastic-aggregating-errors` for more details.
A. It didn't meet people's expectations and it has been removed. Please
consider using the external checker [tsuquyomi][tsuquyomi] instead. If you
install this plugin the checker should be picked up automatically by syntastic.
< a name = "faqargs" > < / a >
< a name = "faqxcrun" > < / a >
__4.4. Q. How can I pass additional arguments to a checker?__
__4.8. Q. What happened to the `xcrun` checker?__
A. In most cases a command line is constructed using an internal function
named `makeprgBuild()` , which provides a number of options that allow you to
customise every part of the command that gets run. You can set these options
using global variables.
A. The `xcrun` checker used to have a security problem and it has been removed.
A better checker for __Swift__ is part of the [vim-swift][swift] plugin. If you
install this plugin the checker should be picked up automatically by syntastic.
The general form of the global `args` variable is
`syntastic_<filetype>_<checker>_args` . Thus if you wanted to pass
`--my --args --here` to the Ruby `mri` checker you would add this line to your
`vimrc` :
```vim
let g:syntastic_ruby_mri_args = "--my --args --here"
```
See `:help syntastic-checker-options` for more information.
A number of checkers don't use the `makeprgBuild()` function mentioned above,
or have additional options that can be configured. For these checkers the exact
list of options should be included in the [manual][checkers]
(`:help syntastic-checkers` in Vim).
< a name = "faqloclist" > < / a >
__4.9. Q. I run a checker and the location list is not updated...__
__4.9. Q. I run`:lopen` or `:lwindow` and the error window is empty...__
__4.5 . Q. I run a checker and the location list is not updated...__
__4.5 . Q. I run`:lopen` or `:lwindow` and the error window is empty...__
A. By default the location list is changed only when you run the `:Errors`
command, in order to minimise conflicts with other plugins. If you want the
@ -333,66 +317,53 @@ your `vimrc`:
let g:syntastic_always_populate_loc_list = 1
```
< a name = "faqargs" > < / a >
__4.10. Q. How can I pass additional arguments to a checker?__
< a name = "faqlnext" > < / a >
A. Almost all syntax checkers use the `makeprgBuild()` function. Those checkers
that do can be configured using global variables. The general form of the
global `args` variables is `syntastic_<filetype>_<checker>_args` .
__4.6. Q. How can I jump between the different errors without using the location
list at the bottom of the window?__
So, If you wanted to pass `--my --args --here` to the ruby mri checker you
would add this line to your `vimrc` :
```vim
let g:syntastic_ruby_mri_args = "--my --args --here"
```
A. Vim provides several built-in commands for this. See `:help :lnext` and
`:help :lprevious` .
See `:help syntastic-checker-options` for more information.
If you use these commands a lot then you may want to add shortcut mappings to
your `vimrc` , or install something like [unimpaired][unimpaired], which provides such
mappings (among other things).
< a name = "faqcheckers" > < / a >
< a name = "faqbdelete " > < / a >
__4.11. Q. Syntastic supports several checkers for my filetype - how do I tell it
which one(s) to use ?__
__4.7. Q. The error window is closed automatically when I `:quit` the current buffer
but not when I `:bdelete` it ?__
A. Stick a line like this in your `vimrc` :
A. There is no safe way to handle that situation automatically, but you can
work around it:
```vim
let g:syntastic_< filetype > _checkers = ['< checker-name > ']
nnoremap < silent > < C-d > :lclose< CR > :bdelete< CR >
cabbrev < silent > bd < C-r > =(getcmdtype()==#':' && getcmdpos()==1 ? 'lclose\|bdelete' : 'bd')< CR >
```
To see the list of supported checkers for your filetype read the
[manual][checkers] (`:help syntastic-checkers` in Vim).
< a name = "faqconfig" > < / a >
e.g. Python has the following checkers, among others: `flake8` , `pyflakes` ,
`pylint` and a native `python` checker.
__4.8. My favourite checker needs to load a configuration file from the
project's root rather than the current directory...__
To tell syntastic to use `pylint` , you would use this setting:
```vim
let g:syntastic_python_checkers = ['pylint']
```
A. You can set up an `autocmd` to search for the configuration file in the
current directory and upwards, and add it to the checker's options when found.
For example for `jscs` :
Checkers can be chained together like this:
```vim
let g:syntastic_php_checkers = ['php', 'phpcs', 'phpmd']
```
This is telling syntastic to run the `php` checker first, and if no errors are
found, run `phpcs` , and then `phpmd` .
You can also run checkers explicitly by calling `:SyntasticCheck <checker>` .
function! FindConfig(prefix, what, where)
let cfg = findfile(a:what, escape(a:where, ' ') . ';')
return cfg !=# '' ? ' ' . a:prefix . ' ' . shellescape(cfg) : ''
endfunction
e.g. to run `phpcs` and `phpmd` :
```vim
:SyntasticCheck phpcs phpmd
autocmd FileType javascript let b:syntastic_javascript_jscs_args =
\ get(g:, 'syntastic_javascript_jscs_args', '') .
\ FindConfig('-c', '.jscsrc', expand('< afile > :p:h', 1))
```
This works for any checkers available for the current filetype, even if they
aren't listed in `g:syntastic_<filetype>_checkers` . You can't run checkers for
"foreign" filetypes though (e.g. you can't run, say, a Python checker if the
filetype of the current file is `php` ).
< a name = "faqstyle" > < / a >
__4.12 . Q. What is the difference between syntax checkers and style checkers?__
__4.9. Q. What is the difference between syntax checkers and style checkers?__
A. The errors and warnings they produce are highlighted differently and can
be filtered by different rules, but otherwise the distinction is pretty much
@ -402,13 +373,13 @@ to syntax, and messages produced by style checkers to be _mostly_ about style.
But there can be no formal guarantee that, say, a style checker that runs into
a syntax error wouldn't die with a fatal message, nor that a syntax checker
wouldn't give you warnings against using some constructs as being bad practice.
There is also no guarantee that messages marked as "style" are less severe than
the ones marked as "syntax" (whatever that might mean). And there are even a
There is also no guarantee that messages marked as `style` are less severe than
the ones marked as `syntax` (whatever that might mean). And there are even a
few Frankenstein checkers (for example `flake8` and `pylama` ) that, by their
nature, produce both kinds of messages. Syntastic is not smart enough to be
able to sort out these things by itself.
In fact it's more useful to look at this from the perspective of filtering
Generally it's more useful to look at this from the perspective of filtering
unwanted messages, rather than as an indicator of severity levels. The
distinction between syntax and style is orthogonal to the distinction between
errors and warnings, and thus you can turn off messages based on level, on
@ -418,63 +389,77 @@ e.g. To disable all style messages:
```vim
let g:syntastic_quiet_messages = { "type": "style" }
```
See `:help syntastic_quiet_messages` for details .
See `:help syntastic_quiet_messages` for more information .
< a name = "faqaggregate" > < / a >
__4.13. Q. I have enabled multiple checkers for the current filetype. How can I
display all errors from all checkers together?__
< a name = "faqpython" > < / a >
A. Set `g:syntastic_aggregate_errors` to 1 in your `vimrc` :
```vim
let g:syntastic_aggregate_errors = 1
```
__4.10. Q. How can I check scripts written for different versions of Python?__
See `:help syntastic-aggregating-errors` for more details.
A. Install a Python version manager such as [virtualenv][virtualenv]
or [pyenv][pyenv], activate the environment for the relevant version
of Python, and install in it the checkers you want to use. Set
`g:syntastic_python_checkers` accordingly in your `vimrc` , and run [Vim][vim]
from the virtual environment.
< a name = "faqlnext" > < / a >
If you're starting Vim from a desktop manager rather than from a terminal you
might need to write wrapper scripts around your checkers, to activate the
virtual environment before running the actual checks. Then you'll need to
point the relevant `g:syntastic_python_<checker>_exec` variables to the wrapper
scripts.
__4.14. Q. How can I jump between the different errors without using the location
list at the bottom of the window?__
< a name = "faqruby" > < / a >
A. Vim provides several built-in commands for this. See `:help :lnext` and
`:help :lprevious` .
__4.11. Q. How can I check scripts written for different versions of Ruby?__
If you use these commands a lot then you may want to add shortcut mappings to
your `vimrc` , or install something like [unimpaired][unimpaired], which provides such
mappings (among other things).
A. Install a Ruby version manager such as [rvm][rvm] or [rbenv][rbenv],
activate the environment for the relevant version of Ruby, and install in it
the checkers you want to use. Set `g:syntastic_ruby_checkers` accordingly in
your `vimrc` , and run [Vim][vim] from the virtual environment.
< a name = "faqconfig" > < / a >
If you're starting Vim from a desktop manager rather than from a terminal you
might need to write wrapper scripts around your checkers, to activate the
virtual environment before running the actual checks. Then you'll need to
point the relevant `g:syntastic_ruby_<checker>_exec` variables to the wrapper
scripts.
__4.15. My favourite checker needs to load a configuration file from the
project's root rather than the current directory...__
< a name = "faqperl" > < / a >
A. You can set up an `autocmd` to search for the configuration file in the
current directory and upwards, and add it to the checker's options when found.
For example for `jscs` :
__4.12. Q. The `perl` checker has stopped working...__
A. The `perl` checker runs `perl -c` against your file, which in turn
__executes__ any `BEGIN` , `UNITCHECK` , and `CHECK` blocks, and any `use`
statements in your file (cf. [perlrun][perlrun]). This is probably fine if you
wrote the file yourself, but it's a security problem if you're checking
third-party files. Since there is currently no way to disable this behaviour
while still producing useful results, the checker is now disabled by default.
To (re-)enable it, make sure the `g:syntastic_perl_checkers` list includes
`perl` , and set `g:syntastic_enable_perl_checker` to 1 in your `vimrc` :
```vim
function! FindConfig(prefix, what, where)
let cfg = findfile(a:what, escape(a:where, ' ') . ';')
return cfg !=# '' ? ' ' . a:prefix . ' ' . shellescape(cfg) : ''
endfunction
autocmd FileType javascript let b:syntastic_javascript_jscs_args =
\ get(g:, 'syntastic_javascript_jscs_args', '') .
\ FindConfig('-c', '.jscsrc', expand('< afile > :p:h', 1))
let g:syntastic_enable_perl_checker = 1
```
< a name = "faqbdelete" > < / a >
__4.16. Q. The error window is closed automatically when I :quit the current buffer
but not when I :bdelete it?__
< a name = "faqrust" > < / a >
A. There is no safe way to handle that situation automatically, but you can
work around it:
__4.13. Q. What happened to the `rustc` checker?__
```vim
nnoremap < silent > < C-d > :lclose< CR > :bdelete< CR >
cabbrev < silent > bd < C-r > =(getcmdtype()==#':' && getcmdpos()==1 ? 'lclose\|bdelete' : 'bd')< CR >
```
A. It is now part of the [rust.vim][rust] plugin. If you install this plugin the
checker should be picked up automatically by syntastic.
< a name = "faqtsc" > < / a >
__4.14. Q. What happened to the `tsc` checker?__
A. It didn't meet people's expectations and it has been removed. The plugin
[tsuquyomi][tsuquyomi] comes packaged with a checker for TypeScript. If you
install this plugin the checker should be picked up automatically by syntastic.
< a name = "faqxcrun" > < / a >
__4.15. Q. What happened to the `xcrun` checker?__
A. The `xcrun` checker used to have a security problem and it has been removed.
A better checker for __Swift__ is part of the [vim-swift][swift] plugin. If you
install this plugin the checker should be picked up automatically by syntastic.
< a name = "otherresources" > < / a >
@ -517,8 +502,6 @@ a look at [ghcmod-vim][ghcmod], [jedi-vim][jedi], [python-mode][python_mode], [v
[rvm]: https://rvm.io/
[stack_overflow]: http://stackoverflow.com/questions/tagged/syntastic
[swift]: https://github.com/kballard/vim-swift
[tidy]: http://www.htacg.org/tidy-html5/
[tidy_old]: http://tidy.sourceforge.net/
[tsuquyomi]: https://github.com/Quramy/tsuquyomi/
[unimpaired]: https://github.com/tpope/vim-unimpaired
[vam]: https://github.com/MarcWeber/vim-addon-manager