syntastic: A Vim Script repository from winteraspect

               ,
              / \,,_  .'|
           ,{{| /}}}}/_.'            _____________________________________________
          }}}}` '{{'  '.            /                                             \
        {{{{{    _   ;, \          /            Ladies and Gentlemen,              \
     ,}}}}}}    /o`\  ` ;)        |                                                |
    {{{{{{   /           (        |                 this is ...                    |
    }}}}}}   |            \       |                                                |
   {{{{{{{{   \            \      |                                                |
   }}}}}}}}}   '.__      _  |     |    _____             __             __  _      |
   {{{{{{{{       /`._  (_\ /     |   / ___/__  ______  / /_____ ______/ /_(_)____ |
    }}}}}}'      |    //___/   --=:   \__ \/ / / / __ \/ __/ __ `/ ___/ __/ / ___/ |
jgs `{{{{`       |     '--'       |  ___/ / /_/ / / / / /_/ /_/ (__  ) /_/ / /__   |
     }}}`                         | /____/\__, /_/ /_/\__/\__,_/____/\__/_/\___/   |
                                  |      /____/                                    |
                                  |                                               /
                                   \_____________________________________________/

Introduction
Installation
2.1. Requirements
2.2. Installing syntastic with Pathogen
Recommended settings
FAQ
4.1. I installed syntastic but it isn't reporting any errors...
4.2. The python checker complains about syntactically valid Python 3 constructs...
4.3. Are there any local checkers for HTML5 that I can use with syntastic?
4.4. The perl checker has stopped working...
4.5. What happened to the rustc checker?
4.6. I run a checker and the location list is not updated...
4.6. I run:lopen or :lwindow and the error window is empty...
4.7. How can I pass additional arguments to a checker?
4.8. Syntastic supports several checkers for my filetype - how do I tell which one(s) to use?
4.9. What is the difference between syntax checkers and style checkers?
4.10. I have enabled multiple checkers for the current filetype. How can I display all of the errors from all of the checkers together?
4.11. How can I jump between the different errors without using the location list at the bottom of the window?
4.12. The error window is closed automatically when I :quit the current buffer but not when I :bdelete it?
Resources

1. Introduction

Syntastic is a syntax checking plugin for Vim that runs files through external syntax checkers and displays any resulting errors to the user. This can be done on demand, or automatically as files are saved. If syntax errors are detected, the user is notified and is happy because they didn't have to compile their code or execute their script to find them.

At the time of this writing, syntax checking plugins exist for ActionScript, Ada, AppleScript, AsciiDoc, ASM, BEMHTML, Bro, Bourne shell, C, C++, C#, Cabal, Chef, CoffeeScript, Coco, Coq, CSS, Cucumber, CUDA, D, Dart, DocBook, Dust, Elixir, Erlang, eRuby, Fortran, Gentoo metadata, GLSL, Go, Haml, Haskell, Haxe, Handlebars, HSS, HTML, Java, JavaScript, JSON, JSX, LESS, Lex, Limbo, LISP, LLVM intermediate language, Lua, Markdown, MATLAB, NASM, Objective-C, Objective-C++, OCaml, Perl, Perl POD, PHP, gettext Portable Object, OS X and iOS property lists, Puppet, Python, R, Racket, Relax NG, reStructuredText, RPM spec, Ruby, SASS/SCSS, Scala, Slim, Tcl, TeX, Texinfo, Twig, TypeScript, Vala, Verilog, VHDL, VimL, xHtml, XML, XSLT, YACC, YAML, z80, Zope page templates, and zsh. See the wiki for details about the corresponding supported checkers.

Below is a screenshot showing the methods that Syntastic uses to display syntax errors. Note that, in practise, you will only have a subset of these methods enabled.

Errors are loaded into the location list for the corresponding window.
When the cursor is on a line containing an error, the error message is echoed in the command window.
Signs are placed beside lines with errors - note that warnings are displayed in a different color.
There is a configurable statusline flag you can include in your statusline config.
Hover the mouse over a line containing an error and the error message is displayed as a balloon.
(not shown) Highlighting errors with syntax highlighting. Erroneous parts of lines can be highlighted.

2. Installation

2.1. Requirements

Syntastic itself has rather relaxed requirements: it doesn't have any external dependencies, and it needs a version of Vim compiled with a few common features: autocmd, eval, file_in_path, modify_fname, quickfix, reltime, and user_commands. Not all possible combinations of features that include the ones above make equal sense on all operating systems, but Vim 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, Pathogen, Vim-Addon-Manager, Vim-Plug, or Vundle. Instructions for installing syntastic with Pathogen are included below for completeness.

Last but not least: syntastic doesn't know how to do any syntax checks by itself. In order to get meaningful results you need to install external checkers corresponding to the types of files you use. Please consult the wiki for a list of supported checkers.

2.2. Installing syntastic with Pathogen

If you already have Pathogen working then skip Step 1 and go to Step 2.

2.2.1. Step 1: Install pathogen.vim

First I'll show you how to install Tim Pope's Pathogen so that it's easy to install syntastic. Do this in your terminal so that you get the pathogen.vim file and the directories it needs:

mkdir -p ~/.vim/autoload ~/.vim/bundle && \
curl -LSso ~/.vim/autoload/pathogen.vim https://tpo.pe/pathogen.vim

Next you need to add this to your ~/.vimrc:

execute pathogen#infect()

2.2.2. Step 2: Install syntastic as a Pathogen bundle

You now have pathogen installed and can put syntastic into ~/.vim/bundle like this:

cd ~/.vim/bundle && \
git clone https://github.com/scrooloose/syntastic.git

Quit vim and start it back up to reload it, then type:

:Helptags

If you get an error when you do this, then you probably didn't install Pathogen right. Go back to Step 1 and make sure you did the following:

Created both the ~/.vim/autoload and ~/.vim/bundle directories.
Added the execute pathogen#infect() line to your ~/.vimrc file
Did the git clone of syntastic inside ~/.vim/bundle
Have permissions to access all of these directories.

3. Recommended settings

Syntastic has a large number of options that can be configured, and the defaults are not particularly well suitable for new users. It is recommended that you start by adding the following lines to your vimrc file, and return to them after reading the manual (see :help syntastic in Vim):

set statusline+=%#warningmsg#
set statusline+=%{SyntasticStatuslineFlag()}
set statusline+=%*

let g:syntastic_always_populate_loc_list = 1
let g:syntastic_auto_loc_list = 1
let g:syntastic_check_on_open = 1
let g:syntastic_check_on_wq = 0

4. FAQ

4.1. Q. I installed syntastic but it isn't reporting any errors...

A. The most likely reason is that none of the syntax checkers that it requires is installed. For example: by default, python requires either flake8 or pylint to be installed and in your $PATH. To see which executables are supported, look at the wiki. Note that aliases do not work; the actual executables must be available in your $PATH. Symbolic links are okay though. You can see syntastic's idea of available checkers by running :SyntasticInfo.

Another reason it could fail is that either the command line options 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 create an issue - or better yet, create a pull request.

4.2. Q. The python checker complains about syntactically valid Python 3 constructs...

A. Configure the python checker to call a Python 3 interpreter rather than Python 2, e.g:

let g:syntastic_python_python_exec = '/path/to/python3'

4.3. Q. Are there any local checkers for HTML5 that I can use with syntastic?

HTML Tidy has a fork named HTML Tidy for HTML5. 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.

Alternatively, you can install vnu.jar from the validator.nu project and run it as a HTTP server:

$ java -Xss512k -cp /path/to/vnu.jar nu.validator.servlet.Main 8888

Then you can configure syntastic to use it:

let g:syntastic_html_validator_api = 'http://localhost:8888/'

4.4. 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). 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:

let g:syntastic_enable_perl_checker = 1

4.5. Q. What happened to the rustc checker?

A. It has been included in the Rust compiler package. If you have a recent version of the Rust compiler, the checker should be picked up automatically by syntastic.

4.6. Q. I run a checker and the location list is not updated...
4.6. 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 location list to always be updated when you run the checkers, add this line to your vimrc:

let g:syntastic_always_populate_loc_list = 1

4.7. Q. How can I pass additional arguments to a checker?

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.

So, If you wanted to pass --my --args --here to the ruby mri checker you would add this line to your vimrc:

let g:syntastic_ruby_mri_args = "--my --args --here"

See :help syntastic-checker-options for more information.

4.8. Q. Syntastic supports several checkers for my filetype - how do I tell it which one(s) to use?

A. Stick a line like this in your vimrc:

let g:syntastic_<filetype>_checkers = ['<checker-name>']

To see the list of supported checkers for your filetype look at the wiki.

e.g. 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:

let g:syntastic_python_checkers = ['pylint']

Checkers can be chained together like this:

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>.

e.g. to run phpcs and phpmd:

:SyntasticCheck phpcs phpmd

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.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 arbitrary. There is an ongoing effort to keep things consistent, so you can generally expect messages produced by syntax checkers to be mostly related 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 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 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 type, or both.

e.g. To disable all style messages:

let g:syntastic_quiet_messages = { "type": "style" }

See :help syntastic_quiet_messages for details.

4.10. Q. I have enabled multiple checkers for the current filetype. How can I display all of the errors from all of the checkers together?

A. Set g:syntastic_aggregate_errors to 1 in your vimrc:

let g:syntastic_aggregate_errors = 1

See :help syntastic-aggregating-errors for more details.

4.11. Q. How can I jump between the different errors without using the location list at the bottom of the window?

A. Vim provides several built-in commands for this. See :help :lnext and :help :lprevious.

If you use these commands a lot then you may want to add shortcut mappings to your vimrc, or install something like unimpaired, which provides such mappings (among other things).

4.12. Q. The error window is closed automatically when I :quit the current buffer but not when I :bdelete it?

A. There is no safe way to handle that situation automatically, but you can work around it:

nnoremap <silent> <C-d> :lclose<CR>:bdelete<CR>
cabbrev <silent> bd lclose\|bdelete

5. Resources

The preferred place for posting suggestions, reporting bugs, and general discussions related to syntastic is the issue tracker at GitHub. A guide for writing syntax checkers can be found in the wiki. There are also a dedicated google group, and a syntastic tag at StackOverflow.

Syntastic aims to provide a common interface to syntax checkers for as many languages as possible. For particular languages, there are, of course, other plugins that provide more functionality than syntastic. You might want to take a look at jedi-vim, python-mode, or YouCompleteMe.

winteraspect/syntastic