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 Sun Jun 16 16:11:23 CEST 2024.