upgrade.html revision 8badcee6a9e9d4bda74005bdde3bc709ec998d17
1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<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"> 4TD {font-family: Verdana,Arial,Helvetica} 5BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em} 6H1 {font-family: Verdana,Arial,Helvetica} 7H2 {font-family: Verdana,Arial,Helvetica} 8H3 {font-family: Verdana,Arial,Helvetica} 9A:link, A:visited, A:active { text-decoration: underline } 10</style><title>Upgrading 1.x code</title></head><body bgcolor="#8b7765" text="#000000" link="#000000" 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="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://garypennington.net/libxml2/">Solaris binaries</a></li><li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal 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 backward 11incompatible changes. The main goals were:</p><ul><li>a general cleanup. A number of mistakes inherited from the very early 12 versions couldn't be changed due to compatibility constraints. Example 13 the "childs" element in the nodes.</li> 14 <li>Uniformization of the various nodes, at least for their header and link 15 parts (doc, parent, children, prev, next), the goal is a simpler 16 programming model and simplifying the task of the DOM implementors.</li> 17 <li>better conformances to the XML specification, for example version 1.x 18 had an heuristic to try to detect ignorable white spaces. As a result the 19 SAX event generated were ignorableWhitespace() while the spec requires 20 character() in that case. This also mean that a number of DOM node 21 containing blank text may populate the DOM tree which were not present 22 before.</li> 23</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 be 24changed to compile against version 2.x of libxml. Here is a list of changes 25that I have collected, they may not be sufficient, so in case you find other 26change which are required, <a href="mailto:Daniel.Veillard@w3.org">drop me a 27mail</a>:</p><ol><li>The package name have changed from libxml to libxml2, the library name 28 is now -lxml2 . There is a new xml2-config script which should be used to 29 select the right parameters libxml2</li> 30 <li>Node <strong>childs</strong> field has been renamed 31 <strong>children</strong> so s/childs/children/g should be applied 32 (probability of having "childs" anywhere else is close to 0+</li> 33 <li>The document don't have anymore a <strong>root</strong> element it has 34 been replaced by <strong>children</strong> and usually you will get a 35 list of element here. For example a Dtd element for the internal subset 36 and it's declaration may be found in that list, as well as processing 37 instructions or comments found before or after the document root element. 38 Use <strong>xmlDocGetRootElement(doc)</strong> to get the root element of 39 a document. Alternatively if you are sure to not reference DTDs nor have 40 PIs or comments before or after the root element 41 s/->root/->children/g will probably do it.</li> 42 <li>The white space issue, this one is more complex, unless special case of 43 validating parsing, the line breaks and spaces usually used for indenting 44 and formatting the document content becomes significant. So they are 45 reported by SAX and if your using the DOM tree, corresponding nodes are 46 generated. Too approach can be taken: 47 <ol><li>lazy one, use the compatibility call 48 <strong>xmlKeepBlanksDefault(0)</strong> but be aware that you are 49 relying on a special (and possibly broken) set of heuristics of 50 libxml to detect ignorable blanks. Don't complain if it breaks or 51 make your application not 100% clean w.r.t. to it's input.</li> 52 <li>the Right Way: change you code to accept possibly insignificant 53 blanks characters, or have your tree populated with weird blank text 54 nodes. You can spot them using the commodity function 55 <strong>xmlIsBlankNode(node)</strong> returning 1 for such blank 56 nodes.</li> 57 </ol><p>Note also that with the new default the output functions don't add any 58 extra indentation when saving a tree in order to be able to round trip 59 (read and save) without inflating the document with extra formatting 60 chars.</p> 61 </li> 62 <li>The include path has changed to $prefix/libxml/ and the includes 63 themselves uses this new prefix in includes instructions... If you are 64 using (as expected) the 65 <pre>xml2-config --cflags</pre> 66 <p>output to generate you compile commands this will probably work out of 67 the box</p> 68 </li> 69 <li>xmlDetectCharEncoding takes an extra argument indicating the length in 70 byte of the head of the document available for character detection.</li> 71</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 released 72to allow smooth upgrade of existing libxml v1code while retaining 73compatibility. They offers the following:</p><ol><li>similar include naming, one should use 74 <strong>#include<libxml/...></strong> in both cases.</li> 75 <li>similar identifiers defined via macros for the child and root fields: 76 respectively <strong>xmlChildrenNode</strong> and 77 <strong>xmlRootNode</strong></li> 78 <li>a new macro <strong>LIBXML_TEST_VERSION</strong> which should be 79 inserted once in the client code</li> 80</ol><p>So the roadmap to upgrade your existing libxml applications is the 81following:</p><ol><li>install the libxml-1.8.8 (and libxml-devel-1.8.8) packages</li> 82 <li>find all occurrences where the xmlDoc <strong>root</strong> field is 83 used and change it to <strong>xmlRootNode</strong></li> 84 <li>similarly find all occurrences where the xmlNode 85 <strong>childs</strong> field is used and change it to 86 <strong>xmlChildrenNode</strong></li> 87 <li>add a <strong>LIBXML_TEST_VERSION</strong> macro somewhere in your 88 <strong>main()</strong> or in the library init entry point</li> 89 <li>Recompile, check compatibility, it should still work</li> 90 <li>Change your configure script to look first for xml2-config and fall 91 back using xml-config . Use the --cflags and --libs output of the command 92 as the Include and Linking parameters needed to use libxml.</li> 93 <li>install libxml2-2.3.x and libxml2-devel-2.3.x (libxml-1.8.y and 94 libxml-devel-1.8.y can be kept simultaneously)</li> 95 <li>remove your config.cache, relaunch your configuration mechanism, and 96 recompile, if steps 2 and 3 were done right it should compile as-is</li> 97 <li>Test that your application is still running correctly, if not this may 98 be due to extra empty nodes due to formating spaces being kept in libxml2 99 contrary to libxml1, in that case insert xmlKeepBlanksDefault(1) in your 100 code before calling the parser (next to 101 <strong>LIBXML_TEST_VERSION</strong> is a fine place).</li> 102</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 from 103libxml 1.x to 2.x than the ones you may have to patch for. The overall code 104has been considerably cleaned up and the conformance to the XML specification 105has been drastically improved too. Don't take those changes as an excuse to 106not 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> 107
