Installing Vim Scripts
From InstallationWiki
| Official Page |
| Project Documentation |
| Download |
|
Contents |
[edit] Installing Scripts
When you download scripts, they typically come in one of the three formats:
- As a single
.vimscript file - As a compressed (typically Zip) file that typically contains one or more
.vimfiles (both global and file-type dependent) and documentation. - As a vimball, which is an automatic Vim script installation written in Vim.
If the script you want to install is just a Vim script file, then normally all it takes to install it is to copy it to the VIMHOME/plugin directory or VIMHOME/ftplugin if it is a file-type-dependent script.
If you are on a multi-user system, you can install it for all users at the same time by installing it in directories with the same names, but instead of in your VIMHOME, located where Vim is installed on your system.
If the script comes in a compressed file instead, it can be hard to tell how to install it. Typically, you will simply have to place the file in your VIMHOME and then uncompress it there. This normally places the files in the right folders according to how Vim wants them. In any case, there might be a README or INSTALL file where you can read how to install the script.
| If you have found the script on the online Vim Community at http://www.vim.org, then you will find instructions for installation on the page that describes the script. |
The third and last way to install Vim scripts is by using the vimball installation system an installation system created for Vim 7 and newer. This system takes a range of files and combines them into a single Vim script archive with the extention .vba a vimball.
Before you start using vimballs, you will need to have the vimball script installed. This adds the functionality for reading and installing vimballs. As with most other scripts for Vim, you will be able to find the script on the online Vim community site.
| The latest version of the vimball script can always be found here: http://www.vim.org/scripts/script.php?script_id=1502 |
When you have the vimball script installed, you are ready to use vimballs for installing other Vim scripts.
Let's say that you have a vimball called myscript.vba and want to install it. You simply open the vimball in Vim. Vim will now tell you how to install the script. This is normally done by executing the following command:
:source %
This installs the script in the first place found in the runtimepath option in Vim. If you want to install the script elsewhere, you can do so by using the following command instead:
:UseVimball PATH
You need to replace PATH with the path to where you want Vim to install the script. Please note that some scripts only work when they are installed in the correct place.
Sometimes, you do not want to install a script unless you know what it contains. If this is the case, then the vimball script has a command that will give you a list of the files that you will get installed if you decide to install the vimball. To get the list of files in the vimball, execute the following command after you have opened the vimball in Vim:
:VimballList
If the files and directories listed are the ones you expected, then you are ready to install the file, and can then use either the :source or the :UseVimball commands to install it.
[edit] Uninstalling Scripts
There is normally no automatic way of uninstalling scripts after they are installed, and you will have to go through the files, one by one, and uninstall them manually. Having said that, the Vimball script does in fact have an uninstall mechanism.
If you remember the name of the vimball you used to install a Vim script, then you can later use this very same vimball name to uninstall the script. You just have to execute the following command in Vim:
:RmVimball VIMBALLNAME
Replace the VIMBALLNAME with the name of the vimball you used to install the script. If the script was not installed in the default place (if installed with :UseVimball), then you can add the installation path as a second argument to the command, and thereby tell the vimball script where to find the files it should remove.
:RmVimball VIMBALLNAME PATH
In order to be able to bind a vimball name to the files it needs to delete, the script will create a file called .VimballRecord in your VIMHOME. Note that if you remove this file, you will not be able to uninstall any of the vimballs you have previously installed unless you do it manually.
[edit] Additional References
- For instructions on Debugging Vim Scripts, click here
[edit] Source
The source of this content is Chapter 6: Vim Scripting of Hacking Vim by Kim Schulz (Packt Publishing, 2007).
