Debian Packaging Policy for Vim
Debian VIM Maintainers
<team+vim@tracker.debian.org>
Version 2.0
Copyright © 2007, 2008 Stefano Zacchiroli
Copyright © 2021 James McCoy
__________________________________________________________
Table of Contents
1. Vim Addon Packaging in a Nutshell
2. Vim Packaging
3. Packaging of Vim Addons
3.1. Addon Structure
3.2. Addon Packages
4. Tools
1. Vim Addon Packaging in a Nutshell
Warning
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:
1. create an architecture: all .deb binary package called
vim-ADDON, where ADDON is the addon name. See Section 3.2
for more info on this.
2. 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 Section 3.1 for more info on this.
3. 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.
4. add Depends: ${vim-addon:Depends} to the binary package
stanzas.
That's it! Easy, isn't it?
__________________________________________________________
2. Vim Packaging
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
Section 3.
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.
__________________________________________________________
3. Packaging of Vim 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, ...
__________________________________________________________
3.1. Addon Structure
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:
Example 1. Files composing the vcscommand addon
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.
__________________________________________________________
3.2. Addon Packages
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.
__________________________________________________________
4. Tools
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.
Generated by dwww version 1.15 on Thu Jun 27 22:57:03 CEST 2024.