1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"/usr/share/sgml/docbook/dtd/xml/4.3/docbookx.dtd" [
<!ENTITY vim-version "8.2">
<!ENTITY vim "<application>Vim</application>">
<!ENTITY debian "Debian">
<!ENTITY authors SYSTEM "authors.xml">
<!ENTITY legal SYSTEM "legal.xml">
]>
<article>
<articleinfo>
<title>Debian Packaging Policy for &vim;</title>
<releaseinfo>Version 2.0</releaseinfo>
&authors;
&legal;
</articleinfo>
<section id="nutshell">
<title>&vim; Addon Packaging in a Nutshell</title>
<warning> <para> 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.
</para> </warning>
<para> So you've found on <ulink url="https://www.vim.org">vim.org</ulink> 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:
<orderedlist numeration="arabic">
<listitem> <para> create an <code>architecture: all</code>
<filename>.deb</filename> binary package called
<application>vim-<replaceable>ADDON</replaceable></application>,
where <replaceable>ADDON</replaceable> is the addon name. See <xref
linkend="addon-packages" /> for more info on this. </para>
</listitem>
<listitem> <para> make your package ship all the files composing your
addon (usually <filename>.vim</filename> and
<filename>.txt</filename> files) under
<filename>/usr/share/vim-<replaceable>ADDON</replaceable>/</filename>. 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
<filename>plugin/foo.vim</filename> then you should ship it as
<filename>/usr/share/vim-<replaceable>ADDON</replaceable>/plugin/foo.vim</filename>. See <xref
linkend="addon-structure" /> for more info on this. </para>
</listitem>
<listitem> <para>create a
<filename>debian/vim-<replaceable>ADDON</replaceable>.vim-addon</filename>
specifying the files and/or directories making up the addon. If neovim is also supported, create
a corresponding <filename>debian/vim-<replaceable>ADDON</replaceable>.neovim-addon</filename>
for it, or a symlink if the same set of files are used.
See the <command>dh_vim-addon</command> manual page, in the <application>dh-vim-addon</application>
package, for more details. </para> </listitem>
<listitem> <para>add <code>Depends: ${vim-addon:Depends}</code> to the binary package stanzas.</para> </listitem>
</orderedlist>
That's it! Easy, isn't it? </para>
</section>
<section id="legacy-packaging">
<title>&vim; Packaging</title>
<para> 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
<xref linkend="addon-packaging" />. </para>
<para> The &vim; editor is split in &debian; as several binary
packages. The key splitting is according to variants, a &vim;
<emphasis>variant</emphasis> is a particular version of the
<filename>/usr/bin/vim</filename> executable built with a given
set of (<application>configure</application>) option. Examples of
variants provided in &debian; are: <ulink
url="https://packages.debian.org/unstable/editors/vim-tiny"><application>vim-tiny</application></ulink>,
<ulink
url="https://packages.debian.org/unstable/editors/vim"><application>vim</application></ulink>,
<ulink
url="https://packages.debian.org/unstable/editors/vim-nox"><application>vim-nox</application></ulink>,
<ulink
url="https://packages.debian.org/unstable/editors/vim-gtk3"><application>vim-gtk3</application></ulink>.
Have a look at their full descriptions for their characteristics.
The actual <filename>/usr/bin/vim</filename> file is managed via
the alternative mechanism and point to one of the variants.
</para>
<para> Another relevant binary package is <ulink
url="https://packages.debian.org/unstable/editors/vim-runtime"><application>vim-runtime</application></ulink>
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. </para>
<para> 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 <emphasis>&vim; runtime path</emphasis>, and is kept in the
&vim; global variable <envar>runtimepath</envar>; you can inspect it
executing <command>:set runtimepath?</command> inside &vim;. See <ulink
url="https://vimhelp.org/options.txt.html#'runtimepath'"><command>:help
'runtimepath'</command></ulink> in the &vim; online help for more
information, including the relevant subdirectories which &vim; will look
for inside <emphasis>each</emphasis> component of the runtime path.
</para>
<para> &vim; also has a concept of <emphasis>packages</emphasis>. A package
must follow a specific directory structure and be located in one of the
directories defined in the <envar>packpath</envar> option. Within each
package, there are two relevant directories: <variablelist>
<varlistentry><term><emphasis>start</emphasis></term>
<listitem><para>All addons in this directory will automatically
be added to <envar>runtimepath</envar> and loaded like any other
addon that comes with &vim;. These are called
<emphasis>automatic</emphasis> addons.</para> </listitem> </varlistentry>
<varlistentry><term><emphasis>opt</emphasis></term>
<listitem><para>Any addons in this directory must explicitly
be enabled by executing <command>:packadd! <replaceable>ADDON</replaceable></command>
in the user's vimrc. These are called <emphasis>optional</emphasis> addons.
</para> </listitem> </varlistentry>
</variablelist> </para>
</section>
<section id="addon-packaging">
<title>Packaging of &vim; Addons</title>
<para> With the term (&vim;) <emphasis>addon</emphasis> 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, ... </para>
<section id="addon-structure">
<title>Addon Structure</title>
<para> An addon is usually composed of a set of <filename>.vim</filename>
files; other kind of files, for example <filename>.txt</filename> files
for documentation purposes, can be provided as well.
For instance, the following files compose the <ulink
url="https://www.vim.org/scripts/script.php?script_id=90"><application>vcscommand</application></ulink>
addon, providing plugins, syntax higlighting definitions, and
documentation:
<example> <title>Files composing the
<application>vcscommand</application> addon</title>
<programlisting>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</programlisting>
</example>
</para>
<para> 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
<filename>/usr/share/vim-vcscommand/</filename> is the chosen directory,
then <filename>SVNAnnotate.vim</filename> should be installed as
<filename>/usr/share/vim-vcscommand/syntax/SVNAnnotate.vim</filename>,
<filename>vcssvn.vim</filename> as
<filename>/usr/share/vim-vcscommand/plugin/vcssvn.vim</filename>, and so
on. </para>
</section>
<section id="addon-packages">
<title>Addon Packages</title>
<para> 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
<application>vim-<replaceable>ADDON</replaceable> </application>
where <replaceable>ADDON</replaceable> is a name identifying the
packaged addon. </para>
<para> Each binary package should contain a single addon installed as an
<emphasis>automatic</emphasis> addon. If the addon requires
heavy customization or is noticeably intrusive, it may be preferable
to install it as an <emphasis>optional</emphasis> addon.</para>
<para> 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 <ulink url="https://packages.qa.debian.org/vim-scripts">
<application>vim-scripts</application> package</ulink>.
In such cases, the addons should be installed as <emphasis>optional</emphasis>
addons so the user can choose which ones to enable. </para>
</section>
</section>
<section id="tools">
<title>Tools</title>
<para> <command>dh_vim-addons</command> is the tool used by maintainers
to install &vim; addons into the appropriate runtime path. It is shipped in the <ulink
url="https://packages.qa.debian.org/dh-vim-addon"><application>dh-vim-addon</application></ulink>
package. It will ensure that the addons are installed in to the correct
<envar>packpath</envar>, based on whether it is an <emphasis>automatic</emphasis>
or <emphasis>optional</emphasis> addon, and which editors are supported. </para>
</section>
</article>
|
