xml_pack - ryzom/ryzomcore GitHub Wiki

The XML Pack mechanism is useful for packaging several different XML files in a single packed XML file. They function within NeL similar to Big Files and are abstracted by the CPath system. In this section we'll cover how to create XML packs, how to load them and how to access and use them.

In order to create xml_pack files you will first need a copy of the xml_packer executable. If you do not have this you can compile it as part of the optional NeL tools. This tool is very simple and only has three (3) command line options: -p (pack), -r (recurse) and -u (unpack). Assume you have the following contents in your current directory:

$ pwd
/home/me/xmltest
$ ls -l
total 8
-rw-r--r-- 1 me me 25 2008-05-15 15:26 bar.xml
-rw-r--r-- 1 me me 26 2008-05-15 15:26 foo.xml

To convert these two files into a single XML Pack you would simply run this from the above directory:

$ xml_pack -p

This creates a new xml_pack file called xmltest.xml_pack in your current directory using every file in the directory. The xml_packer tool will add every file in your directory except other .xml_pack files. If you have multiple sub-directories you can also have the xml_packer tool add the files in those directories as well by adding in the -r command line option. Finally you can extract any xml_pack files you have back into their directories using the -u or unpack option.

It is important to note that xml_packer is intended for XML files but will pack everything in it's path. The only exception is the following extensions: xml_pack, xml_pack_index, log, and bin. It also ignores the CVS directories. Not being careful about what you pack could create harmful bugs in the future.

Whenever you add a search path to CPath it will automatically discover any xml_pack files in that search path. Alternatively if you have specific files that are not in your search path you can manually add them using the addSearchXmlpackFile method. Useful scenarios of this are if you are transmitting XML Packs of containing dynamic or updated data you may want or need to use the method to one-off add the file.

Accessing XML Packs is no different than using CPath to find any normal file. Rarely will you use CPath::lookup to find an XML Pack, however you will use it to find an XML file contained within an XML Pack. If you used the XML Pack that we created in the previous section then loading an XML file from an XML Pack is as simple as the following example:

// The fourth (4th) argument is lookupInLocalDirectory, it is important that this is false.
std::string filename = CPath::lookup("bar.xml", true, true, false);
CIFile barXml(filename);

You can see how simple it was to find a file and load it into a CIFile. There is the possibility that you have two files with the same name, although this should be avoided at all costs. If you need to troubleshoot one quick way to verify which file you have received is to check the path of the file returned by the CPath::lookup call:

std::string filename = CPath::lookup("bar.xml", true, true, false);
if (filename.find("xmltest.xml_pack@@bar.xml") != std::string::npos)
{
	// we found the correct file name.
	nlinfo("filepath is: %s", filename);
	// this outputs: filepath is: xmltest.xml_pack@@bar.xml
}

Source