sponsor Vim development Vim logo Vim Book Ad

vimmake : Customize shell tools for vim (supports async jobs)

 script karma  Rating 51/18, Downloaded by 598    Comments, bugs, improvements  Vim wiki

created by
Wei Lin
script type
Customize shell tools for vim. Similar to 'Run Commands' in NotePad++, 'User Tool' in EditPlus/UltraEdit, 'External Tool' in GEdit and 'Shell Commands' in TextMate.

Homepage for latest version and full document please visit: https://github.com/skywind3000/vimmake

This plugin is inspired by GEdit's External Tool which enables you to compile and run your project in a efficient way. Each tool is a single shell script defined by user which can be used to execute Makefile or compile/run a single file with customizable compile flags and run options.

Vim has numerous community plugins for building or running programs, and I have tried some. Most of them are really great in certain extent but still cannot fully satisfy my need. Therefore I decided to reference their packages and make my own.


- Customize user tool to invoke compiler or other tools with current file or directory.
- Tools can be created as a single shell script in unix like system or a batch file in windows (.cmd/.bat).
- Tools can be launched by :VimTool {name} with given system environment variables
- Launch mode can be configured as sync, async or silent (run in background and discard output).
- Output can be captured and display in the quickfix window in realtime.
- Ex-command :VimTool {name} and :VimStop can be binded to your favorite keymaps.
- Error output can be matched in quickfix window.
- Simple and lightweight.


Create a single shell script ~/.vim/vimmake.gcc in ~/.vim:

#! /bin/sh

After changing file mode to 0755, you can launch it inside vim with the command ":VimTool gcc".

Command ":VimTool {name}" will launch the script "vimmake.{name}" in the directory of "~/.vim" with the predefined environment variables:

$VIM_FILEPATH    - File name of current buffer with full path
$VIM_FILENAME    - File name of current buffer without path
$VIM_FILEDIR     - Full path of current buffer without the file name
$VIM_FILEEXT     - File extension of current buffer
$VIM_FILENOEXT   - File name of current buffer without path and extension
$VIM_CWD         - Current directory
$VIM_RELDIR      - File path relativize to current directory
$VIM_RELNAME     - File name relativize to current directory
$VIM_CWORD       - Current word under cursor in the buffer
$VIM_GUI         - Is running under gui ?
$VIM_VERSION     - Value of v:version
$VIM_MODE        - Execute via 0:!, 1:makeprg, 2:system()
$VIM_SCRIPT      - Home path of tool scripts
$VIM_TARGET      - Target given after name as ":VimTool {name} {target}"

You can setup as many tools as you wish to build your project makefile, or compile/run a single source file directly, or compile your latex, or run grep in current directory, passing current word under cursor to external man help / dictionary / other external scripts, or just call svn diff with current file and redirect the output to the bottom panel.

Command ":VimTool {name} {target}" will pass {target} in the system environment variable as $VIM_TARGET. Script can use this value as build target and pass as a parameter of gnumake.

VimStop - stop the user tool in background

This command will stop the current async building job.


Edit your .vimrc to configurate vimmake in details:

g:vimmake_mode (dictionary) - launch mode

Setup launch mode to indicate how to execute the tools:

let g:vimmake_mode = {}
let g:vimmake_mode['gcc'] = 'async'
let g:vimmake_mode['run'] = 'normal'

Launch mode can be one of these:

normal    - Default, launch the tool and return to vim after exit
quickfix  - Launch and redirect output to quickfix window
bg        - Launch in background and discard any output
async     - Run in async mode and redirect output to quickfix in realtime

Default value of g:vimmake_mode is {} which means all the tool will be launched in normal mode. Normal in windows version of gvim will launch the tool in a new cmd window by using !start.

To open a new terminal window and execute your tool in ubuntu, you may invoke gnome-terminal in the tool script and launch the script in bg mode. In Mac OS X, open can be used to open a terminal window and run the given script.

Vim 7.4.1829 is required for using async mode.

Output can be viewed in quickfix window, to open the quickfix window, you can use :copen 8 or :botright copen 8 to open quickfix window in different position. See :help quickfix for detail.

g:vimmake_path (string) - tool path

This option allows you to change the home directory of tools rather than "~/.vim/".

let g:vimmake_path = '/home/myname/github/config/tools'
Now :VimTool {name} will launch vimmake.{name} from "/home/myname/github/config/tools".

g:vimmake_save (int) - save before launch ?

It can be set to 1 if you want to save current file before execute a tool.

g:vimmake_build_scroll (int) - auto-scroll quickfix ?

When it is set to 1 for async building, quickfix window will scroll to last line automaticly if there is a new output line added to quickfix.

g:vimmake_build_post (string) - post vim commands

When async building job is finished, script in g:vimmake_build_post will be executed. It can be used to invoke a external program:

let g:vimmake_build_post = "silent !afplay ~/.vim/notify.wav"
Now ~/.vim/notify.wav will be played to notify you the async job is finished now.

Visit https://github.com/skywind3000/vimmake for more details.
install details
Copy vimmake.vim to your ~/.vim/plugin or use Vundle to install it from skywind3000/vimmake.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
vimmake.vim 1.1.2 2018-04-18 7.4 Wei Lin new: can take a range of text in current buffer as job's stdin.
vimmake.vim 1.1.1 2018-04-16 7.4 Wei Lin new option `g:vimmake_build_wrapper` to enable setup a command prefix
vimmake.vim 1.1.0 2018-04-16 7.4 Wei Lin handle makeprg/grepprg correctly, accept `%` and `$*` macros.
vimmake.vim 1.0.9 2018-04-13 7.4 Wei Lin Remove trailing ^M in quickfix when running on windows.
vimmake.vim 1.0.8 2018-04-03 7.4 Wei Lin improve old vim compatibility
vimmake.vim 1.0.7 2018-03-12 7.4 Wei Lin new option "g:vimmake_open" to open quickfix automatically.
vimmake.vim 1.0.6 2018-03-05 7.4 Wei Lin fixed: floating point issue
vimmake.vim 1.0.5 2018-02-08 7.4 Wei Lin fixed: Incorrect background job status (by  antoinemadec).
vimmake.vim 1.0.4 2017-12-13 7.4 Wei Lin new option: g:vimmake_build_skip to disable specific autocmd
vimmake.vim 1.0.3 2017-12-11 7.4 Wei Lin fixed: windo breaks commands and visual selection
vimmake.vim 1.0.2 2017-08-06 7.4 Wei Lin process will hang when mode is 5
vimmake.vim 1.0.1 2017-08-01 7.4 Wei Lin minor bugs fix
vimmake.vim 1.0.0 2017-08-01 7.4 Wei Lin stable version.
vimmake.vim 0.0.3 2016-09-19 7.4 Wei Lin fixed quickfix window toggling issue and add macros
vimmake.vim 0.0.2 2016-09-04 7.4 Wei Lin improve argument parsing
vimmake.vim 0.0.1 2016-08-30 7.4 Wei Lin fixed arguments parsing issue
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
SourceForge.net Logo