Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libxml2 / 9110ed633b4b9a2f07930354a20b8c2b52f765cd / . / doc / upgrade.html
blob: 59815ba0bd1c2da6ad626d5e1962793da48787d2 [file] [log] [blame]
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]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">
Daniel Veillard373a4752002-02-21 14:46:29 +0000[diff] [blame]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}
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]9A:link, A:visited, A:active { text-decoration: underline }
Daniel Veillardd463c992006-02-23 22:07:59 +0000[diff] [blame]10</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 backward
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]11incompatible changes. The main goals were:</p><ul><li>a general cleanup. A number of mistakes inherited from the very early
Daniel Veillard585b4ea2001-10-24 07:26:23 +0000[diff] [blame]12 versions couldn't be changed due to compatibility constraints. Example
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]13 the "childs" element in the nodes.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]14 <li>Uniformization of the various nodes, at least for their header and link
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]15 parts (doc, parent, children, prev, next), the goal is a simpler
16 programming model and simplifying the task of the DOM implementors.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]17 <li>better conformances to the XML specification, for example version 1.x
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]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>
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]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
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]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
Daniel Veillardfc8dc352003-10-18 09:07:46 +0000[diff] [blame]26change which are required, <a href="mailto:Daniel.Veillard@w3.org">drop me a
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]27mail</a>:</p><ol><li>The package name have changed from libxml to libxml2, the library name
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]28 is now -lxml2 . There is a new xml2-config script which should be used to
29 select the right parameters libxml2</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]30 <li>Node <strong>childs</strong> field has been renamed
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]31 <strong>children</strong> so s/childs/children/g should be applied
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]32 (probability of having "childs" anywhere else is close to 0+</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]33 <li>The document don't have anymore a <strong>root</strong> element it has
Daniel Veillard585b4ea2001-10-24 07:26:23 +0000[diff] [blame]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
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]37 instructions or comments found before or after the document root element.
38 Use <strong>xmlDocGetRootElement(doc)</strong> to get the root element of
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]39 a document. Alternatively if you are sure to not reference DTDs nor have
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]40 PIs or comments before or after the root element
41 s/-&gt;root/-&gt;children/g will probably do it.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]42 <li>The white space issue, this one is more complex, unless special case of
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]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:
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]47 <ol><li>lazy one, use the compatibility call
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]48 <strong>xmlKeepBlanksDefault(0)</strong> but be aware that you are
Daniel Veillard585b4ea2001-10-24 07:26:23 +0000[diff] [blame]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>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]52 <li>the Right Way: change you code to accept possibly insignificant
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]53 blanks characters, or have your tree populated with weird blank text
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]54 nodes. You can spot them using the commodity function
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]55 <strong>xmlIsBlankNode(node)</strong> returning 1 for such blank
56 nodes.</li>
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]57 </ol><p>Note also that with the new default the output functions don't add any
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]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>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]61 </li>
62 <li>The include path has changed to $prefix/libxml/ and the includes
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]63 themselves uses this new prefix in includes instructions... If you are
Daniel Veillard5e873c42000-04-12 13:27:38 +0000[diff] [blame]64 using (as expected) the
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]65 <pre>xml2-config --cflags</pre>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]66 <p>output to generate you compile commands this will probably work out of
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]67 the box</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]68 </li>
69 <li>xmlDetectCharEncoding takes an extra argument indicating the length in
Daniel Veillard585b4ea2001-10-24 07:26:23 +0000[diff] [blame]70 byte of the head of the document available for character detection.</li>
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]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
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]72to allow smooth upgrade of existing libxml v1code while retaining
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]73compatibility. They offers the following:</p><ol><li>similar include naming, one should use
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]74 <strong>#include&lt;libxml/...&gt;</strong> in both cases.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]75 <li>similar identifiers defined via macros for the child and root fields:
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]76 respectively <strong>xmlChildrenNode</strong> and
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]77 <strong>xmlRootNode</strong></li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]78 <li>a new macro <strong>LIBXML_TEST_VERSION</strong> which should be
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]79 inserted once in the client code</li>
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]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>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]82 <li>find all occurrences where the xmlDoc <strong>root</strong> field is
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]83 used and change it to <strong>xmlRootNode</strong></li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]84 <li>similarly find all occurrences where the xmlNode
Daniel Veillardc0801af2002-05-28 16:28:42 +0000[diff] [blame]85 <strong>childs</strong> field is used and change it to
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]86 <strong>xmlChildrenNode</strong></li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]87 <li>add a <strong>LIBXML_TEST_VERSION</strong> macro somewhere in your
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]88 <strong>main()</strong> or in the library init entry point</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]89 <li>Recompile, check compatibility, it should still work</li>
90 <li>Change your configure script to look first for xml2-config and fall
Daniel Veillardc0801af2002-05-28 16:28:42 +0000[diff] [blame]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>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]93 <li>install libxml2-2.3.x and libxml2-devel-2.3.x (libxml-1.8.y and
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]94 libxml-devel-1.8.y can be kept simultaneously)</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]95 <li>remove your config.cache, relaunch your configuration mechanism, and
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]96 recompile, if steps 2 and 3 were done right it should compile as-is</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]97 <li>Test that your application is still running correctly, if not this may
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]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>
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]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
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]103libxml 1.x to 2.x than the ones you may have to patch for. The overall code
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]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
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]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>