X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=perl-policy.sgml;h=12cd82c136e46c7f88b38727f12e6687edf8c77b;hb=35b766c956f252a9092cfb7b04bcf1f05a4627d1;hp=8edf3d7e5bdb7ffbc5dd4b0272d9ce268f383c66;hpb=3eb12bd7b39a1bcbaf9d973eee86264367abd26e;p=debian%2Fdebian-policy.git
diff --git a/perl-policy.sgml b/perl-policy.sgml
index 8edf3d7..12cd82c 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -1,4 +1,8 @@
-
+
+ %versiondata;
+]>
@@ -6,17 +10,19 @@
Debian Perl Policy
Raphaël Hertzog
- hertzog@debian.org
Brendan O'Dea
- bod@debian.org
- version 1.20
+
+ The Debian Policy mailing list
+ debian-policy@lists.debian.org
+
+ version &version;, &date;
This document describes the packaging of Perl within the Debian
- GNU/Linux distribution and the policy requirements for packaged
+ distribution and the policy requirements for packaged
Perl programs and modules.
@@ -38,21 +44,33 @@
A copy of the GNU General Public License is available as
- /usr/share/common-licences/GPL in the Debian GNU/Linux
+ /usr/share/common-licenses/GPL in the Debian
distribution or on the World Wide Web at
.
You can also obtain it by writing to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+
+ About this document
+
+ This document is distributed as the perl-policy files
+ in the Debian package
+ .
+ It is also available from the Debian web mirrors at
+ .
+
+
+
Perl Packaging
@@ -75,8 +93,12 @@
The perl-base package must provide
- perlapi-version for all released
- versions it is compatible with.
+ perlapi-abiname for all released
+ package versions it is compatible with. The choice of
+ abiname is arbitrary, but if it differs from
+ $Config{version}see the
+ Config module, it must be specified in
+ $Config{debian_abi}.
@@ -89,18 +111,18 @@
the binary and a basic set of modules.
- As Perl is currently used by such things as
- update-alternatives and some package maintainer
- scripts, it must be priority required and marked as
- essential.
+ As Perl has been part of the essential set for some time and is
+ used without dependencies by such things as package maintainer
+ scripts, perl-base must be
+ priority required and marked as essential.
Note that the perl-base 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
- perl-base rather than
- perl.
+ may change. In general, only packages which form part of the
+ base system should use only the facilities
+ of perl-base rather than declaring a
+ dependency on perl.
@@ -124,22 +146,42 @@
Modules installed by the local administrator for the
current version of Perl (see [).
-/usr/local/lib/perl/version
-/usr/local/share/perl/version
+$Config{sitearch} (currently /usr/local/lib/perl/version)
+$Config{sitelib} (currently /usr/local/share/perl/version)
Where version indicates the current Perl
- version ($Config{version}see the
- Config module).
+ version ($Config{version}).
+ ]
+ These locations, particularly $Config{sitearch},
+ may change if the binary interface between the
+ Perl interpreter and compiled modules has to be
+ changed in an incompatible way without a change in
+ version. While this will only be done as a
+ last resort, packages should use $Config{sitelib}
+ and $Config{sitearch}, not hardcode the current
+ locations.Build systems based on
+ ExtUtils::MakeMaker and Module::Build
+ do this automatically.
+
vendor
-
Packaged modules (see [).
-/usr/lib/perl5
-/usr/share/perl5
+$Config{vendorarch} (currently /usr/lib/perl5)
+$Config{vendorlib} (currently /usr/share/perl5)
+ These locations, particularly
+ $Config{vendorarch}, may change if
+ necessaryFor example, to include
+ the multiarch triplet. Packages
+ should use $Config{vendorlib} and
+ $Config{vendorarch}, not hardcode the current
+ locations.Build systems based on
+ ExtUtils::MakeMaker and Module::Build
+ do this automatically.
]
core
@@ -147,9 +189,19 @@
Modules included in the core Perl distribution.
-/usr/lib/perl/version
-/usr/share/perl/version
+$Config{archlib} (currently /usr/lib/perl/shortversion)
+$Config{privlib} (currently /usr/share/perl/shortversion)
+ Where shortversion indicates the current Perl major
+ version (for example 5.18).
+
+
+ These locations should be considered internal to the
+ perl source package. If necessary, packages should use
+ $Config{archlib} and $Config{privlib} instead of
+ hardcoding the current locations.Build systems based on
+ ExtUtils::MakeMaker and Module::Build
+ do this automatically.
site (old)
@@ -176,8 +228,8 @@
package.
- Manual pages distributed with Perl packages must be installed
- into the standard directories:
+ Manual pages distributed with packages built from the perl
+ source package must be installed into the standard directories:
Programs
-
@@ -196,6 +248,8 @@
+ The extensions used for manual pages distributed with module
+ packages are different. See [.
]
@@ -277,10 +331,17 @@ make install
Module Package Names
Perl module packages should be named for the primary module
- provided. The naming convention for module Foo::Bar
- is libfoo-bar-perl. Packages which include
- multiple modules may additionally include provides for those
- modules using the same convention.
+ provided. The naming convention is to lowercase the Perl module
+ name, prepend, lib, change all occurrences
+ of :: to -, and append -perl. For
+ example:
+
+Foo::Bar libfoo-bar-perl
+Foo::Bar::Baz libfoo-bar-baz-perl
+Foo::BarBaz libfoo-barbaz-perl
+
+ Packages which include multiple modules may additionally include
+ provides for the additional modules using the same convention.
@@ -299,12 +360,11 @@ $(MAKE) OPTIMIZE="-O2 -g -Wall"
and this one to install the results into the temporary tree:
-$(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr
-
-
-
- A Build-Depends on perl (>= 5.6.0-16) is
- required.
+$(MAKE) install DESTDIR=$(CURDIR)/debian/<tmp>
+
+ Replace <tmp> with the appropriate directory
+ (nominally just tmp)
+
@@ -325,25 +385,20 @@ $(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr
the minimum required version, or more simply the current
version.
-
- In the absence of an explicit requirement,
- architecture-independent modules must depend on a minimum
- perl or perl-base
- version of 5.6.0-16 due to the changes in
- @INC introduced by that version.
-
- Binary Modules
+ Binary and Other Architecture Dependent Modules
Binary modules must specify a dependency on either
perl or perl-base with
a minimum version of the perl package
- used to build the module, and must additionally depend on
- the expansion of
- perlapi-$Config{version} using
- the Config module.
+ used to build the module. Additionally, all binary modules
+ (regardless of their installation directory) and any other modules
+ installed into $Config{vendorarch} must depend on the
+ expansion of perlapi-$Config{debian_abi} using
+ the Config module. If $Config{debian_abi}
+ is empty or not set, $Config{version} must be used.
@@ -353,15 +408,22 @@ $(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr
Rather than hard-coding the dependencies into the control
file, using a substitution such as ${perl:Depends}
is suggested. This allows the dependencies to be determined
- as build time and written to the substvars file
- in the form perl:Depends=deps.
+ at build time and written to the substvars file
+ in the form
+ perl:Depends=deps.
+ Please note that dependencies caused by versioned
+ uses and on separately packaged modules are not included
+ in this variable and must be explicitly included.
+
- Packages built with debhelper may use to generate this substitution
- automatically. This additionally requires a versioned
- Build-Depends (or Build-Depends-Indep)
- on debhelper (>= 3.0.18).
+ Packages built with debhelper may use
+
+ to generate this
+ substitution automatically. This additionally requires a
+ versioned Build-Depends (or
+ Build-Depends-Indep) on debhelper (>=
+ 3.0.18).
@@ -395,7 +457,7 @@ $(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr
As with modules, packages using debhelper may use
- to automatically generate
+ to automatically generate
dependences (see [).
]
@@ -433,6 +495,26 @@ perl -MExtUtils::Embed -e ldopts
package must depend upon it explicitly.
+
+
+ Perl Package Upgrades
+
+ Starting from perl 5.12.3-2, a dpkg trigger
+ named perl-major-upgrade will be triggered by the
+ postinst of the perl package during major
+ upgrades. Some examples of things which constitute a major upgrade
+ are an upgrade which would change the value of versioned
+ directories in @INC, or one which changes abiname.
+ Any package may declare an interest in the trigger, especially
+ packages including long-running daemons which would stop working
+ until restart.
+
+
+ It is suggested that such packages include an appropriate section
+ in their postinst to handle the trigger by restarting relevant
+ daemons or notifying users of further action.
+
+
@@ -464,3 +546,6 @@ perl -MExtUtils::Embed -e ldopts
+
+
+