perl-policy.sgml

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