vim"> Vim"> ]>
Debian Packaging Policy for &vim; Version 0.0.1 &authors; &legal;
&vim; Addon Packaging in a Nutshell 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/addons/. 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/addons/plugin/foo.vim. See for more info on this. create a vim-ADDON.yaml registry file for your addon and ship it as /usr/share/vim/registry/vim-ADDON.yaml. You can find documentation on how to write a registry file in and cut&paste-ready examples in . If the addon you are packaging does not provide a way to disable it consider patching it so that it is possible, put in your registry entry the appropriate disabledby field, and forward the patch upstream. Recommend: vim-addon-manager in your debian/control and write into README.Debian something like:
Dear user, this package provides the vim addon ADDON, but it is not enable per default. If you want to enable it for your user account just execute vim-addons install ADDON. Similarly, to enable it for all users of this system just execute (as root) vim-addons -w install ADDON. vim-addons is provided by the vim-addon-manager package, have a look at its manpage for more information.
See for more info on this. That's it! Easy, isn't it?
&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 . 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-perl, vim-full. 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.
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, ...
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: Files composing the <application>vcscommand</application> addon syntax/vcscommit.vim syntax/SVNAnnotate.vim syntax/CVSAnnotate.vim plugin/vcssvn.vim plugin/vcscvs.vim plugin/vcscommand.vim doc/vcscommand.txt For an addon to work properly (and its plugins being automatically loaded by &vim;) all its files should be installed under a directory which is a component of the &vim; runtime path, in the appropriate subdirectories. In the example above, if /usr/share/vim/&vim-tag;/ is the chosen component and if vcscommand should be installed there, then SVNAnnotate.vim should be installed as /usr/share/vim/&vim-tag;/syntax/SVNAnnotate.vim, vcssvn.vim as /usr/share/vim/&vim-tag;/plugin/vcssvn.vim, and so on. Addons should not be installed directly under a directory contained in the &vim; runtime path. This is because addons can conflict with each other and also because automatically loading plugins takes time. Therefore users shall be given the freedom to choose which addons they want to have enabled and which they don't. The suggested directory where to install addons is /usr/share/vim/addons, but any other directory not in the &vim; runtime path will do, as long as you install there a file tree with the appropriate sub-directories in place (syntax/, plugin/, ...).
Addon Packages Each non-trivial addon meaning with "non-trivial" that its size justifies the creation of a &debian; package for that, YMMV 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. Trivial addons should be collected in suites of &vim; addons and packaged as aggregated &debian; packages. An example of such a suite is distributed as the vim-script package. To ease management of addons (e.g. enabling and disabling them) by both the final users and the local system administrators, each packaged addon should be registered in the &vim; addon registry. The registry is (conceptually) a set of entries, one entry per addon, describing the addon from the point of view of who should configure it: its name and brief description, where it is located on disk, ... All such information should be easily findable in the upstream documentation of the addon. Practically, each &debian; package shipping &vim; addons should provide a single file in YAML format describing all addons shipped by the package. The file should be installed by the package in /usr/share/vim/registry/ and should be named according to the convention PKGNAME.yaml, where PKGNAME is the name of the &debian; package shipping it. There is no need to create the file in postinst, you can ship it normally as a file contained in a your package. In the future we might provide a debhelper to installed &vim; registry files in the right place, but it is not available yet.
Registry Entries The following information should be made available for each addon registered in the addon registry: name (required field) short name of the addon, will be used to refer to the addon (also in command line tools, so beware of spaces, they can be annoying) description (required field) brief description of the addon, in the same spirit of &debian; package short descriptions files (required field) list of files which compose the addon. Intuitively all these files should be made available in the appropriate components of the &vim; runtime path for the addon to be working properly. Each file must be specified relative to a component of the &vim; runtime path. basedir (optional field, default: /usr/share/vim/addons) directory where the files composing the addon reside on the filesystem. This field is optional. disabledby (optional field) &vim; script command that can be used (usually by adding it to ~/.vimrc) to prevent the addon to be used even when it is loaded. The intended usage of this field is to "blacklist" an undesired addon which files are available, and hence automatically loaded by &vim;, in a component of the &vim; runtime path. This field is optional, if missing the addon cannot be blacklisted. Note the relevance of the disabledby field: having it is the only way for a user to prevent the automatic loading of an addon which has been installed system-wide by the local system administrator. If the addon you are packaging does not provide a way to be disabled you should patch it to support disabling and forward your patch upstream. Have a look at the &debian;-specific patches in the vim-scripts package for an idea about how to do it. A YAML file describing registry entries is a standard YAML file with multiple top-level entries (one per registry entry). All field mentioned above are singleton string fields with the exception of files which contains a list of strings (one for each shipped file). See the YAML file format specification for reference ... or the examples of to learn by example. You should not attempt to automatically enable the plugin in the postinst for the reasons mentioned above. It is recommended that enabling of addons should be delegated to the local system administrator and users. If you really feel the need to, please consider using debconf as a way to opt-out from the automatic enabling, and do that strictly using vim-addon-manager (see ), so that users can blacklist the automatically loaded addon.
Tools vim-addons is the tool used by users and local administrator to manage &vim; addons. It is shipped in the vim-addon-manager package. Using it the state of an addon can be changed to one of installed, removed, disabled (i.e. prevented to be loaded even if available somewhere in the &vim; runtime path). The state of each addon can be changed both for a single user (playing with symbolic links in ~/.vim) and for all system users (via /var/lib/vim/addons/, which is contained in the &vim; runtime path). For more information about vim-addons see its manpage: vim-addons(1). Since vim-addons is the recommended way of managing &vim; addons available in a &debian; system, you should instruct your package users about it. You should hence put a Recommend: vim-addon-manager to your addon package and provide a suitable README.Debian with basic instructions about how to use it. See for a template where to start from.
&vim; Registry Entry Examples Here you can find several examples of YAML files containing entries for the &vim; addon registry. <filename>vim-runtime.yaml</filename>: entry for the matchit plugin The vim-runtime package itself ships an addon: the matchit plugin. It is rather standard as it ships its content under /usr/share/vim/addons and has no way to be prevented from being loaded. The content of /usr/share/vim/registry/vim-runtime.yaml follows. addon: matchit description: extended matching with "%" (e.g. if ... then ... else) files: - plugin/matchit.vim - doc/matchit.txt <filename>vim-scripts.yaml</filename>: entries for the &vim; scripts addon suite The vim-scripts package ships a suite of several addons, for each shipped addon an entry for the addon registry is provided. Since the shipped addons are not installed in the default addon directories the basedir field should be specified. Several addons provide a way for being blacklisted, for example the alternatve addon can be disabled by adding the line let loaded_alternateFile = 1 somewhere in ~/.vimrc. (Part of) the content of /usr/share/vim/registry/vim-scripts.yaml follows. addon: alternate description: "alternate pairing files (e.g. .c/.h) with short ex-commands" basedir: /usr/share/vim-scripts/ disabledby: "let loaded_alternateFile = 1" files: - plugin/a.vim - doc/alternate.txt --- addon: gnupg description: "transparent editing of gpg encrypted files" basedir: /usr/share/vim-scripts/ disabledby: "let loaded_gnupg = 1" files: - plugin/gnupg.vim --- addon: align description: "commands and maps for aligned text, equations, declarations, ..." basedir: /usr/share/vim-scripts/ disabledby: "let loaded_alignPlugin = 1" files: - plugin/AlignPlugin.vim - doc/Align.txt - plugin/AlignMaps.vim - plugin/cecutil.vim - autoload/Align.vim --- addon: themes description: "colors sampler pack: all the color schemes on vim.sf.net" basedir: /usr/share/vim-scripts/ disabledby: "let loaded_themes = 1" files: - plugin/themes.vim - colors/adam.vim - colors/adaryn.vim # long list snipped here <filename>vim-latexsuite.yaml</filename>: entries for the &vim; LaTeX suite The vim-latexsuite contains several advanced features for editing LaTeX documents with &vim;. (Part of) the content of /usr/share/vim/registry/vim-latexsuite.yaml follows. addon: latex-suite description: "comprehensive set of tools to view, edit, and compile LaTeX documents" disabledby: "let did_latexSuite_disabled = 1" files: - compiler/tex.vim - doc/imaps.txt.gz - doc/latexhelp.txt.gz - doc/latex-suite-quickstart.txt.gz - doc/latex-suite.txt.gz - ftplugin/bib_latexSuite.vim - ftplugin/latex-suite/bibtex.vim # loooong file listing snipped here - ftplugin/tex_latexSuite.vim - ftplugin/tex/texviewer.vim - indent/tex.vim - plugin/filebrowser.vim - plugin/imaps.vim - plugin/libList.vim - plugin/remoteOpen.vim - plugin/SyntaxFolds.vim