elfrc - a resource compiler for ELF System
==========================================

1.) About
---------
elfrc is a program which can turn arbitrary files into ELF object
files which can then be linked into your program directly and
accessed via simple, user-defined symbol names.

For instance, it's possible to embed even huge (16MB+) files
directly into the executable and then access the data in
constant time without making the compiler or linker eat
loads of memory.

For licensing information, please consult the accompanying LICENSE
file.

2.) Compilation
---------------
The only non-trivial dependency elfrc has are some ELF header files,
other than that it should build out-of-the box on any system which
uses ELF files. Any C compiler and the standard header files will
do.

Just run 'make' (GNU make works, so does FreeBSD make) to build
the program.

3.) Usage
---------
Here's the usage line as given when invocing elfrc without any arguments:

    elfrc [-o <filename>] [-h <filename>] [-v] [resfile]

Here's what the arguments do:

    -o <filename>         Store resulting ELF object in <filename>. If
                          not given, no ELF object will be generated.
    -h <filename>         Store C headerfile which can be used to access
                          the resource data in <filename>. If not given,
                          no header file will be generated.
    -v                    Be a little verbose about what's going on.

In any case, the most important argument is <resfile> - the path
to a resource file which can be parsed by elfrc. If no resource
file is given, or if "-" is given, the resources will be read
from the standard input.

A resource file is just a plain text file, each line in the file
describing a resource to be compiled into the ELF output. Each line
is expected to three fields, separated by tab characters: the
type of the resource (can be either 'binary' or 'text'), the symbol
name (this should be a valid C identifier) and the path to the file
to be compiled in.

Here's a sample resource file which makes the data of 'bigpicture.jpg'
accessible via the 'imgdata' symbol and 'largetext' will contain the
contents of '/home/user/book.txt':

    binary	imgdata	bigpicture.jpg
    text	largetext	/home/user/book.txt

This little resource file could be saved as e.g. 'resfile.rc' and used
with an elfrc invocation like

    elfrc -o resources.o resfile.rc

to compile bigpicture.jpg and /home/user/book.txt into resources.o - which
could then be linked into your program.

If you intend to link the object file into a C or C++ program, you usually
want to generate a corresponding header file as well, which you can then
include into your sources to access the data easily:

    elfrc -o resources.o -h resources.h resfile.rc

Here's how the resulting header file looks like:

    #ifndef H_5863573680128751
    #define H_5863573680128751

    #ifdef __cplusplus
    extern "C" {
    #endif

    /* Automatically generated by elfrc 0.7. Do not modify by hand. */

    /* bigpicture.jpg */
    extern const char imgdata[405585];

    /* /home/user/book.txt */
    extern const char largetext[13931];

    #ifdef __cplusplus
    } /* extern "C" */
    #endif

    #endif /* H_5863573680128751 */

4.) Caveats
-----------
Depending on the size and the number of resource files you feed to
elfrc, very huge object files might be created. Unfortunately, the
GNU ld linker maps each given object file completely into memory
(using the mmap system call) when linking object files. In order
to work around GNU ld thrashing your memory, it might be a good
idea to create multiple object files with elfrc (for instance, one
per resource) instead of a single monolithic one.

5.) Contact
-----------
In case you find bugs or have feature requests, please don't hesitate
to contact me (Frerich Raabe) at raabe@kde.org. Thanks!