README
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