1INTRODUCTION 2============ 3 4This module implements a Perl interface to the Gnome libxml2 library which 5provides interfaces for parsing and manipulating XML files. This module allows 6Perl programmers to make use of the highly capable validating XML parser and 7the high performance DOM implementation. 8 9 10IMPORTANT NOTES 11=============== 12 13XML::LibXML was almost entirely reimplemented between version 1.40 to version 141.49. This may cause problems on some production machines. With version 1.50 a 15lot of compatibility fixes were applied, so programs written for XML::LibXML 161.40 or less should run with version 1.50 again. 17 18In 1.59, a new callback API was introduced. This new API is not compatible with 19the previous one. See XML::LibXML::InputCallback manual page for details. 20 21In 1.61 the XML::LibXML::XPathContext module, previously distributed 22separately, was merged in. 23 24 25DEPENDENCIES 26============ 27 28Prior to installation you MUST have installed the libxml2 library. You can get 29the latest libxml2 version from 30 31http://xmlsoft.org/ 32 33Without libxml2 installed this module will neither build nor run. 34 35Also XML::LibXML requires the following packages: 36 37 o XML::LibXML::Common - general functions used by various XML::LibXML modules 38 o XML::SAX - DOM building support from SAX 39 o XML::NamespaceSupport - DOM building support from SAX 40 41These packages are required. If one is missing some tests will fail. 42 43Again, libxml2 is required to make XML::LibXML work. The library is not just 44required to build XML::LibXML, it has to be accessible during run-time as well. 45Because of this you need to make sure libxml2 is installed properly. To test 46this, run the xmllint program on your system. xmllint is shipped with libxml2 47and therefore should be available. For building the module you will also need 48the header file for libxml2, which in binary (.rpm,.deb) etc. distributions 49usually dwell in a package named libxml2-devel or similar. 50 51 52INSTALLATION 53============ 54 55To install XML::LibXML just follow the standard installation routine for Perl 56modules: 57 58 1 perl Makefile.PL 59 2 make 60 3 make test 61 4 make install # as superuser 62 63Note that XML::LibXML is an XS based Perl extension and you need a C compiler 64to build it. 65 66Note also that you should rebuild XML::LibXML if you upgrade libxml2 in order 67to avoid problems with possible binary incompatibilities between releases of 68the library. 69 70 71Notes on libxml2 versions 72========================= 73 74XML::LibXML requires at least libxml2 2.6.16 to compile and pass all tests and 75at least 2.6.21 is required for XML::LibXML::Reader. For some older OS versions 76this means that an update of the pre-built packages is required. 77 78Although libxml2 claims binary compatibility between its patch levels, it is a 79good idea to recompile XML::LibXML and XML::LibXML::Common and run its tests 80after an upgrade of libxml2. 81 82If your libxml2 installation is not within your $PATH, you can pass the 83XMLPREFIX=$YOURLIBXMLPREFIX parameter to Makefile.PL determining the correct 84libxml2 version in use. e.g. 85 86> perl Makefile.PL XMLPREFIX=/usr/brand-new 87 88will ask '/usr/brand-new/bin/xml2-config' about your real libxml2 89configuration. 90 91Try to avoid setting INC and LIBS directly on the command-line, for if used, 92Makefile.PL does not check the libxml2 version for compatibility with 93XML::LibXML. 94 95 96Which version of libxml2 should be used? 97======================================== 98 99XML::LibXML is tested against a couple versions of libxml2 before it is 100released. Thus there are versions of libxml2 that are known not to work 101properly with XML::LibXML. The Makefile.PL keeps a blacklist of the 102incompatible libxml2 versions. 103 104If Makefile.PL detects one of the incompatible versions, it notifies the user. 105It may still happen that XML::LibXML builds and pass its tests with such a 106version, but that does not mean everything is OK. There will be no support at 107all for blacklisted versions! 108 109As of XML::LibXML 1.61, only versions 2.6.16 and higher are supported. 110XML::LibXML will probably not compile with earlier libxml2 versions than 2.5.6. 111Versions prior to 2.6.8 are known to be broken for various reasons, versions 112prior to 2.1.16 exhibit problems with namespaced attributes and do not 113therefore pass XML::LibXML regression tests. 114 115It may happen that an unsupported version of libxml2 passes all tests under 116certain conditions. This is no reason to assume that it shall work without 117problems. If Makefile.PL marks a version of libxml2 as incompatible or broken 118it is done for a good reason. 119 120 121Notes for Microsoft Windows 122=========================== 123 124Thanks to Randy Kobes there is a pre-compiled PPM package available on 125 126http://theoryx5.uwinnipeg.ca/ppmpackages/ 127 128Usually it takes a little time to build the package for the latest release. 129 130 131Notes for Mac OS X 132================== 133 134Due refactoring the module, XML::LibXML will not run with some earlier versions 135of Mac OS X. It appears that this is related to special linker options for that 136OS prior to version 10.2.2. Since the developers do not have full access to 137this OS, help/ patches from OS X gurus are highly appreciated. 138 139It is confirmed that XML::LibXML builds and runs without problems since Mac OS 140X 10.2.6. 141 142 143Notes for HPUX 144============== 145 146XML::LibXML requires libxml2 2.6.16 or later. There may not exist a usable 147binary libxml2 package for HPUX and XML::LibXML. If HPUX cc does not compile 148libxml2 correctly, you will be forced to recompile perl with gcc (unless you 149have already done that). 150 151Additionally I received the following Note from Rozi Kovesdi: 152 153> Here is my report if someone else runs into the same problem: 154> 155> Finally I am done with installing all the libraries and XML Perl 156> modules 157> 158> The combination that worked best for me was: 159> gcc 160> GNU make 161> 162> Most importantly - before trying to install Perl modules that depend on 163> libxml2: 164> 165> must set SHLIB_PATH to include the path to libxml2 shared library 166> 167> assuming that you used the default: 168> 169> export SHLIB=/usr/local/lib 170> 171> also, make sure that the config files have execute permission: 172> 173> /usr/local/bin/xml2-config 174> /usr/local/bin/xslt-config 175> 176> they did not have +x after they were installed by 'make install' 177> and it took me a while to realize that this was my problem 178> 179> or one can use: 180> 181> perl Makefile.PL LIBS='-L/path/to/lib' INC='-I/path/to/include' 182 183 184CONTACT 185======= 186 187For bug reports, please use the CPAN request tracker on 188http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXML 189 190For suggestions etc. you may contact the maintainer directly at "pajas at ufal 191dot mff dot cuni dot cz", but in general, it is recommended to use the mailing 192list given below. 193 194For suggestions etc., and other issues related to XML::LibXML you may use the 195perl XML mailing list (perl-xml@listserv.ActiveState.com), where most 196XML-related Perl modules are discussed. In case of problems you should check 197the archives of that list first. Many problems are already discussed there. You 198can find the list's archives and subscription options at 199http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml 200 201 202PACKAGE HISTORY 203=============== 204 205Version < 0.98 were maintained by Matt Sergeant 206 2070.98 > Version > 1.49 were maintained by Matt Sergeant and Christian Glahn 208 209Versions >= 1.49 are maintained by Christian Glahn 210 211Versions > 1.56 are co-maintained by Petr Pajas 212 213Versions >= 1.59 are provisionally maintained by Petr Pajas 214 215 216PATCHES AND DEVELOPER VERSION 217============================= 218 219As XML::LibXML is open source software help and patches are appreciated. If you 220find a bug in the current release, make sure this bug still exists in the 221developer version of XML::LibXML. This version can be downloaded from its 222Subversion repository, e.g. via 223 224svn co svn://axkit.org/XML-LibXML/trunk 225 226Note that this account does not allow direct commits. 227 228Please consider all regression tests as correct. If any test fails it is most 229certainly related to a bug. 230 231If you find documentation bugs, please fix them in the libxml.dbk file, stored 232in the docs directory. 233 234 235KNOWN ISSUES 236============ 237 238The push-parser implementation causes memory leaks. 239 240