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