aboutsummaryrefslogtreecommitdiff

Vim MakeJob

This is a plugin for folks who think that Vim's quickfix feature is great, but who don't like how calls to :make and :grep freeze the editor. MakeJob implements asynchronous versions of the builtin commands in just a couple hundred lines of Vimscript.

Goals

  1. Implement a minimal solution for asynchronous :make and :grep. No unnecessary features.
  2. Let Vim be Vim. Use makeprg and errorformat to configure :MakeJob and the analogous grep options for :GrepJob. Use the Quickfix or Location List window to view findings.
  3. Complete feature parity with :make and :grep per the steps outlined in :help quickfix. autowrite, QuickFixCmdPre and QuickFixCmdPost, and the bang operator work as expected.

Requirements

Vim compiled with +job, +channel, and of course +quickfix.

Installation

Arch Linux

Arch Linux users can install system-wide through the vim-makejob package in the AUR, or on a per-user basis using any of the methods below.

Pathogen

cd ~/.vim/bundle git clone https://git.danielmoch.com/vim-makejob.git

Plug.vim

Plug 'https://git.danielmoch.com/vim-makejob.git'

Most other plugin managers will resemble one of these two.

Usage

The Short Version

Vim has :make and :grep. Replace those calls with :MakeJob and :GrepJob. A buffer will open showing the command output, which will be parsed into the Quickfix or LocationList window when the job completes. Bask in your newfound freedom to do as you please in Vim while MakeJob runs.

If MakeJob reports findings, use :copen to view the Quickfix window (in the case of :MakeJob), and likewise :lopen to open the LocationList for :LmakeJob. If the current buffer is showing the output of a running MakeJob, or if it spawned a running MakeJob, then <C-c> stops it. There's also :MakeJobStop to stop an arbitrary MakeJob (with command completion).

Speaking of :LmakeJob, all of the LocationList complements to the Quickfix commands are there with MakeJob, bringing the full list of commands to:

  • :MakeJob
  • :MakeJobStop
  • :LmakeJob
  • :GrepJob
  • :LgrepJob
  • :GrepaddJob
  • :LgrepaddJob

All of which work like their builtin counterparts. Those last two are admittedly a bit longer than we would probably like, but if you grep a lot you'll probably want to set a mapping for it anyway (see below).

The Less Short Version

Users of Syntastic may not be aware that Vim offers many of the same features out of the box. Here's a brief rundown.

With no prior configuration, :make will run the make program with no arguments, and populate the Quickfix list with any errors the process encounters. It's possible to change that behavior in one of two ways. The hard way is to manually use :set makeprg to change the program something else, and then use :set errorformat to configure the format of the errors to look for. This gets pretty hairy, and so we're all better off trying to avoid this in favor of the easy way: compiler plugins. Using a compiler plugin easy (ex: :compiler javac), they abstract away the work of remembering the errorformat, they're extendable, and many are already included in Vim. MakeJob uses the same compiler plugins users of Vim will be familiar with.

It's also possible to use theafter/ftplugin folder to automatically configure compilers on a per-file-type basis. An example of that trick would be to add the following to ~/.vim/after/ftplugin/python.vim:

compiler pylint

Add that and you're good to go for Python files (assuming you have a pylint compiler which hey, if you need one I've got you covered).

Additionally, if you'd like MakeJob to run a linter automatically when you write a file, then something like the following in your .vimrc will to the trick.

autocmd! BufWritePost * :LmakeJob! %<CR>

For more granular control, you can set this trigger on a per-file-type basis with something like the following:

autocmd! BufWritePost *.py :LmakeJob! %<CR>

Grep is a powerful way to search through a directory structure for a keyword. I use it all the time, which is why I've added the following mapping to my .vimrc:

nnoremap <Leader>g :GrepJob!<Space>

Finally, if you find the preview windows distracting or otherwise disruptive to your workflow, you can hide it with the following, global setting:

let g:makejob_hide_preview_window = 1

Gotchas

  1. If grepprg is set to 'internal', then Vim uses its own builtin grep command. This still works when you call :GrepJob, but not asynchronously.
  2. For simplicity, only one instance of a given executable can run at once. You can run make and pylint, but you can't run two instances of make simultaneously.

Vim Documentation

Part of the goal of MakeJob is to minimize the size of the plugin by using features Vim already offers whenever possible. To that end, if any of what foregoing discussion doesn't make sense, then take a look at the help documentation in Vim. Of particular interest will probably be the following:

  1. :h make
  2. :h makeprg
  3. :h errorformat
  4. :h compiler
  5. :h quickfix

Contributing

Pull requests are welcome, preferably via emailed output of git request-pull sent to the maintainer (see here for more information). Bug reports should also be directed to the maintainer via email.

If you aren't hosting a fork anywhere online, you can also send patches using git format-patch (see here).

License

MIT - See the LICENSE file for more information