Permalink
580 lines (491 sloc) 25.4 KB
*neomake.txt* Asynchronous make for Vim version 7.4 and Neovim
███╗ ██╗███████╗ ██████╗ ███╗ ███╗ █████╗ ██╗ ██╗███████╗
████╗ ██║██╔════╝██╔═══██╗████╗ ████║██╔══██╗██║ ██╔╝██╔════╝
██╔██╗ ██║█████╗ ██║ ██║██╔████╔██║███████║█████╔╝ █████╗
██║╚██╗██║██╔══╝ ██║ ██║██║╚██╔╝██║██╔══██║██╔═██╗ ██╔══╝
██║ ╚████║███████╗╚██████╔╝██║ ╚═╝ ██║██║ ██║██║ ██╗███████╗
╚═╝ ╚═══╝╚══════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝
Run make tasks (such as linters and build tools) asynchronously
==============================================================================
CONTENTS *neomake-contents*
1. Introduction ............................... |neomake-introduction|
2. Commands ....................................... |neomake-commands|
3. Configuration ............................. |neomake-configuration|
4. Functions ..................................... |neomake-functions|
5. Autocommands ................................... |neomake-autocmds|
6. Frequently Asked Questions (FAQ) .................... |neomake-faq|
==============================================================================
1. Introduction *neomake-introduction*
Neomake leverages Neovim's or Vim's |job-control| feature where available to
run programs like syntax checkers asynchronously. Where job control is not
available, it resorts to a synchronous |system()| call, making it possible to
run this plugin in both Vim and Neovim. This plugin is heavily inspired by
fantastic Vim plugins such as syntastic and dispatch.
==============================================================================
2. Commands *neomake-commands*
*:Neomake*
*:NeomakeFile*
:Neomake [makers] Run a make command with the current file as input. If
no makers are specified, the default makers for the
current |filetype| are used. See
|neomake-configuration| for more on makers.
*:Neomake!*
*:NeomakeProject*
:Neomake! [makers] Run a make command with no file as input. If no makers
are specified, the default top-level makers will be
used. If no default top-level makers exist,
|'makeprg'| will be used.
*:NeomakeSh*
:NeomakeSh {command} Run {command} in a shell (according to 'shell'). The
command output will be loaded into the quickfix list
when the job is complete. Example: >
:NeomakeSh find . -name '*.pyc'
<
*:NeomakeSh!*
:NeomakeSh! {command} Same as |:NeomakeSh|, but does not buffer the output.
Example: >
:NeomakeSh! while true; do date; sleep 1; done
<
*:NeomakeInfo*
:NeomakeInfo Display information, meant for debugging and inclusion
in bug reports / help requests.
*:NeomakeListJobs*
:NeomakeListJobs List all running jobs in the format: >
job_id job_name
<
*:NeomakeCancelJob*
:NeomakeCancelJob {job_id}
Terminate a job identified by its job_id.
*:NeomakeCancelJobs*
:NeomakeCancelJobs
Terminate all jobs.
==============================================================================
3. Configuration *neomake-configuration*
If you just want an easy way to run |:make| asynchronously, you're all set.
Just set your |'makeprg'| and |'errorformat'| as usual, and run |:Neomake!|.
If you want more, read on.
Makers *neomake-makers*
A maker is an object that tells Neomake how to run a job for you. A maker may
be run with a file as input (great for linting), or with no file as input
(great for building, project-level tasks).
Here is a sample maker definition: >
let g:neomake_make_maker = {
\ 'exe': 'make',
\ 'args': ['--build'],
\ 'errorformat': '%f:%l:%c: %m',
\ }
" Use the maker like this:
:Neomake! make
<
The `exe` and `args` entries can be a function reference (see |Funcref|) or a
dictionary with an expected entry `fn` (which has to be a function).
The function will be called with no arguments, and should return the value to
use.
`exe` has to be a string, while `args` can be a list or a string.
If `args` is a list, entries like '%' and '%:p' will be |expand()|ed, and
quoting/escaping is applied automatically. If you want to handle escaping
yourself, `args` should be a string.
In the above example, the exe argument isn't strictly necessary, since Neomake
uses the name of the maker as the default value for it. If you want it to be
usable on an individual file, you should also include the filetype in the
name: >
let g:neomake_c_lint_maker = {
\ 'exe': 'lint',
\ 'args': ['--option', 'x'],
\ 'errorformat': '%f:%l:%c: %m',
\ }
" Run this maker for the open file (runs "lint --option x myfile.c"):
:Neomake lint
" Or run it on the whole project, executing the command from Vim's current
" working directory (runs "lint --option x"):
:Neomake! c_lint
<
*neomake-{{makepath}}*
*neomake-!!makepath!!*
When running a maker on a file with |:Neomake|, you may want to control where
in the `args` list the file's path will appear. To do this, insert '%:p' in
the `args` list. {{makepath}} and !!makepath!! are no longer used for this,
but will be retained in the docs for discoverability: >
let g:neomake_c_lint_maker = {
\ 'exe': 'lint',
\ 'args': ['%:p', '--option', 'x'],
\ 'errorformat': '%f:%l:%c: %m',
\ }
<
This will cause "lint /path/to/file.c --option x" to be run instead of
"lint --option x /path/to/file.c".
The file path can be excluded from the argument list entirely by setting the
'append_file' argument to 0. >
let g:neomake_c_lint_maker = {
\ 'exe': 'lint',
\ 'args': ['--option', 'x'],
\ 'append_file': 0,
\ 'errorformat': '%f:%l:%c: %m',
\ }
<
This can be useful for makers that are filetype dependent but are typically
run on an whole project rather than a specific file.
*neomake-makers-processing*
*neomake-makers-mapexpr*
You can define two optional properties on a maker object to process its
output: `mapexpr` is applied to the maker's output before any processing, and
`postprocess` is applied to each of the quickfix or location list entries.
The `mapexpr` property will be passed directly into |map()| as the `expr`
argument like so: >
call map(lines, maker.mapexpr)
<where `lines` contains the maker output.
The following variables are available in the `mapexpr`:
- `neomake_output_source`: either "stderr" or "stdout", depending on
where the output is coming from. This will be "stdout" always for
non-async Vim.
- `neomake_bufname` and `neomake_bufdir`: the buffer's name (|bufname()|) and
directory, respectively.
The `mapexpr` itself is being evaluated in the context of the affected buffer
in file mode, and in the context of the buffer that is current when the maker
finished otherwise.
The following `mapexpr` could be used to prefix the output type: >
"printf('[%s] %s', neomake_output_source, v:val)"
<
*neomake-makers-postprocess*
The `postprocess` property is a function reference that will be applied to the
entry in the location or quickfix list.
Example: change the entry type to a warning. >
function SetWarningType(entry)
a:entry.type = 'W'
endfunction
let g:neomake_c_lint_maker = {
\ 'exe': 'lint',
\ 'args': ['--option', 'x'],
\ 'errorformat': '%f:%l:%c: %m',
\ 'postprocess': function('SetWarningType')
\ }
<
The default is to use `neomake#utils#CompressWhitespace` here, which fixes
whitespace issues (especially with multiline error messages).
This can also be used to set the `length` property of an entry, which is used
to highlight entries in the text (|neomake-highlight|).
See `neomake#makers#ft#text#PostprocessWritegood` for an example.
Entries can be selectively removed in post-processing by setting its "valid"
property to `-1`. This removal will happen even if `remove_invalid_entries`
is disabled. This feature is meant for conditional removals and a simpler way
for end users to filter list entries. Makers should handle removals through
|errorformat| using '%-G' to remove items that should never appear in the
error list.
*neomake-makers-buffer_output*
Default: 1
By default Neomake will only process the output from makers when either the
output type changes (from stderr to stdout or vice versa), or at the end of
the job.
If you have a maker that is expected to run longer, and you want to get
feedback as early as possible, you can set this to `0`.
You can override this for a maker using e.g.: >
let g:neomake_ft_test_maker_buffer_output = 0
<
Your results will appear earlier, but if the |'errorformat'| is meant to parse
multiline output this will likely cause issues (depending on how the maker
flushes its output).
*neomake-makers-remove_invalid_entries*
Makers can be configured to filter invalid entries from the location/quickfix
list (i.e. entries that do not match the |'errorformat'|, and that would show
up with a `||` prefix in the location/quickfix list): >
let g:neomake_ft_maker_remove_invalid_entries = 1
<
NOTE: the default for this used to be 1, but it was changed because it is
usually better to see unhandled output in case something is not working as
expected, e.g. when the program displays some error.
Makers should handle this properly through |errorformat|, e.g. by using '%-G'
(see |efm-ignore|). You can specify the default for this via
|g:neomake_remove_invalid_entries|.
*neomake-makers-cwd*
The working directory used to run a maker can be changed by setting its `cwd`
property: >
let g:neomake_my_example_maker = {
\ 'exe': 'pwd',
\ 'cwd': '%:p:h'
\ }
<
Global Options *neomake-options*
*g:neomake_<name>_maker*
*g:neomake_<ft>_<name>_maker*
Define a new filetype or project-level maker. See |neomake-makers|.
*neomake-makers-properties*
*g:neomake_<name>_<property>*
*g:neomake_<ft>_<name>_<property>*
*b:neomake_<name>_<property>*
*b:neomake_<ft>_<name>_<property>*
Configure properties for a maker where <property> is one of `exe`, `args`,
`errorformat`, `buffer_output`, `remove_invalid_entries` or `append_file`.
This can be set per buffer, too. Example: >
let g:neomake_javascript_jshint_exe = './myjshint'
let b:neomake_javascript_jshint_exe = './myotherjshint'
<
The global defaults can be configured using `g:neomake_<property>`, i.e.
*g:neomake_remove_invalid_entries* to remove invalid entries from the quickfix
/ location list (|neomake-makers-remove_invalid_entries|), unless explicitly
provided by the maker or overridden by your global/buffer setting.
The internal defaults are: >
let defaults = {
\ 'exe': maker.name,
\ 'args': [],
\ 'errorformat': &errorformat,
\ 'buffer_output': 0,
\ 'remove_invalid_entries': 0
\ }
<
*g:neomake_<ft>_enabled_makers*
*b:neomake_<ft>_enabled_makers*
This setting will tell Neomake which makers to use by default for the given
filetype `<ft>` (when called without a maker as an argument, i.e. |:Neomake|).
The default for this setting is the return value of the function
`neomake#makers#ft#<ft>#EnabledMakers`. For Python this is defined in
`./autoload/neomake/makers/ft/python.vim`, and might return: >
['python', 'frosted', 'pylama']
<
This setting can also be defined per buffer, so the following snippet can be
used to configure a custom set of makers from your vimrc: >
let g:neomake_python_enabled_makers = ['pep8', 'pylint']
augroup my_custom_maker
au!
au Filetype custom.py let b:neomake_python_enabled_makers = ['flake8']
augroup END
<
Please refer to |autocmd-patterns| for help on defining the pattern
(`custom.py`) in this case.
*g:neomake_enabled_makers*
This setting will tell Neomake which makers to use by default when not
operating on a single file, or when no makers are defined for the filetype of
the current buffer. This effectively defaults to: >
let g:neomake_enabled_makers = ['makeprg']
<
*g:neomake_open_list*
This setting will open the |location-list| or |quickfix| list (depending on
whether it is operating on a file) when adding entries. A value of 2 will
preserve the cursor position when the |location-list| or |quickfix| window is
opened. Defaults to 0.
*g:neomake_list_height*
The height of the |location-list| or |quickfix| list opened by Neomake.
Defaults to 10.
*g:neomake_echo_current_error*
This setting will echo the error for the line your cursor is on, if any.
Defaults to 1.
*g:neomake_serialize*
Setting this to 1 tells Neomake to run each enabled maker one after the other.
This is a good way to ensure messages don't get mixed up. This setting is
implied with non-async Vim versions.
*g:neomake_serialize_abort_on_error*
Setting this to 1 tells Neomake to abort after the first error status is
encountered. This setting only works when |g:neomake_serialize| is on.
*g:neomake_verbose*
Controls how verbose Neomake should be. Neomake log levels are as follows:
0 - Errors only
1 - Quiet message (default -- should only log one message at a time)
2 - Loud message (may log multiple messages at once, making the screen
shift momentarily)
3 - Debug information (all messages).
This will also add time information to messages.
Each log level includes all the levels before it.
*g:neomake_logfile*
Specify a logfile where all log messages will be logged. The setting
|g:neomake_verbose| does not influence which messages will be logged to file,
making it possible to reduce the number of messages you see in your editor
without losing that information should you need it. Mainly for people hacking
on Neomake itself. This feature is not yet cross-platform.
*neomake-signs*
*g:neomake_place_signs*
This setting enables the placement of signs next to items from the location
and quickfix list (i.e. errors/warnings etc recognized from the
|'errorformat'|). Defaults to 1.
*g:neomake_error_sign*
*g:neomake_warning_sign*
*g:neomake_info_sign*
*g:neomake_message_sign*
These options allow you to control the appearance of the signs that are
placed into the |signs| column next to lines with messages.
These are dictionaries that represent the parameters provided by
|:sign-define|. Here is an example definition: >
let g:neomake_error_sign = {
\ 'text': 'E>',
\ 'texthl': 'ErrorMsg',
\ }
<
See the |:highlight| command to list the highlight groups available to you or
create new ones.
Neomake uses the following defaults: >
let g:neomake_error_sign = {'text': '✖', 'texthl': 'NeomakeErrorSign'}
let g:neomake_warning_sign = {
\ 'text': '⚠',
\ 'texthl': 'NeomakeWarningSign',
\ }
let g:neomake_message_sign = {
\ 'text': '➤',
\ 'texthl': 'NeomakeMessageSign',
\ }
let g:neomake_info_sign = {'text': 'ℹ', 'texthl': 'NeomakeInfoSign'}
<
Default |highlight-groups| are created with those names, but only if they do
not exist already, which allows you to customize them. This should typically
be done through the |ColorScheme| autoevent, which applies it after any color
scheme: >
augroup my_neomake_signs
au!
autocmd ColorScheme *
\ hi NeomakeErrorSign ctermfg=white |
\ hi NeomakeWarningSign ctermfg=yellow
augroup END
<
You can use `neomake#utils#GetHighlight` to get e.g. the "bg" from
"SignColumn". See `neomake#signs#DefineHighlights` where this is used.
*neomake-highlight*
*g:neomake_highlight_columns*
This setting enables highlighting of columns for items from the location and
quickfix list. Defaults to 1.
*g:neomake_highlight_lines*
This setting enables highlighting of lines for items from the location and
quickfix list. This overrides |g:neomake_highlight_columns|, since it
highlights the whole line already. Defaults to 0.
The following highlighting groups are used. They default to fg/bg colors from
common highlighting groups, similar to |neomake-signs|, but
underlined/undercurled (GUI).
- NeomakeError
- NeomakeWarning
- NeomakeInfo
- NeomakeMessage
You can define them yourself: >
augroup my_neomake_highlights
au!
autocmd ColorScheme *
\ hi link NeomakeError SpellBad |
\ hi link NeomakeWarning SpellCap
augroup END
>
*g:airline#extensions#neomake#enabled*
Shows warning and error counts returned by |neomake#statusline#LoclistCounts|
in the warning and error sections of the vim-airline |'statusline'|. Defaults
to 1.
==============================================================================
4. Functions *neomake-functions*
This list is non-exhaustive at the moment, but you may find some of these
functions useful.
*neomake#Make* (filemode, makers[, callback])
This function is called by the |:Neomake| (and |:Neomake!|) command. It runs
all the `makers` specified, in order. If `filemode` is 1, then the current
file is used as input to the makers.
It returns an array of job ids that were created; you can potentially cancel
these jobs with |neomake#CancelJob|.
It also accepts a third, optional callback argument that
is called when the command exits. The callback is given the following
dictionary as its sole argument: >
{ 'status': <exit status of maker>,
\ 'name': <maker name>,
\ 'has_next': <true if another maker follows, false otherwise> }
*neomake#Sh* (command[, callback])
This function is called by the |:NeomakeSh| command. It runs the specified
shell `command` according to 'shell'. |neomake#Sh| returns the single job id
that was created (-1 on Vim without asynchronous support); you can potentially
cancel this job with |neomake#CancelJob|.
It also accepts a second, optional callback argument that is called when
the command exits. The callback is given the following dictionary as its
sole argument: >
{ 'status': <exit status of command>,
\ 'name': 'sh: <command>',
\ 'has_next': false }
*neomake#ListJobs*
Invoked via |:NeomakeListJobs|. Echoes a list of running jobs in the format
(job_id, job_name).
*neomake#CancelJob*
Invoked via |:NeomakeCancelJob|. Terminate a job identified by its job_id.
Example: >
let job_id = neomake#Sh("bash -c 'while true; do sleep 1; done'")
call neomake#CancelJob(job_id)
*neomake#signs#RedefineErrorSign*
*neomake#signs#RedefineWarningSign*
These functions define the error sign and the warning sign respectively. They
optionally take a dictionary in the same format as |g:neomake_error_sign|. If
no such dictionary is provided, the default values will be used. These
functions may be useful if somehow |:Neomake| is being invoked before you
define |g:neomake_error_sign|. >
let g:neomake_error_sign = {'text': 'D:'}
call neomake#signs#RedefineErrorSign()
<
*neomake-statusline*
*neomake#statusline#LoclistStatus*
*neomake#statusline#QflistStatus*
These functions return text for your |'statusline'|. They each take an
optional first argument, which is the prefix text that will be shown if errors
or warnings exist. Example usage: >
set statusline+=\ %#ErrorMsg#%{neomake#statusline#QflistStatus('qf:\ ')}
<
The result of this will be something like 'qf: E:1, W:2' if there are errors
or warnings and the empty string otherwise.
*neomake#statusline#LoclistCounts*
*neomake#statusline#QflistCounts*
These functions get the counts of errors by error type for the |location-list|
and the |quickfix| respectively. The return value is something like this: >
{'E': 2, 'W': 1, 'x': 5}
<Where 'E', 'W' and 'x' are error types. Empty error types are ignored for
now.
By default, `LoclistCounts` returns the counts for the current buffer (i.e.
`bufnr("%")`), but you can pass an optional argument: passing a buffer number
will retrieve the counts for a particular buffer, while passing the string
"`all`" will return a dictionary of counts for all buffers.
*neomake#ProcessCurrentWindow*
This is the function that takes the job output and puts it into the
|location-list| or |quickfix| list, adds signs, etc. Currently, if you stay in
the window you called |:Neomake| from, this will happen as the job output
comes in. However, if you go to a different window, Neomake will wait until
you return to that window for the job output to be processed. Currently, that
will happen on |WinEnter| and |CursorHold|. You can also call this function
directly if you need to force it. This function is not currently used for
|:Neomake!|, which always processes its output as it arrives.
==============================================================================
5. Autocommands *neomake-autocmds*
Neomake will trigger |User| autocommands on certain events. With all these
events a dictionary `g:neomake_hook_context` will be set, with key/value pairs
depending on the autocommand.
You can register your own function as a callback like this: >
augroup my_neomake
au!
autocmd User NeomakeFinished call OnNeomakeFinished()
augroup END
<
*NeomakeFinished*
The NeomakeFinished autocommand is triggered after all jobs for a call to
|:Neomake| etc have finished. This can be used to e.g. close an empty
location or quickfix window.
For this event `g:neomake_hook_context.file_mode` and
`g:neomake_hook_context.make_id` will be set.
*NeomakeCountsChanged*
The NeomakeCountsChanged autocommand is triggered after counts for the
location/quickfix list have changed, i.e. the list got reset or new errors
have been added. This can be used to e.g. update the statusline.
For this event `g:neomake_hook_context.file_mode` and
`g:neomake_hook_context.bufnr` will be set. If counts changed because of a
maker's output being processed, the maker object itself will be passed in
(which also has these attributes).
*NeomakeJobFinished*
The NeomakeJobFinished autocommand is triggered after a single job has
finished.
For this event `g:neomake_hook_context.jobinfo` will be set, where `exit_code`
is available.
==============================================================================
6. Frequently Asked Questions (FAQ) *neomake-faq*
6.1 Other plugins overwrite the signs placed by Neomake~
When using quickfixsigns (https://github.com/tomtom/quickfixsigns_vim/) it
will also place signs for errors and warnings in the quickfix/location list,
and conflicts therefore with Neomake's own signs (see
|g:neomake_place_signs|). You can make quickfixsigns respect Neomake's signs
using this option: >
let g:quickfixsigns_protect_sign_rx = '^neomake_'
<
6.2 How to configure the makers to be used?~
See |g:neomake_<ft>_enabled_makers| (press `<C-]>` on the link to go there).
6.3 How to develop/debug the errorformat setting?~
Here are some tips to develop the 'errorformat' setting for makers:
1. Get the output from the linter into a buffer (see also |:read!|).
2. Set the errorformat, e.g. `:let &efm = '%E%f:%l:%c\,%n: %m,%Z%m`.
3. Load the buffer into the quickfix list: `:cgetbuffer`.
4. Use `:echo getqflist()` to display the raw data.
5. Pay attention to the "`valid`" property of entries. Invalid entries are
currently removed by default in Neomake, but that is supposed to change
likely: it is better to ignore them through the |'errorformat'| already.
vim: ft=help tw=78 isk+=<,>,\:,-