Debian Perl policy <author><name>Raphael Hertzog</name> <email>hertzog@debian.org</email> <version>1.11 <abstract> This document explains how Perl stuff is packaged within Debian. <copyright>Copyright 1999 by Software in the Public Interest 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. 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. A copy of the GNU General Public License is available as /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution. <toc> <chapt>General view of Perl stuff on a Debian system Debian has decided to enable developers to have more than one Perl on their system. You can have perl-5.004 and perl-5.005. However only one version of Perl will be officially blessed at a time. This official version should be used to build all Perl modules. The current policy is to bless the more recent Perl available in Debian. The official Perl will always be available under /usr/bin/perl. Older Perls will be available as /usr/bin/perl-$version. This choice has many consequences on how modules and Perl itself are packaged. You'll find all the details in the following chapters. <chapt>How Perl itself is packaged Each perl-$version source package will build at least perl-$version-base, perl-$version, perl-$version-doc, perl-$version-suid and perl-$version-debug. You can also have things like perl-$version-thread or perl-$version-libperl (or libperl-$version) depending on the perl version and on the motivation of the perl maintainer. :-) As perl-5.004 and perl-5.005 may be installed at the same time, the files must be installed in versioned directories so that one package does not overwrite the other's files. But they should cooperate so that the man page refers to the good version of Perl (/usr/bin/perl) and so that /usr/bin/perl will always be the latest Perl. Perl should always look for modules in /usr/lib/perl5 as it's the standard directory used for installing non-binary Perl modules. <sect>perl-$version-base A Debian system must always have a working /usr/bin/perl as it's used by postinsts and by numerous scripts called from postints like adduser, update-alternatives and so on. To achieve this goal, a perl-$version-base package must always be installed. That's the reason why the fake package perl-base is essential and depends on perl5-base that is provided by all perl-$version-base packages. <sect>perl-$version This is the standard Perl package containing all the modules shipped with the Perl sources. It should provide perl5 so that Perl scripts do not need to worry about which perl-$version is the current one. It does depend on perl-$version-base as it does not provide the Perl binary. <chapt>Packaging Perl modules <sect>Recommendations for all modules First, if you package a module Foo::Bar you should call your package libfoo-bar-perl. In order to configure your Perl module you can use something like this : At the top of debian/rules : <example> ifndef PERL PERL = /usr/bin/perl endif TMP =`pwd`/debian/tmp archlib =`$(PERL) -MConfig -e 'print $$Config{installarchlib}'` config =INSTALLDIRS=perl INSTALLMAN1DIR=$(TMP)/usr/share/man/man1 INSTALLMAN3DIR=$(TMP)/usr/share/man/man3 INSTALLPRIVLIB=$(TMP)/usr/lib/perl5 INSTALLARCHLIB=$(TMP)$(archlib) </example> If your module does also install binaries or scripts, you might want to add Ť INSTALLBIN=$(TMP)/usr/bin INSTALLSCRIPT=$(TMP)/usr/bin ť to the $(config) variable given above. And in the build target : <example> $(PERL) Makefile.PL $(config) $(MAKE) OPTIMIZE="-O2 -g -Wall" </example> And for installing the module in the tree : <example> $(MAKE) pure_install </example> Be sure to remove .packlist file installed automatically. You can add those lines for example : <example> find `pwd`/debian/tmp -type f -name .packlist | xargs -r rm -f -find `pwd`/debian/tmp -type d -empty | xargs -r rmdir -p --ignore-fail-on-non-empty </example> Note that the dh_perl script mentionned further in this document will do this for you. <sect1>Managing Perl dependencies automatically As you may have noticed, we do not have hardcoded any specific Perl version in the build process but the package may have to depend on a specific Perl version (generally the version that has been used to build it). In order to never hardcode any Perl version, we'll try to use a substitution. Instead of writing "perl-5.005" or "perl5" in the control file we'll use "${perl:Depends}" and the build process will add a line "perl:Depends=what_is_needeed" to the substvars file. In order to generate this substitution you can use dh_perl that is provided with debhelper. Or you can manage that yourself by adding the good lines in your rules file. If you want to know the version of perl that you're currently using for the build you can use something like this : <example> version = `$(PERL) -e 'printf "%.3f", $$]'` </example> <sect>Non-binary Perl modules They must be installed in /usr/lib/perl5 and must depend on perl5. <sect>Binary Perl modules They must be installed in /usr/lib/perl/$version/$cpu-$system and must depend on perl-$version. $cpu-$system is a GNU system type identifier, consisting of a cpu part and a system part, connected by a minus '-'. Examples are powerpc-linux or i386-gnu. You may want to provide a threaded version of the module which will be installed in /usr/lib/perl5/$version/$cpu-$system-thread. You can provide the threaded module in the same package or in another package called libfoo-bar-perl-thread. The binary modules must always be built with the latest Perl available in Debian. You can build the module for an older version of Perl but in that case you must call the module package accordingly by specifying the Perl version at the end of the package name (ie libfoo-bar-perl-5.004). <chapt>Packaging Perl scripts This is very simple, Perl scripts should always use /usr/bin/perl and should depend on perl5. At the present time you cannot setup a versioned dependency on perl5 as dpkg doesn't support this. However you can be sure that perl5 is >= 5.004.05. If you really need to make sure that you have perl5.005 then you should depend on perl-5.005 (and here you can use a versioned dependency). But you'll have to update your dependency when perl-5.006 comes out and so on, so it's not very convenient. Take care to include any dependency on a Perl module as they are not automatically detected by the standard tools like the libraries are. Lintian may warn you about such problems. If the script does have very special needs such as a specific version of Perl then you'll need to use #!/usr/bin/perl-5.004 (I take 5.004 as an example but you should replace 5.004 by whatever old version of Perl you are needing) and you'll need to add a dependency to perl-5.004. If it does furthermore request some binary modules then you'll need to package thoses modules especially for perl-5.004 instead of the latest Perl (being perl-5.005 or whatever else). Those modules packaged for old Perls will have to add the Perl version in their package name. For a module Foo::Bar, instead of calling the package libfoo-bar-perl you'll have to call it libfoo-bar-perl-5.004. <chapt>Changelog of the perl policy <sect>Version 1.1 <list> <item> Man pages are installed in /usr/share/man. <item> Changed "make" by "$(MAKE)". <item> Changed "CFLAGS=..." by "OPTIMIZE=...". CFLAGS is not recognized by the generated Makefiles. </list> </book>