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 several 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 current Debian packages
 140           has been ordered to include these locations in the following
 141           order<footnote>@INC contains other paths which should be considered
 142       internal to the implementation of the perl packaging</footnote>
 143           <taglist>
 144             <tag><var>site</var> (current)</tag>
 145             <item>
 146               <p>
 147                 Modules installed by the local administrator for the
 148                 current version of Perl (see <ref id="site">).
 149                 <example>
 150 $Config{sitearch}  (currently /usr/local/lib/<var>arch-triplet</var>/perl/<var>version</var>)
 151 $Config{sitelib}   (currently /usr/local/share/perl/<var>version</var>)
 152                 </example>
 153                 Where <var>version</var> indicates the current Perl
 154                 version (<tt>$Config{version}</tt>).
 155               </p>
 156               <p>
 157                 These locations, particularly <tt>$Config{sitearch}</tt>,
 158                 may change if the binary interface between the
 159                 Perl interpreter and compiled modules has to be
 160                 changed in an incompatible way without a change in
 161                 <var>version</var>. While this will only be done as a
 162                 last resort, packages should use <tt>$Config{sitelib}</tt>
 163                 and <tt>$Config{sitearch}</tt>, not hardcode the current
 164                 locations.<footnote>Build systems based on
 165                 <tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
 166                 do this automatically.</footnote>
 167               <p>
 168             </item>
 169             <tag><var>vendor</var></tag>
 170             <item>
 171               <p>
 172                 Packaged modules (see <ref id="module_packages">).
 173                 <example>
 174 $Config{vendorarch} (currently /usr/lib/<var>arch-triplet</var>/perl5/<var>shortversion</var>)
 175 $Config{vendorlib}  (currently /usr/share/perl5)
 176                 </example>
 177                 Where <var>shortversion</var> indicates the current Perl major
 178                 version (for example <tt>5.22</tt>).
 179             </p>
 180             <p>
 181                 These locations, particularly
 182                 <tt>$Config{vendorarch}</tt>, may change if
 183                 necessary<footnote>For example, to include
 184                 the multiarch triplet</footnote>.  Packages
 185                 should use <tt>$Config{vendorlib}</tt> and
 186                 <tt>$Config{vendorarch}</tt>, not hardcode the current
 187                 locations.<footnote>Build systems based on
 188                 <tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
 189                 do this automatically.</footnote>
 190               </p>
 191             </item>
 192             <tag><var>core</var></tag>
 193             <item>
 194               <p>
 195                 Modules included in the core Perl distribution.
 196                 <example>
 197 $Config{archlib} (currently /usr/lib/<var>arch-triplet</var>/perl/<var>shortversion</var>)
 198 $Config{privlib} (currently /usr/share/perl/<var>shortversion</var>)
 199                 </example>
 200                 Where <var>shortversion</var> indicates the current Perl major
 201                 version (for example <tt>5.22</tt>).
 202               </p>
 203               <p>
 204                 These locations should be considered internal to the <package>
 205                 perl</package> source package. If necessary, packages should use
 206                 <tt>$Config{archlib}</tt> and <tt>$Config{privlib}</tt> instead of
 207                 hardcoding the current locations.<footnote>Build systems based on
 208                 <tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
 209                 do this automatically.</footnote>
 210               </p>
 211             </item>
 212             <tag><var>site</var> (old)</tag>
 213             <item>
 214               <p>
 215                 <var>site</var> directories (as above) for modules
 216                 installed with previously released
 217                 <package>perl</package> packages for which the current
 218                 package is binary compatible are included if present.
 219               </p>
 220             </item>
 221           </taglist>
 222           In each of the directory pairs above, the <file>lib</file>
 223           component is for binary (XS) modules, and <file>share</file>
 224           for architecture-independent (pure-perl) modules.
 225         </p>
 226       </sect>
 227
 228       <sect id="docs">
 229         <heading>Documentation</heading>
 230         <p>
 231           The POD files and manual pages which do not refer to programs
 232           may be split out into a separate <package>perl-doc</package>
 233           package.
 234         </p>
 235         <p>
 236           Manual pages distributed with packages built from the perl
 237           source package must be installed into the standard directories:
 238           <taglist>
 239             <tag>Programs</tag>
 240             <item>
 241               <p>
 242                 Manual pages for programs and scripts are installed into
 243                 <file>/usr/share/man/man1</file> with the extension
 244                 <tt>.1</tt>.
 245               </p>
 246             </item>
 247             <tag>Modules</tag>
 248             <item>
 249               <p>
 250                 Manual pages for modules are installed into
 251                 <file>/usr/share/man/man3</file> with the extension
 252                 <tt>.3perl</tt>.
 253               </p>
 254             </item>
 255           </taglist>
 256           The extensions used for manual pages distributed with module
 257           packages are different.  See <ref id="vendor_dirs">.
 258         </p>
 259       </sect>
 260     </chapt>
 261
 262     <chapt id="site">
 263       <heading>Locally Installed Modules</heading>
 264       <sect id="site_dirs">
 265         <heading>Site Directories</heading>
 266         <p>
 267           The Perl packages must provide a mechanism for the local
 268           administrator to install modules under <file>/usr/local</file>
 269           but must not create or remove those directories.
 270         </p>
 271         <p>
 272           Modules should be installed to the directories described above
 273           in <ref id="paths"> as <var>site</var> (current), programs to
 274           <file>/usr/local/bin</file> and manual pages under
 275           <file>/usr/local/man</file>.
 276         </p>
 277       </sect>
 278
 279       <sect id="site_install">
 280         <heading>Site Installation</heading>
 281         <p>
 282           The following commands should be sufficient in the majority of
 283           cases for the local administrator to install modules and must
 284           create directories as required:
 285           <example>
 286 perl Makefile.PL
 287 make install
 288           </example>
 289         </p>
 290       </sect>
 291     </chapt>
 292
 293     <chapt id="module_packages">
 294       <heading>Packaged Modules</heading>
 295       <sect id="vendor_dirs">
 296         <heading>Vendor Directories</heading>
 297         <p>
 298           The installation directory for Debian modules must be
 299           different from that for <var>core</var> and <var>site</var>
 300           modules.
 301         </p>
 302         <p>
 303           The current Perl packaging uses the <var>vendor</var>
 304           directories for this purpose, which are at present as
 305           described in <ref id="paths"> as <var>vendor</var>.
 306         </p>
 307         <p>
 308           The Perl distribution includes many modules available
 309           separately from CPAN<footnote><url
 310           id="http://www.perl.com/CPAN"></footnote>, which may have a
 311           newer version.  The intent of the <tt>@INC</tt> ordering
 312           (described in <ref id="paths">) is to allow such modules to be
 313           packaged to <var>vendor</var> which take precedence over the
 314           version in <var>core</var>.  A packaged module which shadows a
 315           <var>core</var> module in this way must be a newer version.
 316         </p>
 317         <p>
 318           Module packages must install manual pages into the standard
 319           directories (see <ref id="docs">) using the extensions
 320           <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict
 321           arises where a packaged module duplicates a <var>core</var>
 322           module.
 323         </p>
 324         <p>
 325           <file>.packlist</file> files should not be installed.
 326         </p>
 327       </sect>
 328
 329       <sect id="package_names">
 330         <heading>Module Package Names</heading>
 331         <p>
 332           Perl module packages should be named for the primary module
 333           provided.  The naming convention is to lowercase the Perl module
 334           name, prepend, <tt>lib</tt>, change all occurrences
 335           of <tt>::</tt> to <tt>-</tt>, and append <tt>-perl</tt>.  For
 336           example:
 337           <example>
 338 Foo::Bar        libfoo-bar-perl
 339 Foo::Bar::Baz   libfoo-bar-baz-perl
 340 Foo::BarBaz     libfoo-barbaz-perl
 341           </example>
 342           Packages which include multiple modules may additionally include
 343           provides for the additional modules using the same convention.
 344         </p>
 345       </sect>
 346
 347       <sect id="vendor_install">
 348         <heading>Vendor Installation</heading>
 349         <p>
 350           A module should use the following lines in the
 351           <file>debian/rules</file> <tt>build</tt>
 352           target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
 353           may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
 354           cases where <file>Makefile.PL</file> is not invoked directly
 355           from <file>debian/rules</file></footnote>:
 356           <example>
 357 perl Makefile.PL INSTALLDIRS=vendor
 358 $(MAKE) OPTIMIZE="-O2 -g -Wall"
 359           </example>
 360           and this one to install the results into the temporary tree:
 361           <example>
 362 $(MAKE) install DESTDIR=$(CURDIR)/debian/&lt;tmp&gt;
 363           </example><footnote>
 364             <p>Replace &lt;tmp&gt; with the appropriate directory
 365             (nominally just tmp)</p>
 366           </footnote>
 367         </p>
 368       </sect>
 369
 370       <sect id="module_deps">
 371         <heading>Module Dependencies</heading>
 372         <sect1 id="indep_modules">
 373           <heading>Architecture-Independent Modules</heading>
 374           <p>
 375             Architecture-independent modules which require
 376             <var>core</var> modules from the <package>perl</package>
 377             package must specify a dependency on that package.
 378           </p>
 379           <p>
 380             Modules which contain explicit <tt>require
 381             <var>version</var></tt> or <tt>use <var>version</var></tt>
 382             statements must specify a dependency on
 383             <package>perl</package> or <package>perl-base</package> with
 384             the minimum required version, or more simply the current
 385             version.
 386           </p>
 387         </sect1>
 388
 389         <sect1 id="binary_modules">
 390           <heading>Binary and Other Architecture Dependent Modules</heading>
 391           <p>
 392             Binary modules must specify a dependency on either
 393             <package>perl</package> or <package>perl-base</package> with
 394             a minimum version of the <package>perl</package> package
 395             used to build the module. Additionally, all binary modules
 396             (regardless of their installation directory) and any other modules
 397             installed into <tt>$Config{vendorarch}</tt> must depend on the
 398             expansion of <package>perlapi-$Config{debian_abi}</package> using
 399             the <tt>Config</tt> module. If <tt>$Config{debian_abi}</tt>
 400             is empty or not set, <tt>$Config{version}</tt> must be used.
 401           </p>
 402         </sect1>
 403
 404         <sect1 id="dh_perl">
 405           <heading>Automating Perl Dependencies</heading>
 406           <p>
 407             Rather than hard-coding the dependencies into the control
 408             file, using a substitution such as <tt>${perl:Depends}</tt>
 409             is suggested.  This allows the dependencies to be determined
 410             at build time and written to the <file>substvars</file> file
 411             in the form
 412             <tt>perl:Depends=<var>deps</var></tt>.<footnote>
 413               <p>Please note that dependencies caused by versioned
 414               uses and on separately packaged modules are not included
 415               in this variable and must be explicitly included.</p>
 416             </footnote>
 417           </p>
 418           <p>
 419             Packages built with <prgn>debhelper</prgn> may use
 420
 421             <manref name="dh_perl" section="1"> to generate this
 422             substitution automatically.  This additionally requires a
 423             versioned <tt>Build-Depends</tt> (or
 424             <tt>Build-Depends-Indep</tt>) on <tt>debhelper (>=
 425             3.0.18)</tt>.
 426           </p>
 427         </sect1>
 428       </sect>
 429     </chapt>
 430
 431     <chapt id="programs">
 432       <heading>Perl Programs</heading>
 433       <sect id="hash_bang">
 434         <heading>Script Magic</heading>
 435         <p>
 436           All packaged perl programs must start with
 437           <tt>#!/usr/bin/perl</tt> and may append such flags as are
 438           required.
 439         </p>
 440       </sect>
 441
 442       <sect id="program_deps">
 443         <heading>Program Dependencies</heading>
 444         <p>
 445           Programs which require <var>core</var> modules from the
 446           <package>perl</package> package must specify a dependency on
 447           that package.
 448         </p>
 449         <p>
 450           Programs which contain explicit <tt>require
 451           <var>version</var></tt> or <tt>use <var>version</var></tt>
 452           statements must specify a dependency on
 453           <package>perl</package> or <package>perl-base</package> with
 454           the minimum required version, or more simply the current
 455           version.
 456         </p>
 457         <p>
 458           As with modules, packages using <prgn>debhelper</prgn> may use
 459           <manref name="dh_perl" section="1"> to automatically generate
 460           dependences (see <ref id="dh_perl">).
 461         </p>
 462       </sect>
 463     </chapt>
 464
 465     <chapt id="embed">
 466       <heading>Programs Embedding Perl</heading>
 467       <sect id="build_embedded">
 468         <heading>Building Embedded Programs</heading>
 469         <p>
 470           Programs which embed a perl interpreter must declare a
 471           <tt>Build-Depends</tt> on <package>libperl-dev</package>.
 472         </p>
 473         <p>
 474           The default linker options produced by
 475           <example>
 476 perl -MExtUtils::Embed -e ldopts
 477           </example>
 478           will link against the dynamic <tt>libperl</tt>.  If programs
 479           wish to link to the static library, then <tt>-lperl</tt>
 480           should be changed to <file>/usr/lib/libperl.a</file> in those
 481           options.
 482         </p>
 483       </sect>
 484
 485       <sect id="embedded_deps">
 486         <heading>Embedded Perl Dependencies</heading>
 487         <p>
 488           Dependencies for programs linking against the shared Perl
 489           library will be automatically created by
 490           <prgn>dpkg-shlibdeps</prgn>.  Note however that the shared
 491           perl library package only suggests
 492           <package>perl-base</package> and packages requiring any
 493           <var>core</var> modules from the <package>perl</package>
 494           package must depend upon it explicitly.
 495         </p>
 496       </sect>
 497
 498       <sect id="perl_upgrades">
 499         <heading>Perl Package Upgrades</heading>
 500         <p>
 501           Starting from <package>perl</package> 5.12.3-2, a dpkg trigger
 502           named <var>perl-major-upgrade</var> will be triggered by the
 503           postinst of the <package>perl</package> package during major
 504           upgrades. Some examples of things which constitute a major upgrade
 505           are an upgrade which would change the value of versioned
 506           directories in <tt>@INC</tt>, or one which changes <tt>abiname</tt>.
 507           Any package may declare an interest in the trigger, especially
 508           packages including long-running daemons which would stop working
 509           until restart.
 510         </p>
 511         <p>
 512           It is suggested that such packages include an appropriate section
 513           in their postinst to handle the trigger by restarting relevant
 514           daemons or notifying users of further action.
 515         </p>
 516       </sect>
 517     </chapt>
 518
 519     <appendix id="perl6">
 520       <heading>Perl 6</heading>
 521       <p>
 522         The current stable upstream version at the time of this writing
 523         is 5.6.0.  There is currently work in progress on the next major
 524         revision, although the specifications have yet to be finalised.
 525       </p>
 526       <p>
 527         It is anticipated that when Perl 6 is released it will initially
 528         be packaged as <package>perl6</package>, install the binary as
 529         <file>/usr/bin/perl6</file> and use different directories for
 530         packaged modules to <package>perl</package>:
 531         <example>
 532 /usr/lib/perl6
 533 /usr/share/perl6
 534         </example>
 535         This will allow Perl 5 and 6 packages and modules (which should
 536         be packaged as <package>libfoo-bar-perl6</package>), to co-exist
 537         for as long as required.
 538       </p>
 539       <p>
 540         At some stage in the future when Perl 6 is sufficiently mature,
 541         the package naming may be reversed such that the
 542         <package>perl</package> package contains Perl 6 and the current
 543         package becomes <package>perl5</package>.
 544       </p>
 545     </appendix>
 546   </book>
 547 </debiandoc>
 548 <!-- Local variables: -->
 549 <!-- indent-tabs-mode: t -->
 550 <!-- End: -->