mkvimball.vim : Create a vimball from a list of input files
| script karma |
Rating 0/0,
Downloaded by 1320 |
Comments, bugs, improvements
|
Vim wiki
|
| created by |
| Timothy Madden |
| |
| script type |
| utility |
| |
| description |
This script is intended for plugin developers.
Vimball archives (or .vmb / .vba, see vimscript #1502 for Vimball plugin) are a good way to distribute your plugin to users. They help users with plugin installation, in that users no longer need to know their runtime directory, to unpack a .zip file in there. With a vimball the plugin installation happens entirely within Vim, and all a user has to do is open the vimball file and follow the simple instruction that shows up, of executing ":source %".
They also help with plugin un-installation, when users normally need to find plugin files to be deleted, but with a vimball users can invoke one :RmVimball command
The `mkvimball` Vim script will create a vimball for your plugin from a list of input files. The files can be specified on the command line, in an environment variable, or read from the standard input. Although the script can be installed in the user runtime directory, like any vimball, it is intended primarily for use from the command line, or from a Makefile that you use with your plugin source files. So you might want to install it in your project directory, next to the Makefile or the other build files. You can also run the script with the :runtime or :source command from Vim, if you set :args beforehand the same as on the command line.
The source code repository for the project is available at http://code.google.com/p/dbgp-client/.
To run on the command line, you would need a command like:
vim -V1 -i NONE -u NORC -nNesS mkvimball -c "echo ''|qall"! -- VimballName srcfiles...
On Linux the script uses a shebang line equivalent to the above command, so if you make the script executable, with `chmod +x mkvimball`, you can run the script as follows:
./mkvimball -- VimballName srcfiles ....
On Windows there is no equivalent to the shebang line, and also Vim is not necessarily on PATH, which can make things a little complicated.
Normally the Windows file associations are used for such purpose. You can follow the wiki page at http://vim.wikia.com/wiki/Windows_file_associations, and associate a new file extension like .exim to the above command line. Here 'exim' stands for "improved ex mode', and sometimes Vim was also installed with the name `exim`, in addition to the name `vim`. The mkvimball script itself can register/unregister the a file extension, for the current user or all users, with the following command:
vim -i NONE -V1 -nNesS mkvimball -c "echo ''|qall"! -- --register-file-type { --user | --system } [.ext]
vim -i NONE -V1 -nNesS mkvimabll -c "echo ''|qall"! -- --unregister-file-type { --user | --system } [.ext]
You only need to register the file type once. The default file extension [.ext] is ".exim". After that you should rename mkvimball file to mkvimball.exim, exit current cmd.exe window, and use the `mkvimball` command normally.
However the Windows file associations are specific to the computer where they are configured, and Vim plugins on the other hand are public-domain or open-source and shared with any one who would like to get the source code to build a vimball. To use `mkvimball` with such a public audience you can use a wrapper .cmd file to invoke the full command line. The `mkvimball` script can generate a pair of such wrappers (.cmd and .js, where .js is a JScript file running with Windows Script Host WSH, and is invoked from the .cmd file), if you run it once with this command:
vim -i NONE -V1 -nNesS mkvimball -c "echo ''|qall"! -- --write-cmd-script
than you can use the `mkvimball` command normally.
The generated scripts / file association can read the Windows registry to find Vim installation directory, or search for Vim in %ProgramFiles% or %VIMRUNTIME%.
One last note about the installation: if your project uses php and you know it can be found on path, you can run the script with php, since it is a valid php file as it stands. Just use `php mkvimball VimballName scrfiles...`. Funny (or lucky), but it works, and it makes for an interesting observation ...
Next, the script relies on the standard vimballPlugin to create or list the vimball archive. The script will normally set g:vimball_home to the current directory given as '.'. If the vimball to be created already exists, it will be overwritten.
The names of files from the command line, that are found in or below the current directory, will be re-written to be relative to the current directory (as if with expand('%:.'). Nothing special about it, this is done mostly to fix some attempts by Vim to match a file name argument (from command line) with an existing buffer name upon start-up, when Vim may modify the file name arg for this purpose. But it is also a good sanity check.
To remove some parent directory component from all input file names given, set the environment variable SRC_PATH_PREFIX to the prefix to be removed. Or set g:mkvimball_src_path_prefix variable on the command line before running the script, like:
mkvimball --cmd 'let g:mkvimball_src_path_prefix="src/"' -- Vimball srcfiles...
Note that the `mkvimball` script will not read the .vimrc file, so you can not specify the variable in there.
To prevent implicit file name modification you can specify the list of files as standard input to the command, like
VIMBALL_FILES=- mkvimball -- VimballName <listfile.txt
or in the VIMBALL_FILES environment variable, like
VIMBALL_FILES="plugin/file1.vim plugin/file2.vim" mkvimball -- VimballName
The script will split the list into files around spaces in this case, or with the Vim regular expression given in g:mkvimball_delimiter_regexp variable.
To read the list of input files from standad input, set VIMBALL_FILES to the value "-" (a single dash), or for Linux systems you may also set it empty (Windows does not have empty environment variables). You should also make sure standard input ends with an empty line or with a line containing just a single dot. If the end-of-file is reached without an empty line or a dot line, Vim will stop script execution when that happens, before it can create the vimball. This is because the command line invoking the script will run Vim in ex mode (command mode) which reads Vim commands from standard input.
If you just pass a vimball file as the single argument to the script, you will get a listing of the vimball archive contents, created with :VimballList command provided by the standard vimball plugin.
Instead of running the script from the command line, you may use :source or :runtime command in a running instance of Vim, and be sure to set script arguments with the :args command as a first step. If you want to list a vimball archive in this way, you may need to use the :messages command afterwards, like this:
:arglocal
:argdelete *
:argadd VimballFileName.vba
:runtime mkvimball
:messages
:argglobal |
| |
| install details |
Open the downloaded .vba file in Vim. Vim will show a status line saying you should use ":so %" command to install the vimball.
If you downloaded the .zip file, Vim can usually open it directly, so you do not have to unpack it first.
Next you may want to cd to the directory where you want the mkvimball script installed, for example in your project directory. Than you should type
:cd ..your-project-dir...
:let g:vimball_home='.'
:source %
to unpack the script into that directory.
Otherwise, only run `:so %` and the script will be placed by default in your Vim runtime directory, usually ~/.vim/ on Linux, and %USERPROFILE%\vimfiles\ on Windows.
As the next step, you should now to the following:
- Linux: run `chmod +x ~/.vim/mkvimball`
- Windows: create a file type association or generate a wrapper script, as described above. |
| |
script versions (upload new version)
Click on the package to download.
ip used for rating: 18.223.32.230
|
