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., 51 Franklin St, Fifth Floor,
  51           Boston, MA 02110-1301, 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>abiname</var></package> for all released
  93           package versions it is compatible with. The choice of
  94           <var>abiname</var> is arbitrary, but if it differs from
  95           <tt>$Config{version}</tt>, it must be specified in
  96           <tt>$Config{debian_abi}</tt>.
  97         </p>
  98       </sect>
  99
 100       <sect id="base">
 101         <heading>Base Package</heading>
 102         <p>
 103           In order to provide a minimal installation of Perl for use by
 104           applications without requiring the whole of Perl to be
 105           installed, the <package>perl-base</package> package contains
 106           the binary and a basic set of modules.
 107         </p>
 108         <p>
 109           As Perl has been part of the essential set for some time and is
 110           used without dependencies by such things as package maintainer
 111           scripts, <package>perl-base</package> must be
 112           priority <em>required</em> and marked as <em>essential</em>.
 113         </p>
 114         <p>
 115           Note that the <package>perl-base</package> package is intended
 116           only to provide for exceptional circumstances and the contents
 117           may change.  In general, only packages which form part of the
 118           base system should use only the facilities
 119           of <package>perl-base</package> rather than declaring a
 120           dependency on <package>perl</package>.
 121         </p>
 122       </sect>
 123
 124       <sect id="paths">
 125         <heading>Module Path</heading>
 126         <p>
 127           Perl searches three different locations for modules, referred
 128           to in this document as <var>core</var> in which modules
 129           distributed with Perl are installed, <var>vendor</var> for
 130           packaged modules and <var>site</var> for modules installed by
 131           the local administrator.
 132         </p>
 133         <p>
 134           The module search path (<tt>@INC</tt>) in the Debian packages
 135           has been ordered to include these locations in the following
 136           order:
 137           <taglist>
 138             <tag><var>site</var> (current)</tag>
 139             <item>
 140               <p>
 141                 Modules installed by the local administrator for the
 142                 current version of Perl (see <ref id="site">).
 143                 <example>
 144 /usr/local/lib/perl/<var>version</var>
 145 /usr/local/share/perl/<var>version</var>
 146                 </example>
 147                 Where <var>version</var> indicates the current Perl
 148                 version (<tt>$Config{version}</tt><footnote>see the
 149                 <tt>Config</tt> module</footnote>).
 150               </p>
 151             </item>
 152             <tag><var>vendor</var></tag>
 153             <item>
 154               <p>
 155                 Packaged modules (see <ref id="module_packages">).
 156                 <example>
 157 /usr/lib/perl5
 158 /usr/share/perl5
 159                 </example>
 160               </p>
 161             </item>
 162             <tag><var>core</var></tag>
 163             <item>
 164               <p>
 165                 Modules included in the core Perl distribution.
 166                 <example>
 167 /usr/lib/perl/<var>version</var>
 168 /usr/share/perl/<var>version</var>
 169                 </example>
 170               </p>
 171             </item>
 172             <tag><var>site</var> (old)</tag>
 173             <item>
 174               <p>
 175                 <var>site</var> directories (as above) for modules
 176                 installed with previously released
 177                 <package>perl</package> packages for which the current
 178                 package is binary compatible are included if present.
 179               </p>
 180             </item>
 181           </taglist>
 182           In each of the directory pairs above, the <file>lib</file>
 183           component is for binary (XS) modules, and <file>share</file>
 184           for architecture-independent (pure-perl) modules.
 185         </p>
 186       </sect>
 187
 188       <sect id="docs">
 189         <heading>Documentation</heading>
 190         <p>
 191           The POD files and manual pages which do not refer to programs
 192           may be split out into a separate <package>perl-doc</package>
 193           package.
 194         </p>
 195         <p>
 196           Manual pages distributed with Perl packages must be installed
 197           into the standard directories:
 198           <taglist>
 199             <tag>Programs</tag>
 200             <item>
 201               <p>
 202                 Manual pages for programs and scripts are installed into
 203                 <file>/usr/share/man/man1</file> with the extension
 204                 <tt>.1</tt>.
 205               </p>
 206             </item>
 207             <tag>Modules</tag>
 208             <item>
 209               <p>
 210                 Manual pages for modules are installed into
 211                 <file>/usr/share/man/man3</file> with the extension
 212                 <tt>.3perl</tt>.
 213               </p>
 214             </item>
 215           </taglist>
 216         </p>
 217       </sect>
 218     </chapt>
 219
 220     <chapt id="site">
 221       <heading>Locally Installed Modules</heading>
 222       <sect id="site_dirs">
 223         <heading>Site Directories</heading>
 224         <p>
 225           The Perl packages must provide a mechanism for the local
 226           administrator to install modules under <file>/usr/local</file>
 227           but must not create or remove those directories.
 228         </p>
 229         <p>
 230           Modules should be installed to the directories described above
 231           in <ref id="paths"> as <var>site</var> (current), programs to
 232           <file>/usr/local/bin</file> and manual pages under
 233           <file>/usr/local/man</file>.
 234         </p>
 235       </sect>
 236
 237       <sect id="site_install">
 238         <heading>Site Installation</heading>
 239         <p>
 240           The following commands should be sufficient in the majority of
 241           cases for the local administrator to install modules and must
 242           create directories as required:
 243           <example>
 244 perl Makefile.PL
 245 make install
 246           </example>
 247         </p>
 248       </sect>
 249     </chapt>
 250
 251     <chapt id="module_packages">
 252       <heading>Packaged Modules</heading>
 253       <sect id="vendor_dirs">
 254         <heading>Vendor Directories</heading>
 255         <p>
 256           The installation directory for Debian modules must be
 257           different from that for <var>core</var> and <var>site</var>
 258           modules.
 259         </p>
 260         <p>
 261           The current Perl packaging uses the <var>vendor</var>
 262           directories for this purpose, which are at present as
 263           described in <ref id="paths"> as <var>vendor</var>.
 264         </p>
 265         <p>
 266           No version subdirectory exists on these directories as the
 267           dependencies for packaged modules (see <ref id="module_deps">)
 268           should ensure that all work with the current
 269           <package>perl</package> package.
 270         </p>
 271         <p>
 272           The Perl distribution includes many modules available
 273           separately from CPAN<footnote><url
 274           id="http://www.perl.com/CPAN"></footnote>, which may have a
 275           newer version.  The intent of the <tt>@INC</tt> ordering
 276           (described in <ref id="paths">) is to allow such modules to be
 277           packaged to <var>vendor</var> which take precedence over the
 278           version in <var>core</var>.  A packaged module which shadows a
 279           <var>core</var> module in this way must be a newer version.
 280         </p>
 281         <p>
 282           Module packages must install manual pages into the standard
 283           directories (see <ref id="docs">) using the extensions
 284           <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict
 285           arises where a packaged module duplicates a <var>core</var>
 286           module.
 287         </p>
 288         <p>
 289           <file>.packlist</file> files should not be installed.
 290         </p>
 291       </sect>
 292
 293       <sect id="package_names">
 294         <heading>Module Package Names</heading>
 295         <p>
 296           Perl module packages should be named for the primary module
 297           provided.  The naming convention for module <tt>Foo::Bar</tt>
 298           is <package>libfoo-bar-perl</package>.  Packages which include
 299           multiple modules may additionally include provides for those
 300           modules using the same convention.
 301         </p>
 302       </sect>
 303
 304       <sect id="vendor_install">
 305         <heading>Vendor Installation</heading>
 306         <p>
 307           A module should use the following lines in the
 308           <file>debian/rules</file> <tt>build</tt>
 309           target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
 310           may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
 311           cases where <file>Makefile.PL</file> is not invoked directly
 312           from <file>debian/rules</file></footnote>:
 313           <example>
 314 perl Makefile.PL INSTALLDIRS=vendor
 315 $(MAKE) OPTIMIZE="-O2 -g -Wall"
 316           </example>
 317           and this one to install the results into the temporary tree:
 318           <example>
 319 $(MAKE) install DESTDIR=$(CURDIR)/debian/&lt;tmp&gt;
 320           </example><footnote>
 321             <p>Replace &lt;tmp&gt; with the appropriate directory
 322             (nominally just tmp)</p>
 323           </footnote>
 324         </p>
 325       </sect>
 326
 327       <sect id="module_deps">
 328         <heading>Module Dependencies</heading>
 329         <sect1 id="indep_modules">
 330           <heading>Architecture-Independent Modules</heading>
 331           <p>
 332             Architecture-independent modules which require
 333             <var>core</var> modules from the <package>perl</package>
 334             package must specify a dependency on that package.
 335           </p>
 336           <p>
 337             Modules which contain explicit <tt>require
 338             <var>version</var></tt> or <tt>use <var>version</var></tt>
 339             statements must specify a dependency on
 340             <package>perl</package> or <package>perl-base</package> with
 341             the minimum required version, or more simply the current
 342             version.
 343           </p>
 344         </sect1>
 345
 346         <sect1 id="binary_modules">
 347           <heading>Binary Modules</heading>
 348           <p>
 349             Binary modules must specify a dependency on either
 350             <package>perl</package> or <package>perl-base</package> with
 351             a minimum version of the <package>perl</package> package
 352             used to build the module, and must additionally depend on
 353             the expansion of
 354             <package>perlapi-$Config{debian_abi}</package> using
 355             the <tt>Config</tt> module. If <tt>$Config{debian_abi}</tt>
 356             is empty or not set, <tt>$Config{version}</tt> must be used.
 357           </p>
 358         </sect1>
 359
 360         <sect1 id="dh_perl">
 361           <heading>Automating Perl Dependencies</heading>
 362           <p>
 363             Rather than hard-coding the dependencies into the control
 364             file, using a substitution such as <tt>${perl:Depends}</tt>
 365             is suggested.  This allows the dependencies to be determined
 366             at build time and written to the <file>substvars</file> file
 367             in the form
 368             <tt>perl:Depends=<var>deps</var></tt>.<footnote>
 369               <p>Please note that dependencies caused by versioned
 370               uses and on separately packaged modules are not included
 371               in this variable and must be explicitly included.</p>
 372             </footnote>
 373           </p>
 374           <p>
 375             Packages built with <prgn>debhelper</prgn> may use
 376
 377             <manref name="dh_perl" section="1"> to generate this
 378             substitution automatically.  This additionally requires a
 379             versioned <tt>Build-Depends</tt> (or
 380             <tt>Build-Depends-Indep</tt>) on <tt>debhelper (>=
 381             3.0.18)</tt>.
 382           </p>
 383         </sect1>
 384       </sect>
 385     </chapt>
 386
 387     <chapt id="programs">
 388       <heading>Perl Programs</heading>
 389       <sect id="hash_bang">
 390         <heading>Script Magic</heading>
 391         <p>
 392           All packaged perl programs must start with
 393           <tt>#!/usr/bin/perl</tt> and may append such flags as are
 394           required.
 395         </p>
 396       </sect>
 397
 398       <sect id="program_deps">
 399         <heading>Program Dependencies</heading>
 400         <p>
 401           Programs which require <var>core</var> modules from the
 402           <package>perl</package> package must specify a dependency on
 403           that package.
 404         </p>
 405         <p>
 406           Programs which contain explicit <tt>require
 407           <var>version</var></tt> or <tt>use <var>version</var></tt>
 408           statements must specify a dependency on
 409           <package>perl</package> or <package>perl-base</package> with
 410           the minimum required version, or more simply the current
 411           version.
 412         </p>
 413         <p>
 414           As with modules, packages using <prgn>debhelper</prgn> may use
 415           <manref name="dh_perl" section="1"> to automatically generate
 416           dependences (see <ref id="dh_perl">).
 417         </p>
 418       </sect>
 419     </chapt>
 420
 421     <chapt id="embed">
 422       <heading>Programs Embedding Perl</heading>
 423       <sect id="build_embedded">
 424         <heading>Building Embedded Programs</heading>
 425         <p>
 426           Programs which embed a perl interpreter must declare a
 427           <tt>Build-Depends</tt> on <package>libperl-dev</package>.
 428         </p>
 429         <p>
 430           The default linker options produced by
 431           <example>
 432 perl -MExtUtils::Embed -e ldopts
 433           </example>
 434           will link against the dynamic <tt>libperl</tt>.  If programs
 435           wish to link to the static library, then <tt>-lperl</tt>
 436           should be changed to <file>/usr/lib/libperl.a</file> in those
 437           options.
 438         </p>
 439       </sect>
 440
 441       <sect id="embedded_deps">
 442         <heading>Embedded Perl Dependencies</heading>
 443         <p>
 444           Dependencies for programs linking against the shared Perl
 445           library will be automatically created by
 446           <prgn>dpkg-shlibdeps</prgn>.  Note however that the shared
 447           perl library package only suggests
 448           <package>perl-base</package> and packages requiring any
 449           <var>core</var> modules from the <package>perl</package>
 450           package must depend upon it explicitly.
 451         </p>
 452       </sect>
 453     </chapt>
 454
 455     <appendix id="perl6">
 456       <heading>Perl 6</heading>
 457       <p>
 458         The current stable upstream version at the time of this writing
 459         is 5.6.0.  There is currently work in progress on the next major
 460         revision, although the specifications have yet to be finalised.
 461       </p>
 462       <p>
 463         It is anticipated that when Perl 6 is released it will initially
 464         be packaged as <package>perl6</package>, install the binary as
 465         <file>/usr/bin/perl6</file> and use different directories for
 466         packaged modules to <package>perl</package>:
 467         <example>
 468 /usr/lib/perl6
 469 /usr/share/perl6
 470         </example>
 471         This will allow Perl 5 and 6 packages and modules (which should
 472         be packaged as <package>libfoo-bar-perl6</package>), to co-exist
 473         for as long as required.
 474       </p>
 475       <p>
 476         At some stage in the future when Perl 6 is sufficiently mature,
 477         the package naming may be reversed such that the
 478         <package>perl</package> package contains Perl 6 and the current
 479         package becomes <package>perl5</package>.
 480       </p>
 481     </appendix>
 482   </book>
 483 </debiandoc>
 484 <!-- Local variables: -->
 485 <!-- indent-tabs-mode: t -->
 486 <!-- End: -->