The Big File or BNP system is a logical virtual filesystem that allows packagers to place several files into one physical file. Access the files packaged within this .bnp file is completely transparent to developers of NeL-based applications as long as the bnp file is in one of the search paths. The CPath system completely abstracts finding and accessing these files from the developer. Before you can access BNP packages you will first need to know how to create them. Next you'll need to know some slightly advanced usage in accessing the BNP packages.
In order to create .bnp files you will first need a copy of the bnp_make executable. If you do not have this you can compile it as part of the optional NeL tools. This tool is very simple has has three main actions: pack (/p), unpack (/u) and list (/l). It also accepts two optional parameters -if and -ifnot that take a wildcard string and filter the files that will be copied into the BNP file. Take the following directory for example:
$ pwd
/home/me
$ ls -l bnptest/
total 100
-rw-r--r-- 1 me me 61745 2008-05-19 12:47 gnu.shape
-rw-r--r-- 1 me me 28998 2008-05-19 12:47 sky.shape
Here we have a directory with two shape files in it that we want to package into a single BNP file. Here's the simple command to accomplish this.
$ bnp_make /p bnptest
Treating directory: /home/me/bnptest
adding /home/me/bnptest/gnu.shape
adding /home/me/bnptest/sky.shape
Whenever you add a search path to CPath it will automatically discover any bnpfiles in that search path. Alternatively if you have specific files that are not in your search path you can manually add them using the addSearchBigFilemethod. You will rarely need to manually add these to your CPath search paths, but the method is provided for flexibility, in the instance that a file is downloaded by a patcher after execution, for example.
Accessing BNP files is no different than using CPath to find any normal file. Rarely will you use CPath::lookup to find a BNP file, however you will use it to find any file contained within a BNP file. If you used the .bnp that we created in the previous section then loading a file from a BNP file 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("gnu.shape", true, true, false);
CIFile shapeIn(filename);
You can see how simple it was to find a file and load it into a CIFile. While you will rarely load a shape using CIFile and shape loading will be covered in a later section this does show how easy it is to lookup a file from within a bnp and load it. 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("gnu.shape", true, true, false);
if (filename.find("bnptest.bnp@gnu.shape") != std::string::npos)
{
// we found the correct file name.
nlinfo("filepath is: %s", filename);
// this outputs: filepath is: bnptest.bnp@gnu.shape
}