perl-policy.sgml

   1 <!doctype debiandoc system>
   2
   3 <debiandoc>
   4   <book>
   5     <titlepag>
   6       <title>Debian Perl Policy</title>
   7       <author>
   8         <name>Rapha&euml;l Hertzog</name>
   9       </author>
  10       <author>
  11         <name>Brendan O'Dea</name>
  12       </author>
  13       <author>
  14         <name>The Debian Policy mailing list</name>
  15         <email>debian-policy@lists.debian.org</email>
  16       </author>
  17       <version>version 1.20</version>
  18
  19       <abstract>
  20         This document describes the packaging of Perl within the Debian
  21         GNU/Linux distribution and the policy requirements for packaged
  22         Perl programs and modules.
  23       </abstract>
  24
  25       <copyright>
  26         <copyrightsummary>
  27           Copyright &copy; 1999, 2001 Software in the Public Interest
  28         </copyrightsummary>
  29         <p>
  30           This manual is free software; you can redistribute it and/or
  31           modify it under the terms of the GNU General Public License
  32           as published by the Free Software Foundation; either version
  33           2 of the License, or (at your option) any later version.
  34         </p>
  35         <p>
  36           This is distributed in the hope that it will be useful, but
  37           WITHOUT ANY WARRANTY; without even the implied warranty of
  38           MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
  39           the GNU General Public License for more details.
  40         </p>
  41         <p>
  42           A copy of the GNU General Public License is available as
  43           <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
  44           distribution or on the World Wide Web at
  45           <url id="http://www.gnu.org/copyleft/gpl.html"
  46           name="The GNU Public Licence">.
  47         </p>
  48         <p>
  49           You can also obtain it by writing to the
  50           Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  51           Boston, MA 02111-1307, USA.
  52         </p>
  53       </copyright>
  54     </titlepag>
  55
  56     <toc detail="sect">
  57
  58     <chapt>
  59       <heading>About this document</heading>
  60       <p>
  61         This document is distributed as the <tt>perl-policy</tt> files
  62         in the Debian package
  63         <package><url name="debian-policy" id="http://packages.debian.org/debian-policy"></package>.
  64         It is also available from the Debian web mirrors at
  65         <tt><url name="/doc/packaging-manuals/perl-policy/"
  66                 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
  67       </p>
  68     </chapt>
  69
  70     <chapt id="perl">
  71       <heading>Perl Packaging</heading>
  72       <sect id="versions">
  73         <heading>Versions</heading>
  74         <p>
  75           At any given time, the package <package>perl</package> should
  76           represent the current stable upstream version of Perl revision
  77           5 (see <ref id="perl6">).
  78         </p>
  79         <p>
  80           Only one package may contain the <file>/usr/bin/perl</file>
  81           binary and that package must either be <package>perl</package>
  82           or a dependency of that package (see <ref id="base">).
  83         </p>
  84         <p>
  85           Where possible, Perl should be compiled to provide binary
  86           compatibility to at least the last released package version to
  87           allow a grace period over which binary module packages may be
  88           re-built against the new package (see <ref id="binary_modules">).
  89         </p>
  90         <p>
  91           The <package>perl-base</package> package must provide
  92           <package>perlapi-<var>version</var></package> for all released
  93           versions it is compatible with.
  94         </p>
  95       </sect>
  96
  97       <sect id="base">
  98         <heading>Base Package</heading>
  99         <p>
 100           In order to provide a minimal installation of Perl for use by
 101           applications without requiring the whole of Perl to be
 102           installed, the <package>perl-base</package> package contains
 103           the binary and a basic set of modules.
 104         </p>
 105         <p>
 106           As Perl is currently used by such things as
 107           <file>update-alternatives</file> and some package maintainer
 108           scripts, it must be priority <em>required</em> and marked as
 109           <em>essential</em>.
 110         </p>
 111         <p>
 112           Note that the <package>perl-base</package> package is intended
 113           only to provide for exceptional circumstances and the contents
 114           may change.  In general only packages which form part of the
 115           base system should declare a dependency on
 116           <package>perl-base</package> rather than
 117           <package>perl</package>.
 118         </p>
 119       </sect>
 120
 121       <sect id="paths">
 122         <heading>Module Path</heading>
 123         <p>
 124           Perl searches three different locations for modules, referred
 125           to in this document as <var>core</var> in which modules
 126           distributed with Perl are installed, <var>vendor</var> for
 127           packaged modules and <var>site</var> for modules installed by
 128           the local administrator.
 129         </p>
 130         <p>
 131           The module search path (<tt>@INC</tt>) in the Debian packages
 132           has been ordered to include these locations in the following
 133           order:
 134           <taglist>
 135             <tag><var>site</var> (current)</tag>
 136             <item>
 137               <p>
 138                 Modules installed by the local administrator for the
 139                 current version of Perl (see <ref id="site">).
 140                 <example>
 141 /usr/local/lib/perl/<var>version</var>
 142 /usr/local/share/perl/<var>version</var>
 143                 </example>
 144                 Where <var>version</var> indicates the current Perl
 145                 version (<tt>$Config{version}</tt><footnote>see the
 146                 <tt>Config</tt> module</footnote>).
 147               </p>
 148             </item>
 149             <tag><var>vendor</var></tag>
 150             <item>
 151               <p>
 152                 Packaged modules (see <ref id="module_packages">).
 153                 <example>
 154 /usr/lib/perl5
 155 /usr/share/perl5
 156                 </example>
 157               </p>
 158             </item>
 159             <tag><var>core</var></tag>
 160             <item>
 161               <p>
 162                 Modules included in the core Perl distribution.
 163                 <example>
 164 /usr/lib/perl/<var>version</var>
 165 /usr/share/perl/<var>version</var>
 166                 </example>
 167               </p>
 168             </item>
 169             <tag><var>site</var> (old)</tag>
 170             <item>
 171               <p>
 172                 <var>site</var> directories (as above) for modules
 173                 installed with previously released
 174                 <package>perl</package> packages for which the current
 175                 package is binary compatible are included if present.
 176               </p>
 177             </item>
 178           </taglist>
 179           In each of the directory pairs above, the <file>lib</file>
 180           component is for binary (XS) modules, and <file>share</file>
 181           for architecture-independent (pure-perl) modules.
 182         </p>
 183       </sect>
 184
 185       <sect id="docs">
 186         <heading>Documentation</heading>
 187         <p>
 188           The POD files and manual pages which do not refer to programs
 189           may be split out into a separate <package>perl-doc</package>
 190           package.
 191         </p>
 192         <p>
 193           Manual pages distributed with Perl packages must be installed
 194           into the standard directories:
 195           <taglist>
 196             <tag>Programs</tag>
 197             <item>
 198               <p>
 199                 Manual pages for programs and scripts are installed into
 200                 <file>/usr/share/man/man1</file> with the extension
 201                 <tt>.1</tt>.
 202               </p>
 203             </item>
 204             <tag>Modules</tag>
 205             <item>
 206               <p>
 207                 Manual pages for modules are installed into
 208                 <file>/usr/share/man/man3</file> with the extension
 209                 <tt>.3perl</tt>.
 210               </p>
 211             </item>
 212           </taglist>
 213         </p>
 214       </sect>
 215     </chapt>
 216
 217     <chapt id="site">
 218       <heading>Locally Installed Modules</heading>
 219       <sect id="site_dirs">
 220         <heading>Site Directories</heading>
 221         <p>
 222           The Perl packages must provide a mechanism for the local
 223           administrator to install modules under <file>/usr/local</file>
 224           but must not create or remove those directories.
 225         </p>
 226         <p>
 227           Modules should be installed to the directories described above
 228           in <ref id="paths"> as <var>site</var> (current), programs to
 229           <file>/usr/local/bin</file> and manual pages under
 230           <file>/usr/local/man</file>.
 231         </p>
 232       </sect>
 233
 234       <sect id="site_install">
 235         <heading>Site Installation</heading>
 236         <p>
 237           The following commands should be sufficient in the majority of
 238           cases for the local administrator to install modules and must
 239           create directories as required:
 240           <example>
 241 perl Makefile.PL
 242 make install
 243           </example>
 244         </p>
 245       </sect>
 246     </chapt>
 247
 248     <chapt id="module_packages">
 249       <heading>Packaged Modules</heading>
 250       <sect id="vendor_dirs">
 251         <heading>Vendor Directories</heading>
 252         <p>
 253           The installation directory for Debian modules must be
 254           different from that for <var>core</var> and <var>site</var>
 255           modules.
 256         </p>
 257         <p>
 258           The current Perl packaging uses the <var>vendor</var>
 259           directories for this purpose, which are at present as
 260           described in <ref id="paths"> as <var>vendor</var>.
 261         </p>
 262         <p>
 263           No version subdirectory exists on these directories as the
 264           dependencies for packaged modules (see <ref id="module_deps">)
 265           should ensure that all work with the current
 266           <package>perl</package> package.
 267         </p>
 268         <p>
 269           The Perl distribution includes many modules available
 270           separately from CPAN<footnote><url
 271           id="http://www.perl.com/CPAN"></footnote>, which may have a
 272           newer version.  The intent of the <tt>@INC</tt> ordering
 273           (described in <ref id="paths">) is to allow such modules to be
 274           packaged to <var>vendor</var> which take precedence over the
 275           version in <var>core</var>.  A packaged module which shadows a
 276           <var>core</var> module in this way must be a newer version.
 277         </p>
 278         <p>
 279           Module packages must install manual pages into the standard
 280           directories (see <ref id="docs">) using the extensions
 281           <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict
 282           arises where a packaged module duplicates a <var>core</var>
 283           module.
 284         </p>
 285         <p>
 286           <file>.packlist</file> files should not be installed.
 287         </p>
 288       </sect>
 289
 290       <sect id="package_names">
 291         <heading>Module Package Names</heading>
 292         <p>
 293           Perl module packages should be named for the primary module
 294           provided.  The naming convention for module <tt>Foo::Bar</tt>
 295           is <package>libfoo-bar-perl</package>.  Packages which include
 296           multiple modules may additionally include provides for those
 297           modules using the same convention.
 298         </p>
 299       </sect>
 300
 301       <sect id="vendor_install">
 302         <heading>Vendor Installation</heading>
 303         <p>
 304           A module should use the following lines in the
 305           <file>debian/rules</file> <tt>build</tt>
 306           target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
 307           may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
 308           cases where <file>Makefile.PL</file> is not invoked directly
 309           from <file>debian/rules</file></footnote>:
 310           <example>
 311 perl Makefile.PL INSTALLDIRS=vendor
 312 $(MAKE) OPTIMIZE="-O2 -g -Wall"
 313           </example>
 314           and this one to install the results into the temporary tree:
 315           <example>
 316 $(MAKE) install PREFIX=$(CURDIR)/debian/&lt;tmp&gt;/usr
 317           </example><footnote>
 318             <p>Replace &lt;tmp&gt; with the appropriate directory
 319             (nominally just tmp)</p>
 320           </footnote>
 321         </p>
 322         <p>
 323           A <tt>Build-Depends</tt> on <tt>perl (>= 5.6.0-16)</tt> is
 324           required.
 325         </p>
 326       </sect>
 327
 328       <sect id="module_deps">
 329         <heading>Module Dependencies</heading>
 330         <sect1 id="indep_modules">
 331           <heading>Architecture-Independent Modules</heading>
 332           <p>
 333             Architecture-independent modules which require
 334             <var>core</var> modules from the <package>perl</package>
 335             package must specify a dependency on that package.
 336           </p>
 337           <p>
 338             Modules which contain explicit <tt>require
 339             <var>version</var></tt> or <tt>use <var>version</var></tt>
 340             statements must specify a dependency on
 341             <package>perl</package> or <package>perl-base</package> with
 342             the minimum required version, or more simply the current
 343             version.
 344           </p>
 345           <p>
 346             In the absence of an explicit requirement,
 347             architecture-independent modules must depend on a minimum
 348             <package>perl</package> or <package>perl-base</package>
 349             version of <tt>5.6.0-16</tt> due to the changes in
 350             <tt>@INC</tt> introduced by that version.
 351           </p>
 352         </sect1>
 353
 354         <sect1 id="binary_modules">
 355           <heading>Binary Modules</heading>
 356           <p>
 357             Binary modules must specify a dependency on either
 358             <package>perl</package> or <package>perl-base</package> with
 359             a minimum version of the <package>perl</package> package
 360             used to build the module, and must additionally depend on
 361             the expansion of
 362             <package>perlapi-$Config{version}</package> using
 363             the <tt>Config</tt> module.
 364           </p>
 365         </sect1>
 366
 367         <sect1 id="dh_perl">
 368           <heading>Automating Perl Dependencies</heading>
 369           <p>
 370             Rather than hard-coding the dependencies into the control
 371             file, using a substitution such as <tt>${perl:Depends}</tt>
 372             is suggested.  This allows the dependencies to be determined
 373             as build time and written to the <file>substvars</file> file
 374             in the form
 375             <tt>perl:Depends=<var>deps</var></tt>.<footnote>
 376               <p>Please note that dependencies caused by versioned
 377               uses and on separately packaged modules are not included
 378               in this variable and must be explicitly included.</p>
 379             </footnote>
 380           </p>
 381           <p>
 382             Packages built with <prgn>debhelper</prgn> may use
 383
 384             <manref name="dh_perl" section="1"> to generate this
 385             substitution automatically.  This additionally requires a
 386             versioned <tt>Build-Depends</tt> (or
 387             <tt>Build-Depends-Indep</tt>) on <tt>debhelper (>=
 388             3.0.18)</tt>.
 389           </p>
 390         </sect1>
 391       </sect>
 392     </chapt>
 393
 394     <chapt id="programs">
 395       <heading>Perl Programs</heading>
 396       <sect id="hash_bang">
 397         <heading>Script Magic</heading>
 398         <p>
 399           All packaged perl programs must start with
 400           <tt>#!/usr/bin/perl</tt> and may append such flags as are
 401           required.
 402         </p>
 403       </sect>
 404
 405       <sect id="program_deps">
 406         <heading>Program Dependencies</heading>
 407         <p>
 408           Programs which require <var>core</var> modules from the
 409           <package>perl</package> package must specify a dependency on
 410           that package.
 411         </p>
 412         <p>
 413           Programs which contain explicit <tt>require
 414           <var>version</var></tt> or <tt>use <var>version</var></tt>
 415           statements must specify a dependency on
 416           <package>perl</package> or <package>perl-base</package> with
 417           the minimum required version, or more simply the current
 418           version.
 419         </p>
 420         <p>
 421           As with modules, packages using <prgn>debhelper</prgn> may use
 422           <manref name="dh_perl" section="1"> to automatically generate
 423           dependences (see <ref id="dh_perl">).
 424         </p>
 425       </sect>
 426     </chapt>
 427
 428     <chapt id="embed">
 429       <heading>Programs Embedding Perl</heading>
 430       <sect id="build_embedded">
 431         <heading>Building Embedded Programs</heading>
 432         <p>
 433           Programs which embed a perl interpreter must declare a
 434           <tt>Build-Depends</tt> on <package>libperl-dev</package>.
 435         </p>
 436         <p>
 437           The default linker options produced by
 438           <example>
 439 perl -MExtUtils::Embed -e ldopts
 440           </example>
 441           will link against the dynamic <tt>libperl</tt>.  If programs
 442           wish to link to the static library, then <tt>-lperl</tt>
 443           should be changed to <file>/usr/lib/libperl.a</file> in those
 444           options.
 445         </p>
 446       </sect>
 447
 448       <sect id="embedded_deps">
 449         <heading>Embedded Perl Dependencies</heading>
 450         <p>
 451           Dependencies for programs linking against the shared Perl
 452           library will be automatically created by
 453           <prgn>dpkg-shlibdeps</prgn>.  Note however that the shared
 454           perl library package only suggests
 455           <package>perl-base</package> and packages requiring any
 456           <var>core</var> modules from the <package>perl</package>
 457           package must depend upon it explicitly.
 458         </p>
 459       </sect>
 460     </chapt>
 461
 462     <appendix id="perl6">
 463       <heading>Perl 6</heading>
 464       <p>
 465         The current stable upstream version at the time of this writing
 466         is 5.6.0.  There is currently work in progress on the next major
 467         revision, although the specifications have yet to be finalised.
 468       </p>
 469       <p>
 470         It is anticipated that when Perl 6 is released it will initially
 471         be packaged as <package>perl6</package>, install the binary as
 472         <file>/usr/bin/perl6</file> and use different directories for
 473         packaged modules to <package>perl</package>:
 474         <example>
 475 /usr/lib/perl6
 476 /usr/share/perl6
 477         </example>
 478         This will allow Perl 5 and 6 packages and modules (which should
 479         be packaged as <package>libfoo-bar-perl6</package>), to co-exist
 480         for as long as required.
 481       </p>
 482       <p>
 483         At some stage in the future when Perl 6 is sufficiently mature,
 484         the package naming may be reversed such that the
 485         <package>perl</package> package contains Perl 6 and the current
 486         package becomes <package>perl5</package>.
 487       </p>
 488     </appendix>
 489   </book>
 490 </debiandoc>