perl-policy.xml

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