Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libxml2 / 008186fc7fe681c4fa0abd831bc4cb244f46ab01 / . / doc / FAQ.html
blob: a47314e2b06f2f5caa24b15c75a20b4f68d8da74 [file] [log] [blame]
Daniel Veillardc654d602001-05-01 12:42:26 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]3<html>
4<head>
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]5 <title>Libxml Frequently Asked Questions</title>
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]6 <meta name="GENERATOR" content="amaya V5.0">
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]7 <meta http-equiv="Content-Type" content="text/html">
8</head>
9
10<body bgcolor="#ffffff">
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]11<h1 align="center">Libxml Frequently Asked Questions</h1>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]12
13<p>Location: <a
14href="http://xmlsoft.org/FAQ.html">http://xmlsoft.org/FAQ.html</a></p>
15
16<p>Libxml home page: <a href="http://xmlsoft.org/">http://xmlsoft.org/</a></p>
17
18<p>Mailing-list archive: <a
19href="http://xmlsoft.org/messages/">http://xmlsoft.org/messages/</a></p>
20
Daniel Veillardbe40c8b2000-07-14 12:10:59 +0000[diff] [blame]21<p>Version: $Revision$</p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]22
23<p>Table of Content:</p>
24<ul>
25 <li><a href="#Licence">Licence(s)</a></li>
26 <li><a href="#Installati">Installation</a></li>
27 <li><a href="#Compilatio">Compilation</a></li>
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]28 <li><a href="#Developer">Developer corner</a></li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]29</ul>
30
31<h2><a name="Licence">Licence</a>(s)</h2>
32<ol>
33 <li><em>Licensing Terms for libxml</em>
34 <p>libxml is released under 2 (compatible) licences:</p>
35 <ul>
36 <li>the <a href="http://www.gnu.org/copyleft/lgpl.html">LGPL</a>: GNU
37 Library General Public License</li>
38 <li>the <a
39 href="http://www.w3.org/Consortium/Legal/copyright-software-19980720.html">W3C
40 IPR</a>: very similar to the XWindow licence</li>
41 </ul>
42 </li>
43 <li><em>Can I embed libxml in a proprietary application ?</em>
44 <p>Yes. The W3C IPR allows you to also keep proprietary the changes you
45 made to libxml, but it would be graceful to provide back bugfixes and
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]46 improvements as patches for possible incorporation in the main
47 development tree</p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]48 </li>
49</ol>
50
51<h2><a name="Installati">Installation</a></h2>
52<ol>
Daniel Veillarde0c1d722001-03-21 10:28:36 +0000[diff] [blame]53 <li>Unless you are forced to because your application links with a Gnome
54 library requiring it, <strong><span style="background-color: #FF0000">Do
55 Not Use libxml1</span></strong>, use libxml2</li>
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]56 <li><em>Where can I get libxml</em>
57 ?
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]58 <p>The original distribution comes from <a
59 href="ftp://rpmfind.net/pub/libxml/">rpmfind.net</a> or <a
60 href="ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxml/">gnome.org</a></p>
61 <p>Most linux and Bsd distribution includes libxml, this is probably the
62 safer way for end-users</p>
63 <p>David Doolin provides precompiled Windows versions at <a
Daniel Veillarde9202a02000-10-16 16:58:19 +0000[diff] [blame]64 href="http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/ ">http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/</a></p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]65 </li>
66 <li><em>I see libxml and libxml2 releases, which one should I install ?</em>
67 <ul>
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]68 <li>If you are not concerned by any existing backward compatibility
69 with existing application, install libxml2 only</li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]70 <li>If you are not doing development, you can safely install both.
71 usually the packages <a
72 href="http://rpmfind.net/linux/RPM/libxml.html">libxml</a> and <a
73 href="http://rpmfind.net/linux/RPM/libxml2.html">libxml2</a> are
74 compatible (this is not the case for development packages)</li>
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]75 <li>If you are a developer and your system provides separate packaging
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]76 for shared libraries and the development components, it is possible
77 to install libxml and libxml2, and also <a
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]78 href="http://rpmfind.net/linux/RPM/libxml-devel.html">libxml-devel</a>
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]79 and <a
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]80 href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml2-devel</a>
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]81 too for libxml2 &gt;= 2.3.0</li>
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]82 <li>If you are developing a new application, please develop against
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]83 libxml2(-devel)</li>
84 </ul>
85 </li>
86 <li><em>I can't install the libxml package it conflicts with libxml0</em>
87 <p>You probably have an old libxml0 package used to provide the shared
88 library for libxml.so.0, you can probably safely remove it. Anyway the
89 libxml packages provided on <a
90 href="ftp://rpmfind.net/pub/libxml/">rpmfind.net</a> provides
91 libxml.so.0</p>
92 </li>
Daniel Veillardc654d602001-05-01 12:42:26 +0000[diff] [blame]93 <li><em>I can't install the libxml(2) RPM package due to failed
94 dependancies</em>
95 <p>The most generic solution is to refetch the latest src.rpm , and
96 rebuild it locally with</p>
97 <p><code>rpm --rebuild libxml(2)-xxx.src.rpm</code></p>
98 <p>if everything goes well it will generate two binary rpm (one providing
99 the shared libs and xmllint, and the other one, the -devel package
100 providing includes, static libraries and scripts needed to build
101 applications with libxml(2)) that you can install locally.</p>
102 </li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]103</ol>
104
105<h2><a name="Compilatio">Compilation</a></h2>
106<ol>
107 <li><em>What is the process to compile libxml ?</em>
108 <p>As most UNIX libraries libxml follows the "standard":</p>
109 <p><code>gunzip -c xxx.tar.gz | tar xvf -</code></p>
110 <p><code>cd libxml-xxxx</code></p>
111 <p><code>./configure --help</code></p>
112 <p>to see the options, then the compilation/installation proper</p>
113 <p><code>./configure [possible options]</code></p>
114 <p><code>make</code></p>
115 <p><code>make install</code></p>
116 <p>At that point you may have to rerun ldconfig or similar utility to
117 update your list of installed shared libs.</p>
118 </li>
119 <li><em>What other libraries are needed to compile/install libxml ?</em>
120 <p>Libxml does not requires any other library, the normal C ANSI API
121 should be sufficient (please report any violation to this rule you may
122 find).</p>
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]123 <p>However if found at configuration time libxml will detect and use the
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]124 following libs:</p>
125 <ul>
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]126 <li><a href="http://www.info-zip.org/pub/infozip/zlib/">libz</a>
127 : a highly portable and available widely compression library</li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]128 <li>iconv: a powerful character encoding conversion library. It's
129 included by default on recent glibc libraries, so it doesn't need to
130 be installed specifically on linux. It seems it's now <a
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]131 href="http://www.opennc.org/onlinepubs/7908799/xsh/iconv.html">part
132 of the official UNIX</a> specification. Here is one <a
Daniel Veillarde9202a02000-10-16 16:58:19 +0000[diff] [blame]133 href="http://clisp.cons.org/~haible/packages-libiconv.html">implementation
134 of the library</a> which source can be found <a
Daniel Veillard7f41b3e2001-02-10 09:35:37 +0000[diff] [blame]135 href="ftp://ftp.ilog.fr/pub/Users/haible/gnu/">here</a>.</li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]136 </ul>
137 </li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]138 <li><em>libxml does not compile with HP-UX's optional ANSI-C compiler</em>
139 <p>this is due to macro limitations. Try to add " -Wp,-H16800 -Ae" to the
140 CFLAGS</p>
141 <p>you can also install and use gcc instead or use a precompiled version
142 of libxml, both available from the <a
143 href="http://hpux.cae.wisc.edu/hppd/auto/summary_all.html">HP-UX Porting
144 and Archive Centre</a></p>
145 </li>
146 <li><em>make check fails on some platforms</em>
147 <p>Sometime the regression tests results don't completely match the value
148 produced by the parser, and the makefile uses diff to print the delta. On
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]149 some platforms the diff return breaks the compilation process, if the
150 diff is small this is probably not a serious problem</p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]151 </li>
Daniel Veillard6761eee2001-06-11 10:29:38 +0000[diff] [blame]152 <li><em>I use the CVS version and there is no configure script</em>
153 <p>The configure (and other Makefiles) are generated. Use the autogen.sh
154 script to regenerate the configure and Makefiles, like:</p>
155 <p><code>./autogen.sh --prefix=/usr --disable-shared</code></p>
156 </li>
Daniel Veillard7b06bcb2001-06-22 16:03:51 +0000[diff] [blame]157 <li><em>I have troubles when running make tests with gcc-3.0</em>
158 <p>It seems the initial release of gcc-3.0 has a problem with the
159 optimizer which miscompiles the URI module. Please use another
160 compiler</p>
161 </li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]162</ol>
163
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]164<h2><a name="Developer">Developer</a> corner</h2>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]165<ol>
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]166 <li><em>xmlDocDump() generates output on one line</em>
167 <p>libxml will not <strong>invent</strong> spaces in the content of a
168 document since <strong>all spaces in the content of a document are
169 significant</strong>. If you build a tree from the API and want
170 indentation:</p>
171 <ol>
172 <li>the correct way is to generate those yourself too</li>
173 <li>the dangerous way is to ask libxml to add those blanks to your
174 content <strong>modifying the content of your document in the
175 process</strong>. The result may not be what you expect. There is
176 <strong>NO</strong> way to guarantee that such a modification won't
177 impact other part of the content of your document. See <a
178 href="http://xmlsoft.org/html/libxml-parser.html#XMLKEEPBLANKSDEFAULT">xmlKeepBlanksDefault
179 ()</a> and <a
180 href="http://xmlsoft.org/html/libxml-tree.html#XMLSAVEFORMATFILE">xmlSaveFormatFile
181 ()</a></li>
182 </ol>
183 </li>
Daniel Veillard7f41b3e2001-02-10 09:35:37 +0000[diff] [blame]184 <li>Extra nodes in the document:
Daniel Veillard62bccd52001-02-10 09:40:10 +0000[diff] [blame]185 <p><em>For a XML file as below:</em></p>
186 <pre>&lt;?xml version="1.0"?&gt;
Daniel Veillarda6663592001-02-10 09:41:12 +0000[diff] [blame]187&lt;PLAN xmlns="http://www.argus.ca/autotest/1.0/"&gt;
Daniel Veillard62bccd52001-02-10 09:40:10 +0000[diff] [blame]188&lt;NODE CommFlag="0"/&gt;
189&lt;NODE CommFlag="1"/&gt;
190&lt;/PLAN&gt;</pre>
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]191 <p><em>after parsing it with the function
192 pxmlDoc=xmlParseFile(...);</em></p>
Daniel Veillard7f41b3e2001-02-10 09:35:37 +0000[diff] [blame]193 <p><em>I want to the get the content of the first node (node with the
194 CommFlag="0")</em></p>
195 <p><em>so I did it as following;</em></p>
Daniel Veillard62bccd52001-02-10 09:40:10 +0000[diff] [blame]196 <pre>xmlNodePtr pode;
197pnode=pxmlDoc-&gt;children-&gt;children;</pre>
Daniel Veillard7f41b3e2001-02-10 09:35:37 +0000[diff] [blame]198 <p><em>but it does not work. If I change it to</em></p>
Daniel Veillard62bccd52001-02-10 09:40:10 +0000[diff] [blame]199 <pre>pnode=pxmlDoc-&gt;children-&gt;children-&gt;next;</pre>
Daniel Veillard7f41b3e2001-02-10 09:35:37 +0000[diff] [blame]200 <p><em>then it works. Can someone explain it to me.</em></p>
201 <p></p>
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]202 <p>In XML all characters in the content of the document are significant
Daniel Veillard7f41b3e2001-02-10 09:35:37 +0000[diff] [blame]203 <strong>including blanks and formatting line breaks</strong>.</p>
204 <p>The extra nodes you are wondering about are just that, text nodes with
205 the formatting spaces wich are part of the document but that people tend
206 to forget. There is a function <a
207 href="http://xmlsoft.org/html/libxml-parser.html">xmlKeepBlanksDefault
208 ()</a> to remove those at parse time, but that's an heuristic, and its
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]209 use should be limited to case where you are sure there is no
210 mixed-content in the document.</p>
Daniel Veillard7f41b3e2001-02-10 09:35:37 +0000[diff] [blame]211 </li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]212 <li><em>I get compilation errors of existing code like when accessing
213 <strong>root</strong> or <strong>childs fields</strong> of nodes</em>
Daniel Veillard3f3b4f32001-03-13 15:12:39 +0000[diff] [blame]214 <p>You are compiling code developed for libxml version 1 and using a
215 libxml2 development environment. Either switch back to libxml v1 devel or
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]216 even better fix the code to compile with libxml2 (or both) by <a
217 href="upgrade.html">following the instructions</a>.</p>
218 </li>
219 <li><em>I get compilation errors about non existing
220 <strong>xmlRootNode</strong> or <strong>xmlChildrenNode</strong>
221 fields</em>
222 <p>The source code you are using has been <a
223 href="upgrade.html">upgraded</a> to be able to compile with both libxml
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]224 and libxml2, but you need to install a more recent version:
225 libxml(-devel) &gt;= 1.8.8 or libxml2(-devel) &gt;= 2.1.0</p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]226 </li>
227 <li><em>XPath implementation looks seriously broken</em>
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]228 <p>XPath implementation prior to 2.3.0 was really incomplete, upgrade to
229 a recent version, the implementation and debug of libxslt generated fixes
Daniel Veillard480363b2001-03-16 22:04:15 +0000[diff] [blame]230 for most obvious problems.</p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]231 </li>
232 <li><em>The example provided in the web page does not compile</em>
233 <p>It's hard to maintain the documentation in sync with the code
Daniel Veillarde9202a02000-10-16 16:58:19 +0000[diff] [blame]234 &lt;grin/&gt; ...</p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]235 <p>Check the previous points 1/ and 2/ raised before, and send
236 patches.</p>
237 </li>
238 <li><em>Where can I get more examples and informations than in the web
239 page</em>
240 <p>Ideally a libxml book would be nice. I have no such plan ... But you
241 can:</p>
242 <ul>
Daniel Veillarde9202a02000-10-16 16:58:19 +0000[diff] [blame]243 <li>check more deeply the <a href="html/libxml-lib.html">existing
244 generated doc</a></li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]245 <li>looks for examples of use for libxml function using the Gnome code
246 for example the following will query the full Gnome CVs base for the
247 use of the <strong>xmlAddChild()</strong> function:
248 <p><a
249 href="http://cvs.gnome.org/lxr/search?string=xmlAddChild">http://cvs.gnome.org/lxr/search?string=xmlAddChild</a></p>
250 <p>This may be slow, a large hardware donation to the gnome project
251 could cure this :-)</p>
252 </li>
253 <li><a
Daniel Veillarde9202a02000-10-16 16:58:19 +0000[diff] [blame]254 href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&amp;dir=gnome-xml">Browse
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]255 the libxml source</a>
256 , I try to write code as clean and documented as possible, so
257 looking at it may be helpful</li>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]258 </ul>
259 </li>
260 <li>What about C++ ?
Daniel Veillard008186f2001-09-13 14:24:44 +0000[diff] [blame^]261 <p>libxml is written in pure C in order to allow easy reuse on a number
262 of platforms, including embedded systems. I don't intend to convert to
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]263 C++.</p>
264 <p>There is however a C++ wrapper provided by Ari Johnson
Daniel Veillarde9202a02000-10-16 16:58:19 +0000[diff] [blame]265 &lt;ari@btigate.com&gt; which may fullfill your needs:</p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]266 <p>Website: <a
267 href="http://lusis.org/~ari/xml++/">http://lusis.org/~ari/xml++/</a></p>
268 <p>Download: <a
269 href="http://lusis.org/~ari/xml++/libxml++.tar.gz">http://lusis.org/~ari/xml++/libxml++.tar.gz</a></p>
270 </li>
271 <li>How to validate a document a posteriori ?
272 <p>It is possible to validate documents which had not been validated at
273 initial parsing time or documents who have been built from scratch using
274 the API. Use the <a
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]275 href="http://xmlsoft.org/html/libxml-valid.html#XMLVALIDATEDTD">xmlValidateDtd()</a>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]276 function. It is also possible to simply add a Dtd to an existing
277 document:</p>
278 <pre>xmlDocPtr doc; /* your existing document */
279 xmlDtdPtr dtd = xmlParseDTD(NULL, filename_of_dtd); /* parse the DTD */
Daniel Veillarde9202a02000-10-16 16:58:19 +0000[diff] [blame]280 dtd-&gt;name = xmlStrDup((xmlChar*)"root_name"); /* use the given root */
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]281
Daniel Veillarde9202a02000-10-16 16:58:19 +0000[diff] [blame]282 doc-&gt;intSubset = dtd;
283 if (doc-&gt;children == NULL) xmlAddChild((xmlNodePtr)doc, (xmlNodePtr)dtd);
284 else xmlAddPrevSibling(doc-&gt;children, (xmlNodePtr)dtd);
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]285 </pre>
286 </li>
287 <li>etc ...</li>
288</ol>
289
Daniel Veillardc5d64342001-06-24 12:13:24 +0000[diff] [blame]290<p><a href="mailto:daniel@veillard.com">Daniel Veillard</a></p>
Daniel Veillardaf743792000-07-01 11:49:28 +0000[diff] [blame]291
292<p>$Id$</p>
293</body>
294</html>