libxml-sax-perl for Debian ========================== This is the Debian package of the Perl XML::SAX module which is the base package for the Perl SAX parser modules. Background ---------- A Perl SAX parser module is expected to register itself with the XML::SAX module during installation using a code snippet in the Makefile.PL for that module (see XML::SAX(3pm) for all the details). This latter module uses a file called 'ParserDetails.ini' as register which is created in the same directory where the XML::SAX modules are installed. Unfortunately, this registration does not work out of the box on a Debian system: The `make install` using the Makefile generated from the Makefile.PL mentioned above is run by the package maintainer on the system where the Debian package is build, while for the above described registration to work is has to run on the user's system. Perl SAX parser module registration -- the Debian way ----------------------------------------------------- On a Debian system the registration of the parser modules is done using a script called `update-perl-sax-parsers` in two steps: 1. Store the Perl SAX parser module info in a per-module file in a directory called 'ParserDetails.d'. 2. Generate the file 'ParserDetails.ini' by concatenating the contents of the files in the 'ParserDetails.d' directory. The deregistration of a parser module is also done in two steps: 1. Remove the per-module file for the Perl SAX parser module from the directory 'ParserDetails.d'. 2. Generate the file 'ParserDetails.ini' by concatenating the contents of the remaining files in the 'ParserDetails.d' directory. This script uses the directory '/var/lib/libxml-sax-perl/ParserDetails.d' and the file '/etc/perl/XML/SAX/ParserDetails.ini' by default. To keep the default behaviour of the XML::SAX module the file '/usr/share/perl5/XML/SAX/ParserDetails.ini' is symlinked to the file '/etc/perl/XML/SAX/ParserDetails.ini'. The file '/etc/perl/XML/SAX/ParserDetails.ini' is managed with ucf(1) to ensure that local changes are not accidentally overwritten. If you choose to keep a locally modified file but change your mind later, you can get update-perl-sax-parsers to overwrite your modified file by running 'ucf --purge '/etc/perl/XML/SAX/ParserDetails.ini' first. Support for Debian packages with Perl SAX parser modules -------------------------------------------------------- Each Debian package containing one or more Perl SAX parser modules needs to register these modules using the `update-perl-sax-parsers` script. This is done by putting the appropriate invocations of this script in the postinst and the prerm scripts of that package. Starting with libxml-sax-perl version 0.16+dfsg-1, the 'update-perl-sax-parsers' script supports parser-specific priorities. The idea is that the parser with the highest priority gets to be the default SAX parser. The bundled parser, XML::SAX::PurePerl, is not recommended for serious use, so its priority is set to 10. The default priority, when the '--priority' option is not used, is 50. Parsers with the same priority are ordered alphabetically by their module name, and the last one is the winner. If you want to change the priority of your module later, just remove the module with the old priority and the re-add it with the new priority. Below is an example of a postinst script: #!/bin/sh ## ---------------------------------------------------------------------- ## debian/postinst : postinstallation script for libxml-foo-perl ## ---------------------------------------------------------------------- ## ---------------------------------------------------------------------- set -e ## ---------------------------------------------------------------------- if [ "$1" = configure ] then if [ -n "$2" ] && dpkg --compare-versions "$2" lt x.x-x then update-perl-sax-parsers --remove XML::FOO fi update-perl-sax-parsers --add XML::FOO --priority 60 update-perl-sax-parsers --update fi ## ---------------------------------------------------------------------- ## automatically generated debhelper commands #DEBHELPER# exit 0 ## ---------------------------------------------------------------------- and of a prerm script: #!/bin/sh ## ---------------------------------------------------------------------- ## debian/prerm : preremoval script for libxml-foo-perl ## ---------------------------------------------------------------------- ## ---------------------------------------------------------------------- set -e ## ---------------------------------------------------------------------- if [ "$1" = remove ] then update-perl-sax-parsers --remove XML::FOO --priority 60 update-perl-sax-parsers --update fi ## ---------------------------------------------------------------------- ## automatically generated debhelper commands #DEBHELPER# exit 0 ## ---------------------------------------------------------------------- For the above to work properly the package needs to have a versioned dependency on 'libxml-sax-perl (>= 0.16+dfsg-1)'. You can find these examples in the directory '/usr/share/doc/libxml-sax-perl/examples'. Local Parser SAX parser module registration ------------------------------------------- The `update-perl-sax-parsers` script can also be used to maintain local Perl SAX parser module registration. When (de)registering a Perl SAX parser module to the registry one can indicate a directory (default is '/var/lib/libxml-sax-perl/ParserDetails.d'), e.g.: update-perl-sax-parsers --add XML::FOO \ --directory /usr/local/share/perl5/XML/SAX/ParserDetails.d update-perl-sax-parsers --remove XML::FOO \ --directory /usr/local/share/perl5/XML/SAX/ParserDetails.d Note that the indicated directory has to exist before invoking the script. When generating the 'ParserDetails.ini' file one can indicate its directory (default is '/etc/perl/XML/SAX/ParserDetails.ini') as well as one or more 'ParserDetails.d' directories to be used as sources. An example: update-perl-sax-parsers --update \ --file /usr/local/share/perl5/XML/SAX/ParserDetails.ini \ --directory /usr/local/share/perl5/XML/SAX/ParserDetails.d \ --directory /var/lib/libxml-sax-perl/ParserDetails.d Original CPAN Package vs. Debian Package ---------------------------------------- Installing the original package from CPAN into /usr/local breaks the Debian package, since the former is in Perl's @INC before the latter. So, please don't do this. If there's a new version of XML::SAX simply file a wishlist against the Debian package and wait for the update. If it's too late and you already have another version of XML::SAX in /usr/local shadowing the Debian one, this entry from an old version of the CPAN FAQ (that has apparently been removed since) may be helpful: How do I remove installed Perl modules? By using the ExtUtils::Installed and ExtUtils::Packlist modules that come with Perl as in the example below. There is also a more elaborate example in the ExtUtils::Packlist man page. #!/usr/local/bin/perl -w use ExtUtils::Packlist; use ExtUtils::Installed; $ARGV[0] or die "Usage: $0 Module::Name\n"; my $mod = $ARGV[0]; my $inst = ExtUtils::Installed->new(); foreach my $item (sort($inst->files($mod))) { print "removing $item\n"; unlink $item; } my $packfile = $inst->packlist($mod)->packlist_file(); print "removing $packfile\n"; unlink $packfile; This text was originally written by Ardo van Rangelrooij . -- Niko Tyni Fri, 04 Apr 2008 15:57:01 +0300