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.
