Version 2.0 &authors; &legal;

This section contains a brief howto of what to do to package a &vim; addon (plugin, syntax definition, ...) in &debian;. This section is not the full policy nor the guidelines for doing that; have a look at the remainder of this document for such information. So you've found on vim.org a cool extra feature for your beloved editor (&vim;) and you want it to be packaged in &debian;. It's as easy as implementing the following 4 steps: create an architecture: all .deb binary package called vim-ADDON, where ADDON is the addon name. See for more info on this. make your package ship all the files composing your addon (usually .vim and .txt files) under /usr/share/vim-ADDON/. The files should be shipped as a file and directory tree isomorphic to what you want to see in a runtime &vim; directory. So if for example the addon documentation says that something should be installed as plugin/foo.vim then you should ship it as /usr/share/vim-ADDON/plugin/foo.vim. See for more info on this. create a debian/vim-ADDON.vim-addon specifying the files and/or directories making up the addon. If neovim is also supported, create a corresponding debian/vim-ADDON.neovim-addon for it, or a symlink if the same set of files are used. See the dh_vim-addon manual page, in the dh-vim-addon package, for more details. add Depends: ${vim-addon:Depends} to the binary package stanzas. That's it! Easy, isn't it?

Here you can find a brief overview of how the &vim; editor is packaged in &debian; and a few concepts useful later; if you are just interested in the guidelines for packaging addons skip to . The &vim; editor is split in &debian; as several binary packages. The key splitting is according to variants, a &vim; variant is a particular version of the /usr/bin/vim executable built with a given set of (configure) option. Examples of variants provided in &debian; are: vim-tiny, vim, vim-nox, vim-gtk3. Have a look at their full descriptions for their characteristics. The actual /usr/bin/vim file is managed via the alternative mechanism and point to one of the variants. Another relevant binary package is vim-runtime which ships the &vim; runtime environment distributed upstream together with the editor. Almost all third party extensions to &vim; come as additional pieces of this runtime environment, how to package them is the main topic of this document. To be working properly extensions should be located somewhere where &vim; can find them. This "somewhere" is expressed in &vim; as a list of directories to be looked for in turn when looking for extensions. Such a list is the &vim; runtime path, and is kept in the &vim; global variable runtimepath; you can inspect it executing :set runtimepath? inside &vim;. See :help 'runtimepath' in the &vim; online help for more information, including the relevant subdirectories which &vim; will look for inside each component of the runtime path. &vim; also has a concept of packages. A package must follow a specific directory structure and be located in one of the directories defined in the packpath option. Within each package, there are two relevant directories: start All addons in this directory will automatically be added to runtimepath and loaded like any other addon that comes with &vim;. These are called automatic addons. opt Any addons in this directory must explicitly be enabled by executing :packadd! ADDON in the user's vimrc. These are called optional addons.

With the term (&vim;) addon we refer to an extension for the &vim; editor which is not shipped with the editor itself. Examples of addons which can be frequently found on the Internet are color schemes, syntax and corresponding higlighting definitions for new languages, indentation definitions, generic and filetype-specific plugins, ...

An addon is usually composed of a set of .vim files; other kind of files, for example .txt files for documentation purposes, can be provided as well. For instance, the following files compose the vcscommand addon, providing plugins, syntax higlighting definitions, and documentation: doc/tags doc/vcscommand.txt plugin/vcsbzr.vim plugin/vcscommand.vim plugin/vcscvs.vim plugin/vcsgit.vim plugin/vcshg.vim plugin/vcssvk.vim plugin/vcssvn.vim syntax/cvsannotate.vim syntax/gitannotate.vim syntax/hgannotate.vim syntax/svkannotate.vim syntax/svnannotate.vim syntax/vcscommit.vim For an addon to work properly (and its plugins being automatically loaded by &vim;) all its files should be installed under a unique directory which will be added to &vim;'s pack path. In the example above, if /usr/share/vim-vcscommand/ is the chosen directory, then SVNAnnotate.vim should be installed as /usr/share/vim-vcscommand/syntax/SVNAnnotate.vim, vcssvn.vim as /usr/share/vim-vcscommand/plugin/vcssvn.vim, and so on.

Each addon should be packaged and distributed in &debian; as a separate package. It is recommended that the package is named according to the naming convention vim-ADDON where ADDON is a name identifying the packaged addon. Each binary package should contain a single addon installed as an automatic addon. If the addon requires heavy customization or is noticeably intrusive, it may be preferable to install it as an optional addon. In some cases, it may make sense to aggregate multiple &vim; addons in a single &debian; package. An example of such a suite is distributed as the vim-scripts package. In such cases, the addons should be installed as optional addons so the user can choose which ones to enable.

dh_vim-addons is the tool used by maintainers to install &vim; addons into the appropriate runtime path. It is shipped in the dh-vim-addon package. It will ensure that the addons are installed in to the correct packpath, based on whether it is an automatic or optional addon, and which editors are supported.