Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / libxml2 / 480363bdf57ea65106e6c4be4131656108c84121 / . / doc / upgrade.html
blob: 120cad0986e12447eec9937f7c074d93ec5cc123 [file] [log] [blame]
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]1<html>
2<head>
3 <title>Upgrading libxml client code from 1.x to 2.x</title>
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame^]4 <meta name="GENERATOR" content="amaya V4.1">
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]5 <meta http-equiv="Content-Type" content="text/html">
6</head>
7
8<body bgcolor="#ffffff">
9<h1 align="center">Upgrading libxml client code from 1.x to 2.x</h1>
10
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]11<h2>Incompatible changes:</h2>
12
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]13<p>Version 2 of libxml is the first version introducing serious backward
14incompatible changes. The main goals were:</p>
15<ul>
16 <li>a general cleanup. A number of mistakes inherited from the very early
17 versions couldn't be changed due to compatibility constraints. Example the
18 "childs" element in the nodes.</li>
19 <li>Uniformization of the various nodes, at least for their header and link
20 parts (doc, parent, children, prev, next), the goal is a simpler
21 programming model and simplifying the task of the DOM implementors.</li>
22 <li>better conformances to the XML specification, for example version 1.x
23 had an heuristic to try to detect ignorable white spaces. As a result the
24 SAX event generated were ignorableWhitespace() while the spec requires
25 character() in that case. This also mean that a number of DOM node
26 containing blank text may populate the DOM tree which were not present
27 before.</li>
28</ul>
29
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]30<h2>How to fix libxml-1.x code:</h2>
31
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]32<p>So client code of libxml designed to run with version 1.x may have to be
33changed to compile against version 2.x of libxml. Here is a list of changes
34that I have collected, they may not be sufficient, so in case you find other
35change which are required, <a href="mailto:Daniel.Ïeillardw3.org">drop me a
36mail</a>:</p>
37<ol>
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame^]38 <li>The package name have changed from libxml to libxml2, the library name
39 is now -lxml2 . There is a new xml2-config script which should be used to
40 select the right parameters libxml2</li>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]41 <li>Node <strong>childs</strong> field has been renamed
42 <strong>children</strong> so s/childs/children/g should be applied
43 (probablility of having "childs" anywere else is close to 0+</li>
44 <li>The document don't have anymore a <strong>root</strong> element it has
45 been replaced by <strong>children</strong> and usually you will get a list
Daniel Veillardf13e1ed2000-03-06 07:41:49 +0000[diff] [blame]46 of element here. For example a Dtd element for the internal subset and
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]47 it's declaration may be found in that list, as well as processing
48 instructions or comments found before or after the document root element.
49 Use <strong>xmlDocGetRootElement(doc)</strong> to get the root element of
50 a document. Alternatively if you are sure to not reference Dtds nor have
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame^]51 PIs or comments before or after the root element
52 s/-&gt;root/-&gt;children/g will probably do it.</li>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]53 <li>The white space issue, this one is more complex, unless special case of
54 validating parsing, the line breaks and spaces usually used for indenting
55 and formatting the document content becomes significant. So they are
56 reported by SAX and if your using the DOM tree, corresponding nodes are
57 generated. Too approach can be taken:
58 <ol>
59 <li>lazy one, use the compatibility call
60 <strong>xmlKeepBlanksDefault(0)</strong> but be aware that you are
61 relying on a special (and possibly broken) set of heuristics of libxml
62 to detect ignorable blanks. Don't complain if it breaks or make your
63 application not 100% clean w.r.t. to it's input.</li>
64 <li>the Right Way: change you code to accept possibly unsignificant
65 blanks characters, or have your tree populated with weird blank text
66 nodes. You can spot them using the comodity function
67 <strong>xmlIsBlankNode(node)</strong> returning 1 for such blank
68 nodes.</li>
69 </ol>
70 <p>Note also that with the new default the output functions don't add any
71 extra indentation when saving a tree in order to be able to round trip
72 (read and save) without inflating the document with extra formatting
73 chars.</p>
74 </li>
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]75 <li>The include path has changed to $prefix/libxml/ and the includes
76 themselves uses this new prefix in includes instructions... If you are
Daniel Veillard5e873c42000-04-12 13:27:38 +0000[diff] [blame]77 using (as expected) the
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame^]78 <pre>xml2-config --cflags</pre>
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]79 <p>output to generate you compile commands this will probably work out of
80 the box</p>
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]81 </li>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]82</ol>
83
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]84<h2>Ensuring both libxml-1.x and libxml-2.x compatibility</h2>
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]85
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame^]86<p>Two new version of libxml (1.8.11) and libxml2 (2.3.4) have been released
87to allow smoth upgrade of existing libxml v1code while retaining
88compatibility. They offers the following:</p>
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]89<ol>
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]90 <li>similar include naming, one should use
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame^]91 <strong>#include&lt;libxml/...&gt;</strong> in both cases.</li>
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]92 <li>similar identifiers defined via macros for the child and root fields:
93 respectively <strong>xmlChildrenNode</strong> and
Daniel Veillardd83eb822000-06-30 18:39:56 +0000[diff] [blame]94 <strong>xmlRootNode</strong></li>
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]95 <li>a new macro <strong>LIBXML_TEST_VERSION</strong> which should be
96 inserted once in the client code</li>
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]97</ol>
98
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]99<p>So the roadmap to upgrade your existing libxml applications is the
100following:</p>
101<ol>
102 <li>install the libxml-1.8.8 (and libxml-devel-1.8.8) packages</li>
103 <li>find all occurences where the xmlDoc <strong>root</strong> field is used
104 and change it to <strong>xmlRootNode</strong></li>
105 <li>similary find all occurences where the xmlNode <strong>childs</strong>
106 field is used and change it to <strong>xmlChildrenNode</strong></li>
107 <li>add a <strong>LIBXML_TEST_VERSION</strong> macro somewhere in your
108 <strong>main()</strong> or in the library init entry point</li>
109 <li>Recompile, check compatibility, it should still work</li>
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame^]110 <li>Change your configure script to look first for xml2-config and fallback
111 using xml-config . Use the --cflags and --libs ouptut of the command as
112 the Include and Linking parameters needed to use libxml.</li>
113 <li>install libxml2-2.3.x and libxml2-devel-2.3.x (libxml-1.8.y and
114 libxml-devel-1.8.y can be kept simultaneously)</li>
Daniel Veillardc2304102000-06-29 00:43:27 +0000[diff] [blame]115 <li>remove your config.cache, relaunch your configuration mechanism, and
116 recompile, if steps 2 and 3 were done right it should compile as-is</li>
117 <li>Test that your application is still running correctly, if not this may
118 be due to extra empty nodes due to formating spaces being kept in libxml2
119 contrary to libxml1, in that case insert xmlKeepBlanksDefault(1) in your
120 code before calling the parser (next to
121 <strong>LIBXML_TEST_VERSION</strong> is a fine place).</li>
122</ol>
123
Daniel Veillardd83eb822000-06-30 18:39:56 +0000[diff] [blame]124<p>Following those steps should work. It worked for some of my own code.</p>
Daniel Veillardf3029822000-05-06 08:11:19 +0000[diff] [blame]125
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]126<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]127libxml 1.x to 2.x than the ones you may have to patch for. The overall code
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]128has been considerably improved and the conformance to the XML specification
129has been drastically improve. Don't take those changes as an excuse to not
130upgrade, it may cost a lot on the long term ...</p>
131
132<p><a href="mailto:Daniel.Veillard@w3.org">Daniel Veillard</a></p>
133
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame^]134<p>$Id: upgrade.html,v 1.7 2000/06/30 18:39:56 veillard Exp $</p>
Daniel Veillard3e6d2372000-03-04 11:39:43 +0000[diff] [blame]135</body>
136</html>