perl-policy.sgml

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