<?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
seriousbackwardincompatible changes. The main goals were:</p><ul><li>a general cleanup. A number of mistakes inherited from the
veryearlyversions 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
andlinkparts (doc, parent, children, prev, next), the goal is
asimplerprogramming model and simplifying the task of the
DOMimplementors.</li>
<li>better conformances to the XML specification, for example version1.xhad
an heuristic to try to detect ignorable white spaces. As a resulttheSAX
event generated were ignorableWhitespace() while the
specrequirescharacter() in that case. This also mean that a number of
DOMnodecontaining blank text may populate the DOM tree which were
notpresentbefore.</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
tobechanged to compile against version 2.x of libxml. Here is a list
ofchangesthat I have collected, they may not be sufficient, so in case you
findotherchange which are required, <a href="mailto:Daniel.Veillard@w3.org">dropme amail</a>:</p><ol><li>The package name have changed from libxml to libxml2, the librarynameis
now -lxml2 . There is a new xml2-config script which should beused
toselect the right parameters libxml2</li>
<li>Node <strong>childs</strong>field has
beenrenamed<strong>children</strong>so s/childs/children/g should
beapplied(probability of having "childs" anywhere else is close to 0+</li>
<li>The document don't have anymore a <strong>root</strong>element
ithasbeen replaced by <strong>children</strong>and usually you will
getalist of element here. For example a Dtd element for the
internalsubsetand it's declaration may be found in that list, as well
asprocessinginstructions or comments found before or after the
documentroot element.Use <strong>xmlDocGetRootElement(doc)</strong>to get
theroot element ofa document. Alternatively if you are sure to not
referenceDTDs nor havePIs or comments before or after the
rootelements/->root/->children/g will probably do it.</li>
<li>The white space issue, this one is more complex, unless special
caseofvalidating parsing, the line breaks and spaces usually used
forindentingand formatting the document content becomes significant. So
theyarereported by SAX and if your using the DOM tree, corresponding
nodesaregenerated. Too approach can be taken:
<ol><li>lazy one, use the
compatibilitycall<strong>xmlKeepBlanksDefault(0)</strong>but be aware
that youarerelying on a special (and possibly broken) set of
heuristicsoflibxml to detect ignorable blanks. Don't complain if it
breaksormake your application not 100% clean w.r.t. to it's
input.</li>
<li>the Right Way: change you code to accept
possiblyinsignificantblanks characters, or have your tree populated
withweird blank textnodes. You can spot them using the
commodityfunction<strong>xmlIsBlankNode(node)</strong>returning 1 for
suchblanknodes.</li>
</ol><p>Note also that with the new default the output functions don't
addanyextra indentation when saving a tree in order to be able to
roundtrip(read and save) without inflating the document with
extraformattingchars.</p>
</li>
<li>The include path has changed to $prefix/libxml/ and
theincludesthemselves uses this new prefix in includes instructions...
Ifyou areusing (as expected) the
<pre>xml2-config --cflags</pre>
<p>output to generate you compile commands this will probably work
outofthe box</p>
</li>
<li>xmlDetectCharEncoding takes an extra argument indicating the
lengthinbyte 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 beenreleasedto
allow smooth upgrade of existing libxml v1code whileretainingcompatibility.
They offers the following:</p><ol><li>similar include naming, one
shoulduse<strong>#include<libxml/...></strong>in both cases.</li>
<li>similar identifiers defined via macros for the child and
rootfields:respectively<strong>xmlChildrenNode</strong>and<strong>xmlRootNode</strong></li>
<li>a new macro <strong>LIBXML_TEST_VERSION</strong>which should
beinsertedonce in the client code</li>
</ol><p>So the roadmap to upgrade your existing libxml applications
isthefollowing:</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
isusedand change it to <strong>xmlRootNode</strong></li>
<li>similarly find all occurrences where
thexmlNode<strong>childs</strong>field is used and change
itto<strong>xmlChildrenNode</strong></li>
<li>add a <strong>LIBXML_TEST_VERSION</strong>macro somewhere
inyour<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
fallbackusing xml-config . Use the --cflags and --libs output of the
commandasthe Include and Linking parameters needed to use libxml.</li>
<li>install libxml2-2.3.x and libxml2-devel-2.3.x
(libxml-1.8.yandlibxml-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
compileas-is</li>
<li>Test that your application is still running correctly, if not thismaybe
due to extra empty nodes due to formating spaces being kept
inlibxml2contrary to libxml1, in that case insert
xmlKeepBlanksDefault(1)in yourcode before calling the parser
(nextto<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
changesfromlibxml 1.x to 2.x than the ones you may have to patch for. The
overallcodehas been considerably cleaned up and the conformance to the
XMLspecificationhas been drastically improved too. Don't take those changes
asan 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>
