Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / libxml2 / d2fd1b67ecbd8aa448c14886d36700585125021c / . / doc / upgrade.html
blob: 6c0b77334f81061ca6107e34b34c864c41296d5a [file] [log] [blame]
Daniel Veillard43d3f612001-11-10 11:57:23 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]2<html>
3<head>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
Daniel Veillardc332dab2002-03-29 14:08:27 +0000[diff] [blame]5<link rel="SHORTCUT ICON" href="/favicon.ico">
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]6<style type="text/css"><!--
Daniel Veillard373a4752002-02-21 14:46:29 +0000[diff] [blame]7TD {font-family: Verdana,Arial,Helvetica}
8BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
9H1 {font-family: Verdana,Arial,Helvetica}
10H2 {font-family: Verdana,Arial,Helvetica}
11H3 {font-family: Verdana,Arial,Helvetica}
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]12A:link, A:visited, A:active { text-decoration: underline }
13--></style>
14<title>Upgrading 1.x code</title>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]15</head>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]16<body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
17<table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
18<td width="180">
19<a href="http://www.gnome.org/"><img src="smallfootonly.gif" alt="Gnome 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>
20</td>
21<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">
22<h1>The XML C library for Gnome</h1>
23<h2>Upgrading 1.x code</h2>
24</td></tr></table></td></tr></table></td>
25</tr></table>
26<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>
27<td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td>
28<table width="100%" border="0" cellspacing="1" cellpadding="3">
29<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr>
Daniel Veillard8acca112002-01-21 09:52:27 +0000[diff] [blame]30<tr><td bgcolor="#fffacd"><ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]31<li><a href="index.html">Home</a></li>
32<li><a href="intro.html">Introduction</a></li>
33<li><a href="FAQ.html">FAQ</a></li>
34<li><a href="docs.html">Documentation</a></li>
35<li><a href="bugs.html">Reporting bugs and getting help</a></li>
36<li><a href="help.html">How to help</a></li>
37<li><a href="downloads.html">Downloads</a></li>
38<li><a href="news.html">News</a></li>
Daniel Veillard7b602b42002-01-08 13:26:00 +0000[diff] [blame]39<li><a href="XMLinfo.html">XML</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]40<li><a href="XSLT.html">XSLT</a></li>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]41<li><a href="python.html">Python and bindings</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]42<li><a href="architecture.html">libxml architecture</a></li>
43<li><a href="tree.html">The tree output</a></li>
44<li><a href="interface.html">The SAX interface</a></li>
45<li><a href="xmldtd.html">Validation &amp; DTDs</a></li>
46<li><a href="xmlmem.html">Memory Management</a></li>
47<li><a href="encoding.html">Encodings support</a></li>
48<li><a href="xmlio.html">I/O Interfaces</a></li>
49<li><a href="catalog.html">Catalog support</a></li>
50<li><a href="library.html">The parser interfaces</a></li>
51<li><a href="entities.html">Entities or no entities</a></li>
52<li><a href="namespaces.html">Namespaces</a></li>
53<li><a href="upgrade.html">Upgrading 1.x code</a></li>
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]54<li><a href="threads.html">Thread safety</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]55<li><a href="DOM.html">DOM Principles</a></li>
56<li><a href="example.html">A real example</a></li>
57<li><a href="contribs.html">Contributions</a></li>
58<li>
59<a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a>
60</li>
61</ul></td></tr>
62</table>
63<table width="100%" border="0" cellspacing="1" cellpadding="3">
Daniel Veillard3bf65be2002-01-23 12:36:34 +0000[diff] [blame]64<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr>
65<tr><td bgcolor="#fffacd"><ul>
Daniel Veillardf8592562002-01-23 17:58:17 +0000[diff] [blame]66<li><a href="APIchunk0.html">Alphabetic</a></li>
Daniel Veillard3bf65be2002-01-23 12:36:34 +0000[diff] [blame]67<li><a href="APIconstructors.html">Constructors</a></li>
68<li><a href="APIfunctions.html">Functions/Types</a></li>
69<li><a href="APIfiles.html">Modules</a></li>
70<li><a href="APIsymbols.html">Symbols</a></li>
71</ul></td></tr>
72</table>
73<table width="100%" border="0" cellspacing="1" cellpadding="3">
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]74<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
Daniel Veillard8acca112002-01-21 09:52:27 +0000[diff] [blame]75<tr><td bgcolor="#fffacd"><ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]76<li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li>
77<li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li>
Daniel Veillard4a859202002-01-08 11:49:22 +0000[diff] [blame]78<li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
Daniel Veillard2d347fa2002-03-17 10:34:11 +0000[diff] [blame]79<li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]80<li><a href="ftp://xmlsoft.org/">FTP</a></li>
81<li><a href="http://www.fh-frankfurt.de/~igor/projects/libxml/">Windows binaries</a></li>
Daniel Veillarddb9dfd92001-11-26 17:25:02 +0000[diff] [blame]82<li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
Daniel Veillarde6d8e202002-05-02 06:11:10 +0000[diff] [blame]83<li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li>
Daniel Veillard2d347fa2002-03-17 10:34:11 +0000[diff] [blame]84<li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&amp;product=libxml2">Bug Tracker</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]85</ul></td></tr>
86</table>
87</td></tr></table></td>
88<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">
89<p>Incompatible changes:</p>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]90<p>Version 2 of libxml is the first version introducing serious backward
91incompatible changes. The main goals were:</p>
92<ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]93<li>a general cleanup. A number of mistakes inherited from the very early
Daniel Veillard585b4ea2001-10-24 07:26:23 +0000[diff] [blame]94 versions couldn't be changed due to compatibility constraints. Example
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]95 the &quot;childs&quot; element in the nodes.</li>
96<li>Uniformization of the various nodes, at least for their header and link
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]97 parts (doc, parent, children, prev, next), the goal is a simpler
98 programming model and simplifying the task of the DOM implementors.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]99<li>better conformances to the XML specification, for example version 1.x
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]100 had an heuristic to try to detect ignorable white spaces. As a result the
101 SAX event generated were ignorableWhitespace() while the spec requires
102 character() in that case. This also mean that a number of DOM node
103 containing blank text may populate the DOM tree which were not present
104 before.</li>
105</ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]106<h3>How to fix libxml-1.x code:</h3>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]107<p>So client code of libxml designed to run with version 1.x may have to be
108changed to compile against version 2.x of libxml. Here is a list of changes
109that I have collected, they may not be sufficient, so in case you find other
Daniel Veillard9b6fd302002-05-13 12:06:47 +0000[diff] [blame]110change which are required, <a href="mailto:Daniel.%C3%8Feillardw3.org">drop me a
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]111mail</a>:</p>
112<ol>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]113<li>The package name have changed from libxml to libxml2, the library name
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]114 is now -lxml2 . There is a new xml2-config script which should be used to
115 select the right parameters libxml2</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]116<li>Node <strong>childs</strong> field has been renamed
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]117 <strong>children</strong> so s/childs/children/g should be applied
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]118 (probability of having &quot;childs&quot; anywhere else is close to 0+</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]119<li>The document don't have anymore a <strong>root</strong> element it has
Daniel Veillard585b4ea2001-10-24 07:26:23 +0000[diff] [blame]120 been replaced by <strong>children</strong> and usually you will get a
121 list of element here. For example a Dtd element for the internal subset
122 and it's declaration may be found in that list, as well as processing
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]123 instructions or comments found before or after the document root element.
124 Use <strong>xmlDocGetRootElement(doc)</strong> to get the root element of
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]125 a document. Alternatively if you are sure to not reference DTDs nor have
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]126 PIs or comments before or after the root element
127 s/-&gt;root/-&gt;children/g will probably do it.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]128<li>The white space issue, this one is more complex, unless special case of
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]129 validating parsing, the line breaks and spaces usually used for indenting
130 and formatting the document content becomes significant. So they are
131 reported by SAX and if your using the DOM tree, corresponding nodes are
132 generated. Too approach can be taken:
133 <ol>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]134<li>lazy one, use the compatibility call
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]135 <strong>xmlKeepBlanksDefault(0)</strong> but be aware that you are
Daniel Veillard585b4ea2001-10-24 07:26:23 +0000[diff] [blame]136 relying on a special (and possibly broken) set of heuristics of
137 libxml to detect ignorable blanks. Don't complain if it breaks or
138 make your application not 100% clean w.r.t. to it's input.</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]139<li>the Right Way: change you code to accept possibly insignificant
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]140 blanks characters, or have your tree populated with weird blank text
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]141 nodes. You can spot them using the commodity function
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]142 <strong>xmlIsBlankNode(node)</strong> returning 1 for such blank
143 nodes.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]144</ol>
145<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]146 extra indentation when saving a tree in order to be able to round trip
147 (read and save) without inflating the document with extra formatting
148 chars.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]149</li>
150<li>The include path has changed to $prefix/libxml/ and the includes
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]151 themselves uses this new prefix in includes instructions... If you are
Daniel Veillard5e873c42000-04-12 13:27:38 +0000[diff] [blame]152 using (as expected) the
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]153 <pre>xml2-config --cflags</pre>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]154<p>output to generate you compile commands this will probably work out of
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]155 the box</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]156</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]157<li>xmlDetectCharEncoding takes an extra argument indicating the length in
Daniel Veillard585b4ea2001-10-24 07:26:23 +0000[diff] [blame]158 byte of the head of the document available for character detection.</li>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]159</ol>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]160<h3>Ensuring both libxml-1.x and libxml-2.x compatibility</h3>
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]161<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]162to allow smooth upgrade of existing libxml v1code while retaining
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]163compatibility. They offers the following:</p>
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]164<ol>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]165<li>similar include naming, one should use
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]166 <strong>#include&lt;libxml/...&gt;</strong> in both cases.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]167<li>similar identifiers defined via macros for the child and root fields:
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]168 respectively <strong>xmlChildrenNode</strong> and
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]169 <strong>xmlRootNode</strong>
170</li>
171<li>a new macro <strong>LIBXML_TEST_VERSION</strong> which should be
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]172 inserted once in the client code</li>
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]173</ol>
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]174<p>So the roadmap to upgrade your existing libxml applications is the
175following:</p>
176<ol>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]177<li>install the libxml-1.8.8 (and libxml-devel-1.8.8) packages</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]178<li>find all occurrences where the xmlDoc <strong>root</strong> field is
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]179 used and change it to <strong>xmlRootNode</strong>
180</li>
Daniel Veillardc0801af2002-05-28 16:28:42 +0000[diff] [blame]181<li>similarly find all occurrences where the xmlNode
182 <strong>childs</strong> field is used and change it to
183 <strong>xmlChildrenNode</strong>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]184</li>
185<li>add a <strong>LIBXML_TEST_VERSION</strong> macro somewhere in your
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]186 <strong>main()</strong> or in the library init entry point</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]187<li>Recompile, check compatibility, it should still work</li>
Daniel Veillardc0801af2002-05-28 16:28:42 +0000[diff] [blame]188<li>Change your configure script to look first for xml2-config and fall
189 back using xml-config . Use the --cflags and --libs output of the command
190 as the Include and Linking parameters needed to use libxml.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]191<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]192 libxml-devel-1.8.y can be kept simultaneously)</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]193<li>remove your config.cache, relaunch your configuration mechanism, and
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]194 recompile, if steps 2 and 3 were done right it should compile as-is</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]195<li>Test that your application is still running correctly, if not this may
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]196 be due to extra empty nodes due to formating spaces being kept in libxml2
197 contrary to libxml1, in that case insert xmlKeepBlanksDefault(1) in your
198 code before calling the parser (next to
199 <strong>LIBXML_TEST_VERSION</strong> is a fine place).</li>
200</ol>
Daniel Veillardd83eb822000-06-30 18:39:56 +0000[diff] [blame]201<p>Following those steps should work. It worked for some of my own code.</p>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]202<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]203libxml 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]204has been considerably cleaned up and the conformance to the XML specification
205has been drastically improved too. Don't take those changes as an excuse to
206not upgrade, it may cost a lot on the long term ...</p>
Daniel Veillard3f4c40f2002-02-13 09:19:28 +0000[diff] [blame]207<p><a href="bugs.html">Daniel Veillard</a></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]208</td></tr></table></td></tr></table></td></tr></table></td>
209</tr></table></td></tr></table>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]210</body>
211</html>