Read Me

                                   prtpacker



                         Portable Resource Tree Packer

                                Joseph Coffland
                        jcofflan@users.sourceforge.net

Introduction

prtpacker (pronounced PIRT-Packer) is a tool for creating C or C++ source code
from external program resources such as images, text, or data. These resources
can be arranged in a tree structure much like a typical file system. After
compiling and linking the resulting source code you can access the resource
tree from within your software through a simple API.

Be aware that all resources stay in memory and cannot be easily deallocated.
Generally with small files (< 100K bytes) this is not an issue. So don't go
trying to sticking your latest Divx download in as a resource. That is unless
you want your computer to run like Windows 98.

prtpacker may be ideal for embedded systems where implementing a complete file
system is undesirable. In this case the firmware footprint may actually
decrease.

 Pros:

* Program resources can't get lost.
* Always have the right version with the software.
* Increased portability.
* Programming convenience.
* Quick access.
* It is a cheap embedded file system.


 Cons:

* Larger program memory footprint. (for non-embedded systems)
* Must recompile to change resources.



Tested Platforms

* Linux x86 (gcc2.95 and 3.0)
* Solaris (gcc3.0)
* Windows 2000 (MSVC7 and gcc3.0)



Install

Unpack the source distribution. Then in the resulting directory:

  	./configure
  	make
  	make install





Usage


 * prtpacker


Create the resource source code.

  	prtpacker -r myResources resources/* other_resource >resources.cpp

Add a reference to your resources in your code.

  	#include

h>
	extern const prtp_dir *myResources;
Link the result to your program. libprtpacker.a has some useful functions for
accessing prtpacker resources.

  	g++ -o myapp myapp.cpp resources.cpp -lprtpacker

To access a resource use getResource from prtpacker.h. Here is an example
straight out of prtpacker itself.

  	extern struct prtp_dir *prtpackerResources;

  	const prtp_file *license = getResource(prtpackerResources, "short_license");
    	if (!license) {
      		fprintf(stderr, "ERROR: Could not locate resource 'short_license'\n");
      		return;
    	}
    	printf((const char *)license->data);

Also take a look at these other sources of information:

* The example that comes with the source distribution.
* prtpacker source code which uses itself for the license resources.
* The prtpacker help (i.e. prtpacker -h).
* The prtpacker man page.


 * toolstub


toolstub.cpp is code that can be linked against your compiled resource tree to
get information or extract files.
Be sure to define the ROOT symbol so toolstub can find your resources.
Example:


        g++ -DROOT=myResources -o mytool myresources.o toolstub.o
  prtpackertools.o

        ./mytool -l   # List all the resources in myresources.
        ./mytool -g myresource >myresource  # Dump myresource to a file.



License

GNU_Public_License
See the file COPYING or the prtpacker -l and -L options.



Links

* Home Page                  http://prtpacker.sourceforge.net
* Download                   http://sourceforge.net/project/showfiles.php?group_id=80125
* Bugs                       http://sourceforge.net/tracker/?group_id=80125&atid=558806
* CVS                        http://sourceforge.net/cvs/?group_id=80125
* Source_Forge_Project_Page  http://sourceforge.net/projects/prtpacker/