# Upgrading libxml client code from 1.x to 2.x

## Incompatible changes:

Version 2 of libxml is the first version introducing serious backward incompatible changes. The main goals were:

- a general cleanup. A number of mistakes inherited from the very early versions couldn't be changed due to compatibility constraints. Example the "childs" element in the nodes.
- Uniformization of the various nodes, at least for their header and link parts (doc, parent, children, prev, next), the goal is a simpler programming model and simplifying the task of the DOM implementors.
- better conformances to the XML specification, for example version 1.x had an heuristic to try to detect ignorable white spaces. As a result the SAX event generated were ignorableWhitespace() while the spec requires character() in that case. This also mean that a number of DOM node containing blank text may populate the DOM tree which were not present before.

## How to fix libxml-1.x code:

So client code of libxml designed to run with version 1.x may have to be changed to compile against version 2.x of libxml. Here is a list of changes that I have collected, they may not be sufficient, so in case you find other change which are required, drop me a mail:

1. Node childs field has been renamed children so s/childs/children/g should be applied (probablility of having "childs" anywere else is close to 0+
2. The document don't have anymore a root element it has been replaced by children and usually you will get a list of element here. For example a Dtd element for the internal subset and it's declaration may be found in that list, as well as processing instructions or comments found before or after the document root element. Use xmlDocGetRootElement(doc) to get the root element of a document. Alternatively if you are sure to not reference Dtds nor have PIs or comments before or after the root element s/->root/->children/g will probably do it.
3. The white space issue, this one is more complex, unless special case of validating parsing, the line breaks and spaces usually used for indenting and formatting the document content becomes significant. So they are reported by SAX and if your using the DOM tree, corresponding nodes are generated. Too approach can be taken:
   1. lazy one, use the compatibility call xmlKeepBlanksDefault(0) but be aware that you are relying on a special (and possibly broken) set of heuristics of libxml to detect ignorable blanks. Don't complain if it breaks or make your application not 100% clean w.r.t. to it's input.
   2. the Right Way: change you code to accept possibly unsignificant blanks characters, or have your tree populated with weird blank text nodes. You can spot them using the comodity function xmlIsBlankNode(node) returning 1 for such blank nodes.

   Note also that with the new default the output functions don't add any extra indentation when saving a tree in order to be able to round trip (read and save) without inflating the document with extra formatting chars.

4. The include path has changed to $prefix/libxml/ and the includes themselves uses this new prefix in includes instructions... If you are using (as expected) the

       xml-config --cflags

   output to generate you compile commands this will probably work out of the box

## Ensuring both libxml-1.x and libxml-2.x compatibility

Two new version of libxml (1.8.8) and libxml2 (2.1.0) have been released to allow smoth upgrade of existing libxml v1code while retaining compatibility. They offers the following:

1. similar include naming, one should use #include<libxml/...> in both cases.
2. similar identifiers defined via macros for the child and root fields: respectively xmlChildrenNode and xmlRootNode
3. a new macro LIBXML_TEST_VERSION which should be inserted once in the client code

So the roadmap to upgrade your existing libxml applications is the following:

1. install the libxml-1.8.8 (and libxml-devel-1.8.8) packages
2. find all occurences where the xmlDoc root field is used and change it to xmlRootNode
3. similary find all occurences where the xmlNode childs field is used and change it to xmlChildrenNode
4. add a LIBXML_TEST_VERSION macro somewhere in your main() or in the library init entry point
5. Recompile, check compatibility, it should still work
6. install libxml2-2.1.0, remove libxml-devel-1.8.8 and install libxml2-devel-2.1.0 (libxml-1.8.8 can be kept installed for legacy stuff)
7. remove your config.cache, relaunch your configuration mechanism, and recompile, if steps 2 and 3 were done right it should compile as-is
8. Test that your application is still running correctly, if not this may be due to extra empty nodes due to formating spaces being kept in libxml2 contrary to libxml1, in that case insert xmlKeepBlanksDefault(1) in your code before calling the parser (next to LIBXML_TEST_VERSION is a fine place).

Following those steps should work. It worked for some of my own code.

Let me put some emphasis on the fact that there is far more changes from libxml 1.x to 2.x than the ones you may have to patch for. The overall code has been considerably improved and the conformance to the XML specification has been drastically improve. Don't take those changes as an excuse to not upgrade, it may cost a lot on the long term ...

Daniel Veillard

$Id: upgrade.html,v 1.7 2000/06/30 18:39:56 veillard Exp $