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 <ardo@debian.org>.
-- Niko Tyni <ntyni@iki.fi> Fri, 04 Apr 2008 15:57:01 +0300
Generated by dwww version 1.15 on Wed May 22 15:53:09 CEST 2024.