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