mirror of
https://github.com/SpaceVim/SpaceVim.git
synced 2025-01-24 06:20:05 +08:00
227 lines
9.2 KiB
Plaintext
Vendored
227 lines
9.2 KiB
Plaintext
Vendored
*dispatch.txt* Asynchronous build and test dispatcher
|
|
|
|
Author: Tim Pope <http://tpo.pe/>
|
|
Repo: https://github.com/tpope/vim-dispatch
|
|
License: Same terms as Vim itself (see |license|)
|
|
|
|
INTRODUCTION *dispatch*
|
|
|
|
Leverage the power of Vim's compiler system without being constrained by
|
|
synchronicity.
|
|
|
|
COMMANDS *dispatch-commands*
|
|
|
|
*dispatch-:Make*
|
|
:Make [arguments] Using the current |:compiler| settings, dispatch a
|
|
build in the foreground. Adapter strategies vary, but
|
|
the goal is visibility without stealing focus. When
|
|
the build is complete, load the results into the
|
|
|quickfix| list and call |:cwindow|. This command is
|
|
preferred for shorter tasks like "build this file."
|
|
|
|
:Make! [arguments] Using the current compiler settings, dispatch a build
|
|
in the background. Use |:Copen| to load the results.
|
|
This command is preferred for longer tasks like "run
|
|
the entire test suite."
|
|
|
|
*dispatch-:Copen*
|
|
:Copen Load the latest build into the quickfix list and open
|
|
it with |:copen|. You may call this before the
|
|
process is finished.
|
|
|
|
:Copen! Load the latest build into the quickfix list using a
|
|
catch-all parser. This is useful when you can't tell
|
|
what went wrong.
|
|
|
|
*dispatch-:Dispatch*
|
|
:Dispatch[!] [options] {program} [arguments]
|
|
Find a compiler plugin that sets 'makeprg' to
|
|
{program} and use its 'errorformat' to dispatch a
|
|
|:Make| for the given {program} and [arguments]. If
|
|
no compiler plugin is found, the generic format
|
|
%+I%.%# is used.
|
|
|
|
:Dispatch picks a compiler by looking for either
|
|
CompilerSet makeprg={program}\ [arguments] or
|
|
CompilerSet makeprg={program} in compiler plugins.
|
|
To force a given {program} to use a given {compiler},
|
|
create ~/.vim/after/compiler/{compiler}.vim and add to
|
|
it a line like the following: >
|
|
|
|
" CompilerSet makeprg={program}
|
|
<
|
|
If you need more control, *g:dispatch_compilers* can
|
|
be set to a dictionary with commands for keys and
|
|
compiler plugins for values. Use an empty value to
|
|
skip the matched string and try again with the rest of
|
|
the command.
|
|
>
|
|
let g:dispatch_compilers = {
|
|
\ 'latex': 'tex',
|
|
\ 'bundle exec': ''}
|
|
<
|
|
You can optionally give one or more of the following
|
|
options before {program}:
|
|
|
|
-compiler=... force use of a compiler plugin
|
|
-dir=... run command in given directory
|
|
|
|
:Dispatch[!] [options] -- [arguments]
|
|
This is equivalent to |:Make| but accepts options.
|
|
|
|
*b:dispatch*
|
|
:Dispatch[!] [options] Invoke |:Dispatch| with the options, program, and
|
|
arguments found in b:dispatch. In the quickfix
|
|
window, this reruns the shown dispatch. When no other
|
|
default is found, equivalent to |:Make|.
|
|
|
|
*dispatch-:FocusDispatch*
|
|
:FocusDispatch [options] {program} [arguments]
|
|
Set a global default command for |:Dispatch| with no
|
|
arguments. Overrides |b:dispatch|.
|
|
|
|
:FocusDispatch! [options] {program} [arguments]
|
|
Set a window local default command for |:Dispatch|
|
|
with no arguments. Overrides |b:dispatch| and the
|
|
global default.
|
|
|
|
:FocusDispatch! Clear the global and window local defaults for
|
|
|:Dispatch|.
|
|
|
|
:FocusDispatch Show the task that would run when calling |:Dispatch|
|
|
with no arguments.
|
|
|
|
:0Dispatch[!] [options] Provide a range to |:Dispatch| skips any focused task
|
|
and forces |b:dispatch|.
|
|
|
|
*dispatch-:AbortDispatch*
|
|
:AbortDispatch Abort the most recent build.
|
|
|
|
:AbortDispatch {command}
|
|
Abort the most recent build of {command}.
|
|
|
|
*dispatch-:Start*
|
|
:Start [options] {command}
|
|
Start a process in a new, focused window. If
|
|
{command} and the directory for execution match a
|
|
previous :Start invocation, focus it instead, if
|
|
possible. Options:
|
|
|
|
-dir=... run command in given directory
|
|
-title=... short label for supported adapters
|
|
-wait=... when to display press enter prompt:
|
|
"always", "never", or "error"
|
|
|
|
:Start! [options] {command}
|
|
Start a process in a new, unfocused window. If
|
|
{command} and the current working directory match
|
|
previous :Start invocation, do nothing.
|
|
|
|
*b:start*
|
|
:Start[!] [options] With no arguments, |:Start| the options and command
|
|
given by |b:start|. If not set, falls back to
|
|
'shell'.
|
|
|
|
*dispatch-:Spawn*
|
|
:Spawn[!] [options] [command]
|
|
Like |:Start|, but always spawn a new process rather
|
|
than focusing an existing one. The default is always
|
|
to spawn a new 'shell'.
|
|
|
|
:0Spawn! [options]
|
|
Provide a range to |:Spawn| to spawn |b:dispatch|.
|
|
Handy for using an interactive debugger.
|
|
|
|
MAPS *dispatch-maps*
|
|
|
|
The following convenience maps are provided.
|
|
|
|
*m<CR>* |:Make|<CR>
|
|
*m<Space>* |:Make|<Space>
|
|
*m!* |:Make|!
|
|
*m?* Show 'makeprg'
|
|
*`<CR>* |:Dispatch|<CR>
|
|
*`<Space>* |:Dispatch|<Space>
|
|
*`!* |:Dispatch|!
|
|
*`?* |:FocusDispatch|<CR>
|
|
*'<CR>* |:Start|<CR>
|
|
*'<Space>* |:Start|<Space>
|
|
*'!* |:Start|!
|
|
*'?* Show |b:start|
|
|
*g'<CR>* |:Spawn|<CR>
|
|
*g'<Space>* |:Spawn|<Space>
|
|
*g'!* |:Spawn|!
|
|
*g'?* Show 'shell'
|
|
|
|
These can be disabled with
|
|
>
|
|
let g:dispatch_no_maps = 1
|
|
<
|
|
STRATEGIES *dispatch-strategies*
|
|
|
|
Strategies are listed in order of precedence. The first available one is
|
|
used. Some strategies only provide for a subset of tasks.
|
|
|
|
Disable :Make/:Dispatch or :Start/:Spawn using a given strategy by assigning
|
|
g:dispatch_no_strategyname_make or g:dispatch_no_strategyname_start,
|
|
respectively. For example, to prevent :Dispatch from ever using the Job
|
|
handler:
|
|
>
|
|
let g:dispatch_no_job_make = 1
|
|
<
|
|
Except for Tmux, which uses |VimResized|, all strategies require either |job|
|
|
support plus a file system with FIFOs (basically everything but Windows) or
|
|
|clientserver| support to do foreground makes.
|
|
|
|
Tmux ~
|
|
|
|
Foreground makes open in a small split at the bottom. The closure of the
|
|
pane triggers a |VimResized| event which loads the results into the quickfix
|
|
list.
|
|
|
|
The tmux strategy can be used from the GUI as well. Either start Vim from
|
|
inside of tmux or assign g:tmux_session. This will use a new window for
|
|
foreground makes rather than a split.
|
|
|
|
Job ~
|
|
|
|
Uses the |job| support in Vim 8 and Neovim to update the quickfix list in real
|
|
time.
|
|
|
|
GNU Screen ~
|
|
|
|
A new window is always used, since splits in GNU Screen are awkward.
|
|
|
|
Terminal ~
|
|
|
|
Uses the respective |:terminal| features of Vim and Neovim.
|
|
|
|
Windows ~
|
|
|
|
You can use either the standard cmd.exe or a cygwin shell. Both foreground
|
|
and background |:Make| invocations are started minimized to prevent focus
|
|
stealing.
|
|
|
|
iTerm ~
|
|
|
|
This strategy fires if you're in MacVim with at least one iTerm window open,
|
|
or if Vim is running in iTerm itself. Used only for |:Start|.
|
|
|
|
X11 ~
|
|
|
|
Uses g:dispatch_terminal_exec, "$TERMINAL -e", or "xterm -e". Used only for
|
|
|:Start|. Background invocations require wmctrl to be is installed (which is
|
|
used to switch the focus back to Vim).
|
|
|
|
Headless ~
|
|
|
|
Forks tasks into the background. It's working, you just can't see it. Don't
|
|
forget to check |:Copen|. The presence of this strategy means that |:Make!|
|
|
and |:Start!| will never block Vim.
|
|
|
|
Synchronous ~
|
|
|
|
When all else fails, a vanilla |:make| or |:!| is performed.
|
|
|
|
vim:tw=78:et:ft=help:norl:
|