blob: b44ca96c273cc4230f20bb17949e24e095919391 [file] [log] [blame]
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="SHORTCUT ICON" href="/favicon.ico" /><style type="text/css">
TD {font-family: Verdana,Arial,Helvetica}
BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>Upgrading 1.x code</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Upgrading 1.x code</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Developer Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html" style="font-weight:bold">Main Menu</a></li><li><a href="html/index.html" style="font-weight:bold">Reference Manual</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="tutorial/index.html">Tutorial</a></li><li><a href="xmlreader.html">The Reader Interface</a></li><li><a href="ChangeLog.html">ChangeLog</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="python.html">Python and bindings</a></li><li><a href="architecture.html">libxml2 architecture</a></li><li><a href="tree.html">The tree output</a></li><li><a href="interface.html">The SAX interface</a></li><li><a href="xmlmem.html">Memory Management</a></li><li><a href="xmlio.html">I/O Interfaces</a></li><li><a href="library.html">The parser interfaces</a></li><li><a href="entities.html">Entities or no entities</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="upgrade.html">Upgrading 1.x code</a></li><li><a href="threads.html">Thread safety</a></li><li><a href="DOM.html">DOM Principles</a></li><li><a href="example.html">A real example</a></li><li><a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="APIchunk0.html">Alphabetic</a></li><li><a href="APIconstructors.html">Constructors</a></li><li><a href="APIfunctions.html">Functions/Types</a></li><li><a href="APIfiles.html">Modules</a></li><li><a href="APIsymbols.html">Symbols</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>Incompatible changes:</p><p>Version 2 of libxml2 is the first version introducing serious
backwardincompatible changes. The main goals were:</p><ul><li>a general cleanup. A number of mistakes inherited from the very
earlyversions couldn't be changed due to compatibility constraints.
Examplethe "childs" element in the nodes.</li>
<li>Uniformization of the various nodes, at least for their header and
linkparts (doc, parent, children, prev, next), the goal is a
simplerprogramming model and simplifying the task of the DOM
implementors.</li>
<li>better conformances to the XML specification, for example version
1.xhad an heuristic to try to detect ignorable white spaces. As a result
theSAX event generated were ignorableWhitespace() while the spec
requirescharacter() in that case. This also mean that a number of DOM
nodecontaining blank text may populate the DOM tree which were not
presentbefore.</li>
</ul><h3>How to fix libxml-1.x code:</h3><p>So client code of libxml designed to run with version 1.x may have to
bechanged to compile against version 2.x of libxml. Here is a list of
changesthat I have collected, they may not be sufficient, so in case you find
otherchange which are required, <a href="mailto:Daniel.Veillard@w3.org">drop
me amail</a>:</p><ol><li>The package name have changed from libxml to libxml2, the library
nameis now -lxml2 . There is a new xml2-config script which should be
used toselect the right parameters libxml2</li>
<li>Node <strong>childs</strong>field has been
renamed<strong>children</strong>so s/childs/children/g should be
applied(probability of having "childs" anywhere else is close to 0+</li>
<li>The document don't have anymore a <strong>root</strong>element it
hasbeen replaced by <strong>children</strong>and usually you will get
alist of element here. For example a Dtd element for the internal
subsetand it's declaration may be found in that list, as well as
processinginstructions or comments found before or after the document
root element.Use <strong>xmlDocGetRootElement(doc)</strong>to get the
root element ofa document. Alternatively if you are sure to not reference
DTDs nor havePIs or comments before or after the root
elements/-&gt;root/-&gt;children/g will probably do it.</li>
<li>The white space issue, this one is more complex, unless special case
ofvalidating parsing, the line breaks and spaces usually used for
indentingand formatting the document content becomes significant. So they
arereported by SAX and if your using the DOM tree, corresponding nodes
aregenerated. Too approach can be taken:
<ol><li>lazy one, use the compatibility
call<strong>xmlKeepBlanksDefault(0)</strong>but be aware that you
arerelying on a special (and possibly broken) set of heuristics
oflibxml to detect ignorable blanks. Don't complain if it breaks
ormake your application not 100% clean w.r.t. to it's input.</li>
<li>the Right Way: change you code to accept possibly
insignificantblanks characters, or have your tree populated with
weird blank textnodes. You can spot them using the commodity
function<strong>xmlIsBlankNode(node)</strong>returning 1 for such
blanknodes.</li>
</ol><p>Note also that with the new default the output functions don't add
anyextra indentation when saving a tree in order to be able to round
trip(read and save) without inflating the document with extra
formattingchars.</p>
</li>
<li>The include path has changed to $prefix/libxml/ and the
includesthemselves uses this new prefix in includes instructions... If
you areusing (as expected) the
<pre>xml2-config --cflags</pre>
<p>output to generate you compile commands this will probably work out
ofthe box</p>
</li>
<li>xmlDetectCharEncoding takes an extra argument indicating the length
inbyte of the head of the document available for character detection.</li>
</ol><h3>Ensuring both libxml-1.x and libxml-2.x compatibility</h3><p>Two new version of libxml (1.8.11) and libxml2 (2.3.4) have been
releasedto allow smooth upgrade of existing libxml v1code while
retainingcompatibility. They offers the following:</p><ol><li>similar include naming, one should
use<strong>#include&lt;libxml/...&gt;</strong>in both cases.</li>
<li>similar identifiers defined via macros for the child and root
fields:respectively
<strong>xmlChildrenNode</strong>and<strong>xmlRootNode</strong></li>
<li>a new macro <strong>LIBXML_TEST_VERSION</strong>which should beinserted
once in the client code</li>
</ol><p>So the roadmap to upgrade your existing libxml applications is
thefollowing:</p><ol><li>install the libxml-1.8.8 (and libxml-devel-1.8.8) packages</li>
<li>find all occurrences where the xmlDoc <strong>root</strong>field isused
and change it to <strong>xmlRootNode</strong></li>
<li>similarly find all occurrences where the
xmlNode<strong>childs</strong>field is used and change it
to<strong>xmlChildrenNode</strong></li>
<li>add a <strong>LIBXML_TEST_VERSION</strong>macro somewhere in
your<strong>main()</strong>or in the library init entry point</li>
<li>Recompile, check compatibility, it should still work</li>
<li>Change your configure script to look first for xml2-config and fallback
using xml-config . Use the --cflags and --libs output of the commandas
the Include and Linking parameters needed to use libxml.</li>
<li>install libxml2-2.3.x and libxml2-devel-2.3.x (libxml-1.8.y
andlibxml-devel-1.8.y can be kept simultaneously)</li>
<li>remove your config.cache, relaunch your configuration mechanism,
andrecompile, if steps 2 and 3 were done right it should compile
as-is</li>
<li>Test that your application is still running correctly, if not this
maybe due to extra empty nodes due to formating spaces being kept in
libxml2contrary to libxml1, in that case insert xmlKeepBlanksDefault(1)
in yourcode before calling the parser (next
to<strong>LIBXML_TEST_VERSION</strong>is a fine place).</li>
</ol><p>Following those steps should work. It worked for some of my own code.</p><p>Let me put some emphasis on the fact that there is far more changes
fromlibxml 1.x to 2.x than the ones you may have to patch for. The overall
codehas been considerably cleaned up and the conformance to the XML
specificationhas been drastically improved too. Don't take those changes as
an excuse tonot upgrade, it may cost a lot on the long term ...</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>