--- /dev/null
+<!doctype debiandoc system>
+
+<debiandoc>
+ <book>
+ <titlepag>
+ <title>Debian Perl Policy</title>
+ <author>
+ <name>Raphaël Hertzog</name>
+ <email>hertzog@debian.org</email>
+ </author>
+ <author>
+ <name>Brendan O'Dea</name>
+ <email>bod@debian.org</email>
+ </author>
+ <version>version 1.19</version>
+
+ <abstract>
+ This document describes the packaging of Perl within the Debian
+ GNU/Linux distribution and the policy requirements for packaged
+ Perl programs and modules.
+ </abstract>
+
+ <copyright>
+ <copyrightsummary>
+ Copyright © 1999, 2001 Software in the Public Interest
+ </copyrightsummary>
+ <p>
+ This manual is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation; either version
+ 2 of the License, or (at your option) any later version.
+ </p>
+ <p>
+ This is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
+ the GNU General Public License for more details.
+ </p>
+ <p>
+ A copy of the GNU General Public License is available as
+ <tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
+ distribution or on the World Wide Web at
+ <url id="http://www.gnu.org/copyleft/gpl.html"
+ name="The GNU Public Licence">.
+ </p>
+ <p>
+ You can also obtain it by writing to the
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+ </p>
+ </copyright>
+ </titlepag>
+
+ <toc detail="sect">
+
+ <chapt id="perl">
+ <heading>Perl Packaging</heading>
+ <sect id="versions">
+ <heading>Versions</heading>
+ <p>
+ At any given time, the package <package>perl</package> should
+ represent the current stable upstream version of Perl revision
+ 5 (see <ref id="perl6">).
+ </p>
+ <p>
+ Only one package may contain the <file>/usr/bin/perl</file>
+ binary and that package must either be <package>perl</package>
+ or a dependency of that package (see <ref id="base">).
+ </p>
+ <p>
+ Where possible, Perl should be compiled to provide binary
+ compatibility to at least the last released package version to
+ allow a grace period over which binary module packages may be
+ re-built against the new package (see <ref id="binary_modules">).
+ </p>
+ <p>
+ The <package>perl-base</package> package must provide
+ <package>perlapi-<var>version</var></package> for all released
+ versions it is compatible with.
+ </p>
+ </sect>
+
+ <sect id="base">
+ <heading>Base Package</heading>
+ <p>
+ In order to provide a minimal installation of Perl for use by
+ applications without requiring the whole of Perl to be
+ installed, the <package>perl-base</package> package contains
+ the binary and a basic set of modules.
+ </p>
+ <p>
+ As Perl is currently used by such things as
+ <file>update-alternatives</file> and some package maintainer
+ scripts, it must be priority <em>required</em> and marked as
+ <em>essential</em>.
+ </p>
+ <p>
+ Note that the <package>perl-base</package> package is intended
+ only to provide for exceptional circumstances and the contents
+ may change. In general only packages which form part of the
+ base system should declare a dependency on
+ <package>perl-base</package> rather than
+ <package>perl</package>.
+ </p>
+ </sect>
+
+ <sect id="paths">
+ <heading>Module Path</heading>
+ <p>
+ Perl searches three different locations for modules, referred
+ to in this document as <var>core</var> in which modules
+ distributed with Perl are installed, <var>vendor</var> for
+ packaged modules and <var>site</var> for modules installed by
+ the local administrator.
+ </p>
+ <p>
+ The module search path (<tt>@INC</tt>) in the Debian packages
+ has been ordered to include these locations in the following
+ order:
+ <taglist>
+ <tag><var>site</var> (current)</tag>
+ <item>
+ <p>
+ Modules installed by the local administrator for the
+ current version of Perl (see <ref id="site">).
+ <example>
+/usr/local/lib/perl/<var>version</var>
+/usr/local/share/perl/<var>version</var>
+ </example>
+ Where <var>version</var> indicates the current Perl
+ version (<tt>$Config{version}</tt><footnote>see the
+ <tt>Config</tt> module</footnote>).
+ </p>
+ </item>
+ <tag><var>vendor</var></tag>
+ <item>
+ <p>
+ Packaged modules (see <ref id="module_packages">).
+ <example>
+/usr/lib/perl5
+/usr/share/perl5
+ </example>
+ </p>
+ </item>
+ <tag><var>core</var></tag>
+ <item>
+ <p>
+ Modules included in the core Perl distribution.
+ <example>
+/usr/lib/perl/<var>version</var>
+/usr/share/perl/<var>version</var>
+ </example>
+ </p>
+ </item>
+ <tag><var>site</var> (old)</tag>
+ <item>
+ <p>
+ <var>site</var> directories (as above) for modules
+ installed with previously released
+ <package>perl</package> packages for which the current
+ package is binary compatible are included if present.
+ </p>
+ </item>
+ </taglist>
+ In each of the directory pairs above, the <file>lib</file>
+ component is for binary (XS) modules, and <file>share</file>
+ for architecture-independent (pure-perl) modules.
+ </p>
+ </sect>
+
+ <sect id="docs">
+ <heading>Documentation</heading>
+ <p>
+ The POD files and manual pages which do not refer to programs
+ may be split out into a separate <package>perl-doc</package>
+ package.
+ </p>
+ <p>
+ Manual pages distributed with Perl packages must be installed
+ into the standard directories:
+ <taglist>
+ <tag>Programs</tag>
+ <item>
+ <p>
+ Manual pages for programs and scripts are installed into
+ <file>/usr/share/man/man1</file> with the extension
+ <tt>.1</tt>.
+ </p>
+ </item>
+ <tag>Modules</tag>
+ <item>
+ <p>
+ Manual pages for modules are installed into
+ <file>/usr/share/man/man3</file> with the extension
+ <tt>.3perl</tt>.
+ </p>
+ </item>
+ </taglist>
+ </p>
+ </sect>
+ </chapt>
+
+ <chapt id="site">
+ <heading>Locally Installed Modules</heading>
+ <sect id="site_dirs">
+ <heading>Site Directories</heading>
+ <p>
+ The Perl packages must provide a mechanism for the local
+ administrator to install modules under <file>/usr/local</file>
+ but must not create or remove those directories.
+ </p>
+ <p>
+ Modules should be installed to the directories described above
+ in <ref id="paths"> as <var>site</var> (current), programs to
+ <file>/usr/local/bin</file> and manual pages under
+ <file>/usr/local/man</file>.
+ </p>
+ </sect>
+
+ <sect id="site_install">
+ <heading>Site Installation</heading>
+ <p>
+ The following commands should be sufficient in the majority of
+ cases for the local administrator to install modules and must
+ create directories as required:
+ <example>
+perl Makefile.PL
+make install
+ </example>
+ </p>
+ </sect>
+ </chapt>
+
+ <chapt id="module_packages">
+ <heading>Packaged Modules</heading>
+ <sect id="vendor_dirs">
+ <heading>Vendor Directories</heading>
+ <p>
+ The installation directory for Debian modules must be
+ different from that for <var>core</var> and <var>site</var>
+ modules.
+ </p>
+ <p>
+ The current Perl packaging uses the <var>vendor</var>
+ directories for this purpose, which are at present as
+ described in <ref id="paths"> as <var>vendor</var>.
+ </p>
+ <p>
+ No version subdirectory exists on these directories as the
+ dependencies for packaged modules (see <ref id="module_deps">)
+ should ensure that all work with the current
+ <package>perl</package> package.
+ </p>
+ <p>
+ The Perl distribution includes many modules available
+ separately from CPAN<footnote><url
+ id="http://www.perl.com/CPAN"></footnote>, which may have a
+ newer version. The intent of the <tt>@INC</tt> ordering
+ (described in <ref id="paths">) is to allow such modules to be
+ packaged to <var>vendor</var> which take precedence over the
+ version in <var>core</var>. A packaged module which shadows a
+ <var>core</var> module in this way must be a newer version.
+ </p>
+ <p>
+ Module packages must install manual pages into the standard
+ directories (see <ref id="docs">) using the extensions
+ <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict
+ arises where a packaged module duplicates a <var>core</var>
+ module.
+ </p>
+ <p>
+ <file>.packlist</file> files should not be installed.
+ </p>
+ </sect>
+
+ <sect id="package_names">
+ <heading>Module Package Names</heading>
+ <p>
+ Perl module packages should be named for the primary module
+ provided. The naming convention for module <tt>Foo::Bar</tt>
+ is <package>libfoo-bar-perl</package>. Packages which include
+ multiple modules may additionally include provides for those
+ modules using the same convention.
+ </p>
+ </sect>
+
+ <sect id="vendor_install">
+ <heading>Vendor Installation</heading>
+ <p>
+ A module should use the following lines in the
+ <file>debian/rules</file> <tt>build</tt>
+ target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
+ may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
+ cases where <file>Makefile.PL</file> is not invoked directly
+ from <file>debian/rules</file></footnote>:
+ <example>
+perl Makefile.PL INSTALLDIRS=vendor
+$(MAKE) OPTIMIZE="-O2 -g -Wall"
+ </example>
+ and this one to install the results into the temporary tree:
+ <example>
+$(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr
+ </example>
+ </p>
+ <p>
+ A <tt>Build-Depends</tt> on <tt>perl (>= 5.6.0-16)</tt> is
+ required.
+ </p>
+ </sect>
+
+ <sect id="module_deps">
+ <heading>Module Dependencies</heading>
+ <sect1 id="indep_modules">
+ <heading>Architecture-Independent Modules</heading>
+ <p>
+ Architecture-independent modules which require
+ <var>core</var> modules from the <package>perl</package>
+ package must specify a dependency on that package.
+ </p>
+ <p>
+ Modules which contain explicit <tt>require
+ <var>version</var></tt> or <tt>use <var>version</var></tt>
+ statements must specify a dependency on
+ <package>perl</package> or <package>perl-base</package> with
+ the minimum required version, or more simply the current
+ version.
+ </p>
+ <p>
+ In the absence of an explicit requirement,
+ architecture-independent modules must depend on a minimum
+ <package>perl</package> or <package>perl-base</package>
+ version of <tt>5.6.0-16</tt> due to the changes in
+ <tt>@INC</tt> introduced by that version.
+ </p>
+ </sect1>
+
+ <sect1 id="binary_modules">
+ <heading>Binary Modules</heading>
+ <p>
+ Binary modules must specify a dependency on either
+ <package>perl</package> or <package>perl-base</package> with
+ a minimum version of the <package>perl</package> package
+ used to build the module, and must additionally depend on
+ the expansion of
+ <package>perlapi-$Config{version}</package>.
+ </p>
+ </sect1>
+
+ <sect1 id="dh_perl">
+ <heading>Automating Perl Dependencies</heading>
+ <p>
+ Rather than hard-coding the dependencies into the control
+ file, using a substitution such as <tt>${perl:Depends}</tt>
+ is suggested. This allows the dependencies to be determined
+ as build time and written to the <file>substvars</file> file
+ in the form <tt>perl:Depends=<var>deps</var></tt>.
+ </p>
+ <p>
+ Packages built with <prgn>debhelper</prgn> may use <manref
+ name="dh_perl" section=1> to generate this substitution
+ automatically. Additionally requires a
+ <tt>Build-Depends</tt> on <tt>debhelper (>= 3.0.18)</tt>.
+ </p>
+ </sect1>
+ </sect>
+ </chapt>
+
+ <chapt id="programs">
+ <heading>Perl Programs</heading>
+ <sect id="hash_bang">
+ <heading>Script Magic</heading>
+ <p>
+ All packaged perl programs must start with
+ <tt>#!/usr/bin/perl</tt> and may append such flags as are
+ required.
+ </p>
+ </sect>
+
+ <sect id="program_deps">
+ <heading>Program Dependencies</heading>
+ <p>
+ Programs which require <var>core</var> modules from the
+ <package>perl</package> package must specify a dependency on
+ that package.
+ </p>
+ <p>
+ Programs which contain explicit <tt>require
+ <var>version</var></tt> or <tt>use <var>version</var></tt>
+ statements must specify a dependency on
+ <package>perl</package> or <package>perl-base</package> with
+ the minimum required version, or more simply the current
+ version.
+ </p>
+ <p>
+ As with modules, packages using <prgn>debhelper</prgn> may use
+ <manref name="dh_perl" section=1> to automatically generate
+ dependences (see <ref id="dh_perl">).
+ </p>
+ </sect>
+ </chapt>
+
+ <chapt id="embed">
+ <heading>Programs Embedding Perl</heading>
+ <sect id="build_embedded">
+ <heading>Building Embedded Programs</heading>
+ <p>
+ Programs which embed a perl interpreter must declare a
+ <tt>Build-Depends</tt> on <package>libperl-dev</package>.
+ </p>
+ <p>
+ The default linker options produced by
+ <example>
+perl -MExtUtils::Embed -e ldopts
+ </example>
+ will link against the dynamic <tt>libperl</tt>. If programs
+ wish to link to the static library, then <tt>-lperl</tt>
+ should be changed to <file>/usr/lib/libperl.a</file> in those
+ options.
+ </p>
+ </sect>
+
+ <sect id="embedded_deps">
+ <heading>Embedded Perl Dependencies</heading>
+ <p>
+ Dependencies for programs linking against the shared Perl
+ library will be automatically created by
+ <prgn>dpkg-shlibdeps</prgn>. Note however that the shared
+ perl library package only suggests
+ <package>perl-base</package> and packages requiring any
+ <var>core</var> modules from the <package>perl</package>
+ package must depend upon it explicitly.
+ </p>
+ </sect>
+ </chapt>
+
+ <appendix id="perl6">
+ <heading>Perl 6</heading>
+ <p>
+ The current stable upstream version at the time of this writing
+ is 5.6.0. There is currently work in progress on the next major
+ revision, although the specifications have yet to be finalised.
+ </p>
+ <p>
+ It is anticipated that when Perl 6 is released it will initially
+ be packaged as <package>perl6</package>, install the binary as
+ <file>/usr/bin/perl6</file> and use different directories for
+ packaged modules to <package>perl</package>:
+ <example>
+/usr/lib/perl6
+/usr/share/perl6
+ </example>
+ This will allow Perl 5 and 6 packages and modules (which should
+ be packaged as <package>libfoo-bar-perl6</package>), to co-exist
+ for as long as required.
+ </p>
+ <p>
+ At some stage in the future when Perl 6 is sufficiently mature,
+ the package naming may be reversed such that the
+ <package>perl</package> package contains Perl 6 and the current
+ package becomes <package>perl5</package>.
+ </p>
+ </appendix>
+ </book>
+</debiandoc>
<tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
distribution or on the World Wide Web at
<url id="http://www.gnu.org/copyleft/gpl.html"
- name="The GNU General Public Licence">. You can also obtain it by writing to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ name="The GNU General Public Licence">. You can also
+ obtain it by writing to the Free Software Foundation, Inc.,
+ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
</p>
</copyright>
</titlepag>
permissions 2775 (group-writable and set-group-id) and be
owned by <tt>root.staff</tt>.</p>
</sect1>
+ <sect1>
+ <heading>The system-wide mail directory</heading>
+ <p>
+ The system-wide mail directory is <tt>/var/mail</tt>. This
+ directory is part of the base system and should not owned
+ by any particular mail agents. The use of the old
+ location <tt>/var/spool/mail</tt> is deprecated, even
+ though the spool may still be physically located there.
+ To maintain partial upgrade compatibility for systems
+ which have <tt>/var/spool/mail</tt> as their physical mail
+ spool, packages using <tt>/var/mail</tt> must depend on
+ either <package>libc6</package> (>= 2.1.3-13), or on
+ <package>base-files</package> (>= 2.2.0), or on later
+ versions of either one of these packages.
+ </p>
+ </sect1>
+
</sect>
+
+
<sect>
<heading>Users and groups</heading>
<p>
You should follow the directions in the <em>Debian Packaging
- Manual</em> for putting the shared library in its package,
- and you must include a <tt>shlibs</tt> control area
- file with details of the dependencies for packages which
- use the library.</p>
+ Manual</em> (or other documentation of the Debian
+ packaging tools) for putting the shared library in its
+ package, and you must include a <tt>shlibs</tt> control area
+ file with details of the dependencies for packages which use
+ the library.</p>
<p>
Shared libraries should not be installed
</sect>
</chapt>
- <chapt>
+ <chapt id="customized-programs">
<heading>Customized programs</heading>
<sect id="arch-spec">
</enumlist></p></sect>
- <sect>
+ <sect id="mail-transport-agents">
<heading>Mail transport, delivery and user agents</heading>
<p>
serious brain damage!</p>
<p>
- The mail spool is <tt>/var/spool/mail</tt> and the interface
+ The mail spool is <tt>/var/mail</tt> and the interface
to send a mail message is <tt>/usr/sbin/sendmail</tt> (as
- per the FHS). The mail spool is part of the base system
- and not part of the MTA package.</p>
+ per the FHS). On older systems, the mail spool may be
+ physically located in /var/spool/mail, but all access to the
+ mail spool should be via the /var/mail symlink. The mail
+ spool is part of the base system and not part of the MTA
+ package.
+ </p>
<p>
All Debian MUAs, MTAs, MDAs and other mailbox accessing
</p>
</sect>
+ <sect>
+ <heading>Perl programs and modules</heading>
+ <p>
+ Perl programs and modules should follow the current Perl
+ policy as defined in the file found on
+ <ftpsite>ftp.debian.org</ftpsite> in
+ <ftppath>/debian/doc/package-developer/perl-policy.txt.gz</ftppath>
+ or your local mirror. In addition, it is included in the
+ <tt>debian-policy</tt> package.
+ </p>
+ </sect>
<sect>
<heading>Emacs lisp programs</heading>
projects / debian / debian-policy.git / commitdiff