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.20</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/&lt;tmp&gt;/usr
 303           </example><footnote>
 304             <p>Replace &lt;tmp&gt; with the appropriate directory
 305             (nominally just tmp)</p>
 306           </footnote>
 307         </p>
 308         <p>
 309           A <tt>Build-Depends</tt> on <tt>perl (>= 5.6.0-16)</tt> is
 310           required.
 311         </p>
 312       </sect>
 313
 314       <sect id="module_deps">
 315         <heading>Module Dependencies</heading>
 316         <sect1 id="indep_modules">
 317           <heading>Architecture-Independent Modules</heading>
 318           <p>
 319             Architecture-independent modules which require
 320             <var>core</var> modules from the <package>perl</package>
 321             package must specify a dependency on that package.
 322           </p>
 323           <p>
 324             Modules which contain explicit <tt>require
 325             <var>version</var></tt> or <tt>use <var>version</var></tt>
 326             statements must specify a dependency on
 327             <package>perl</package> or <package>perl-base</package> with
 328             the minimum required version, or more simply the current
 329             version.
 330           </p>
 331           <p>
 332             In the absence of an explicit requirement,
 333             architecture-independent modules must depend on a minimum
 334             <package>perl</package> or <package>perl-base</package>
 335             version of <tt>5.6.0-16</tt> due to the changes in
 336             <tt>@INC</tt> introduced by that version.
 337           </p>
 338         </sect1>
 339
 340         <sect1 id="binary_modules">
 341           <heading>Binary Modules</heading>
 342           <p>
 343             Binary modules must specify a dependency on either
 344             <package>perl</package> or <package>perl-base</package> with
 345             a minimum version of the <package>perl</package> package
 346             used to build the module, and must additionally depend on
 347             the expansion of
 348             <package>perlapi-$Config{version}</package> using
 349             the <tt>Config</tt> module.
 350           </p>
 351         </sect1>
 352
 353         <sect1 id="dh_perl">
 354           <heading>Automating Perl Dependencies</heading>
 355           <p>
 356             Rather than hard-coding the dependencies into the control
 357             file, using a substitution such as <tt>${perl:Depends}</tt>
 358             is suggested.  This allows the dependencies to be determined
 359             as build time and written to the <file>substvars</file> file
 360             in the form <tt>perl:Depends=<var>deps</var></tt>.
 361           </p>
 362           <p>
 363             Packages built with <prgn>debhelper</prgn> may use <manref
 364             name="dh_perl" section=1> to generate this substitution
 365             automatically.  This additionally requires a versioned
 366             <tt>Build-Depends</tt> (or <tt>Build-Depends-Indep</tt>)
 367             on <tt>debhelper (>= 3.0.18)</tt>.
 368           </p>
 369         </sect1>
 370       </sect>
 371     </chapt>
 372
 373     <chapt id="programs">
 374       <heading>Perl Programs</heading>
 375       <sect id="hash_bang">
 376         <heading>Script Magic</heading>
 377         <p>
 378           All packaged perl programs must start with
 379           <tt>#!/usr/bin/perl</tt> and may append such flags as are
 380           required.
 381         </p>
 382       </sect>
 383
 384       <sect id="program_deps">
 385         <heading>Program Dependencies</heading>
 386         <p>
 387           Programs which require <var>core</var> modules from the
 388           <package>perl</package> package must specify a dependency on
 389           that package.
 390         </p>
 391         <p>
 392           Programs which contain explicit <tt>require
 393           <var>version</var></tt> or <tt>use <var>version</var></tt>
 394           statements must specify a dependency on
 395           <package>perl</package> or <package>perl-base</package> with
 396           the minimum required version, or more simply the current
 397           version.
 398         </p>
 399         <p>
 400           As with modules, packages using <prgn>debhelper</prgn> may use
 401           <manref name="dh_perl" section=1> to automatically generate
 402           dependences (see <ref id="dh_perl">).
 403         </p>
 404       </sect>
 405     </chapt>
 406
 407     <chapt id="embed">
 408       <heading>Programs Embedding Perl</heading>
 409       <sect id="build_embedded">
 410         <heading>Building Embedded Programs</heading>
 411         <p>
 412           Programs which embed a perl interpreter must declare a
 413           <tt>Build-Depends</tt> on <package>libperl-dev</package>.
 414         </p>
 415         <p>
 416           The default linker options produced by
 417           <example>
 418 perl -MExtUtils::Embed -e ldopts
 419           </example>
 420           will link against the dynamic <tt>libperl</tt>.  If programs
 421           wish to link to the static library, then <tt>-lperl</tt>
 422           should be changed to <file>/usr/lib/libperl.a</file> in those
 423           options.
 424         </p>
 425       </sect>
 426
 427       <sect id="embedded_deps">
 428         <heading>Embedded Perl Dependencies</heading>
 429         <p>
 430           Dependencies for programs linking against the shared Perl
 431           library will be automatically created by
 432           <prgn>dpkg-shlibdeps</prgn>.  Note however that the shared
 433           perl library package only suggests
 434           <package>perl-base</package> and packages requiring any
 435           <var>core</var> modules from the <package>perl</package>
 436           package must depend upon it explicitly.
 437         </p>
 438       </sect>
 439     </chapt>
 440
 441     <appendix id="perl6">
 442       <heading>Perl 6</heading>
 443       <p>
 444         The current stable upstream version at the time of this writing
 445         is 5.6.0.  There is currently work in progress on the next major
 446         revision, although the specifications have yet to be finalised.
 447       </p>
 448       <p>
 449         It is anticipated that when Perl 6 is released it will initially
 450         be packaged as <package>perl6</package>, install the binary as
 451         <file>/usr/bin/perl6</file> and use different directories for
 452         packaged modules to <package>perl</package>:
 453         <example>
 454 /usr/lib/perl6
 455 /usr/share/perl6
 456         </example>
 457         This will allow Perl 5 and 6 packages and modules (which should
 458         be packaged as <package>libfoo-bar-perl6</package>), to co-exist
 459         for as long as required.
 460       </p>
 461       <p>
 462         At some stage in the future when Perl 6 is sufficiently mature,
 463         the package naming may be reversed such that the
 464         <package>perl</package> package contains Perl 6 and the current
 465         package becomes <package>perl5</package>.
 466       </p>
 467     </appendix>
 468   </book>
 469 </debiandoc>