DH_VIM-ADDON(1)

NAME
dh_vim-addon - debhelper addon to help package Vim/Neovim addons

SYNOPSIS
dh_vim-addon [debhelper options]

DESCRIPTION
dh_vim-addon is a debhelper program that is responsible for installing addons for Vim/Neovim and generating the help tags file for any documentation. The addons are installed into directories following Vim's native "package" hierarchy.

There are two types of addons which are supported.

automatic
    Automatic addons are immediately enabled for users when installed. The addons should provide a standard mechansim to let the user disable the addon. This is typically done by short-circuiting loading of the addon when the user adds "let g:loaded_<addon> = 1" in their vimrc.

optional
    Optional addons are only enabled for users if the explicitly opt-in to the addon. The user can do so by adding "packadd! <addon>" to their vimrc.

FILES

debian/package.vim-addon
debian/package.neovim-addon
    List of installed directories to be setup as an automatic addon in package. The format is a set of lines, where each line lists the base directory of an addon, relative to the package build directory and, optionally, the addon name.

        B<path/to/addon/basedir>  I<optional-addon-name>

    There should typically only be a single addon, and therefore line, per package. If an addon name is not supplied, the last component of the base directory will be used as the addon name.

    If the "basedir" does not match the addon's name (e.g., because it matches the Debian package's name), then it is recommended to supply the addon name. This ensures that common conventions, like "packadd addon-name" and "let g:loaded_addon = 1" work as the user expects.

    The "${vim-addon:Depends}" substvar will be set with any required dependencies.

debian/package.vim-opt-addon
debian/package.neovim-opt-addon
    This file follows the same format as vim-addon, however the directories will be installed as optional addons in package.

    The "${vim-addon:Depends}" substvar will be set with any required dependencies.

EXAMPLES

  Single addon, dh-style
Here is an example of a simple dh(1) style package with a single addon, compatible with Vim and Neovim. The debian/rules is:

    #!/usr/bin/make -f
    %:
        dh $@ --with vim_addon

The Vim addon is installed under /usr/share/vim-simple, but the addon name is simple (i.e., "let g:loaded_simple = 1" is the expected way for a user to disable loading of the addon). The vim-addon file is:

    usr/share/vim-simple simple

debian/vim-simple.neovim-addon is a symlink to debian/vim-simple.vim-addon.

  Multiple addons, debhelper
Here is an example of a debhelper style package, providing multiple addons, some of which aren't compatible with Neovim. The debian/rules contains:

    #!/usr/bin/make -f
    ...
        # Install the files to the package build directory
        dh_install
        # Setup the (neo)vim addons
        dh_vim-addon

The addons are installed under /usr/share/vim-multi-addons. Unlike the single addon example, these addons are all installed into a directory matching the addon name, so only the base directory is needed in the vim-addon file:

    usr/share/vim-multi-addons/addon1
    usr/share/vim-multi-addons/addon2

while the neovim-addon is:

    usr/share/vim-multi-addon/addon1
    usr/share/vim-multi-addon/addon3

SEE ALSO
nvim(1), vim(1)

AUTHOR
James McCoy <jamessan@debian.org>