Firstly, welcome to RTTB!
I have organised this manual into five stages, an overview, using the
tools to create an RTTB, using the library, linking with the library
and
such, function listings for using librttb and a hackers guide for
hacking
new code and using the core interface.
Contents
1.0 Overview
1.1 Tools supplied
1.2 Obtaining binary distributions
1.3 License and what it means in brief
2.0 Explaination of makerttb usage
2.1 Explaination of vrttb usage
2.2 RTTB tools/library sync problems
2.3 Prerelease (0) revision number and consequences.
3.0 Where is the library and what does it contain
3.1 Compiling the sources for UNIX
3.2 Compiling the sources (Borland C++ on Win32)
3.3 Compiling the sources (other platforms)
3.4 Adding sections to Makefiles to link with
the library
3.5 Globally converting code with macros
(quick transition)
3.6 The example programs
4.0 Types used by the program
4.1 Error numbers
4.2 User macros
4.3 Custom configuration (need source not bin
distributions)
4.4 Complete function listings
5.0 A hackers guide, introduction
5.1 The debug code
5.2 The three tier trust code model, why I chose it.
5.3 The view of user code (not trusted, level 2)
5.4 The view of outer code (sheltering, level
1)
5.5 The view of the core code (level 0)
5.6 How to write an effective sheltering module
5.7 How to write core code patches.
5.8 Core-only types
5.9 Core Initializers
5.10 Core function listings for use of
sheltering
code
5.11 Core-only function listings.
5.12 RTTB file format
The functions that had to be controlled by the library, were the normal stream handling functions, fseek( ), fread( ), fgetc( ) etc. RTTB is a read only library, read/write access would have meant a far more complex file format and slower access. I used the stream functions and not open( ), close( ) style functions internally because these were the only ones defined by ANSI C. So that I didn't infringe on the C library's namespace, all functions were prefixed with 'rttb_', rttb_fopen( ), rttb_fclose( ) etc.
1.1 Tools supplied
In the tools subdirectory of the distribution there a number of tools
and they will continue to be added to. At the time I wrote this,
there were just two, makerttb and vrttb. Both have useful
purposes.
makerttb - This is the main tool which will probally be used everytime your resources are changed to remake the RTTB file. It is not complex, it offers no extraction or partial adding, listing, searching. All this does is initially create a new RTTB file, overwriting an old one. For more information see the section on using makerttb.
vrttb - This tool is unlikely to be used extensively, certainly not at every rebuild. Before releasing software to the public which has prebuilt RTTB files, always run vrttb on the RTTB file to ensure it is free from errors and/or internal file corruption. For more information see the section on using vrttb.
1.2 Obtaining binary distributions
I recommend you use the source-based distribution. I supply
binaries of the tools and statically built libraries for major
platforms and architectures but it is not as flexible as the
source-based distribution. Generally, binary distributions are
dealt with by package managers or ports collections under the various
operating systems. It is better than operating systems maintain
their own binary distributions of this library and associated tools.
1.3 License and what it means in brief
The BSD-license means, essentially that you can use this source for
commercial or free use. Provided copyright notices remain
intact This means there should be no reason you can't use the
library in your own project, as long as you accept the no-liability
disclaimer and agree to display the copyright notice.
2.0 Explaination of makerttb usage
makerttb is a tool to create a new RTTB file, it does nothing more,
even if offered chocolate. The usage is:
tools/makerttb [rttbfile] file1 file2 file3 @responsefile
|
|
|
|
|
|
|
|
|
|----------------- Text file listing more files which won't fit on one
line
|
|
|
|------------------------------------
File(s) to add to the RTTB file
|
|
|--------------------------------------------- Filename of the RTTB
file
to create
|
|---------------------------------------------------------
Program name
|-----------------------------------------------------------------
Path
Rules: @ may not appear as the first parameter. @ is not part
of the response file's name, it indicate it's a reponsefile and not an
ordinary file to add. We use response files because some
operating
systems don't allow unlimited command line lengths. The
responsefile
could list hundreds, possibly thousands of filenames, line by
line.
Multiple response files may be used on the command line.
The RTTB could take a long time to generate, in some versions files
are checksummed before they are added rather than during, on these
versions
the makerttb utility could take twice as long. Please report any
bugs with this tool to the maintainer, his address will be displayed by
makerttb when run or check the source code makerttb.c near the top.
2.1 Explaination of vrttb usage
vrttb is a tool to verify an RTTB file, use like this:
tools/vrttb [rttbfile]
|
|
|
|
|
|--------------- Name of the RTTB file to verify
|
|---------------------
Program name
|--------------------------- Path
Any errors will be displayed, status messages are displayed as the program runs. In a very large RTTB file the verification of checksums will take a long time.
2.2 RTTB tools/library sync problems
When I designed the RTTB file format, I knew that the file format may
become obsolete or improved. Therefore I added a byte (range
0-255)
with a revision number. If an RTTB is created with one version of
makerttb and verified with an older or newer vrttb or read with an
older
or newer librttb as a program, it will not be recognised.
Luckily,
there are two error numbers defined for this
circumstance.
Note: I won't be making the library or tools backwardly compatible with
older versions of RTTB files. RTTB files should be built with the
tool which matches the RTTB library version. Tools displays the
revision
number thay are designed for and the library can be requested to return
the information with this function.
2.3 Prerelease (0) revision number and
consequences.
The revision number zero is a special case, it is not a normal order
0,1,2,3,4,5 etc., 1 is the first release. When 0 is released, it
is an unofficial, debugging, development version and RTTB files of
revision
zero could contain any old rubbish made by in development, unstable
libraries,
their contents should not be trusted.
3.0 Where is the library and what does it
contain
Under the lib subdirectory there may be a couple of files, a file
called
librttb.a (UNIX) or rttb.lib (Win32 or DOS) and a header, rttb.h for
user
code to include. In source distributions there are many files
here,
if you don't intend to hack the source, ignore most of these but the
files
mentioned. If the library file does not exist, the sources have
not
been compiled yet. The library module contains many object code
modules.
rttb_core.o (or obj) is the most important one. Rather than
supply
the entire library as a C file and have people compile and link it in,
the library is like a small archive of object code modules.
Before
using the library it must be started,
then
functions
may be used and then it should be
shutdown
cleanly. The module rttb_debug.o (or obj) is optional and can be
left out of the link if building manually. It contains debugging
code only.
3.1 Compiling the sources for UNIX
Version 0.0.3 and later now have a configure script generated
automatically from configure.ac by GNU autoconf.
Type ./configure
then make
then make check
(optional)
and finally, make install
(as root).
For further details on the configure options, see section
4.3
3.2 Compiling the sources (Borland C++
on
Win32)
You will need the dlscripts
package (0.2.0 or later) and you will need Cygwin or Microsoft
Services For UNIX. Once you have either of these up and
running, open the Bourne Shell and type:
./configure --enable-win32
./borlandify.sh
Then back in a Win32 console, type:
make -f Makefile.bor
Note: make -f Makefile.bor clean
cleans up the files which have been created.
3.3 Compiling the sources (other
platforms)
For any unsupported platforms please, either write a Makefile and post
it back to the project or manually build the sources in a development
environment.
For the lib subdirectory add all C files which appear in the other
makefiles.
For
the tools, link in the library's binary, which must be built first.
Read
the other makefiles to guide you and if you can, autogenerate a
Makefile
in the development environment, test it, add a clean section and post
it
back to the project.
3.4 Adding sections to Makefiles to
link
with the library
Let's take my normal example as usual but far simplified, say, three
sound effects, shout.au, monster.au and water.au. In the game's
makefile,
a section like this should appear to automatically rebuild sounds.rttb
everytime the user types 'make sounds':
SOUNDEFFECTS=shout.au \
monster.au \
water.au
sounds : sounds.rttb # Equivillant
sounds.rttb : $(SOUNDEFFECTS)
makerttb sounds.rttb $(SOUNDEFFECTS)
clean:
rm -f sounds.rttb
OK, that was simple enough, however, if there really are hundreds of files a way will have to be found to auto generate the dependencies or just force a makerttb when make sounds was executed or only if the file sounds.rttb was deleted and make was typed. A Makefile would look like this in the case on a no dependency option:
sounds : sounds.rttb
sounds.rttb:
ls *.au > sounds.list # dir *.au /b
> sounds.list in Win32
makerttb sounds.rttb @sounds.list
rm -f
sounds.list
# erase sounds.list in Win32
I recommend you make yourself a dependency tool to determine
automatically
if the sounds.rttb file will have to be modified. Linux uses a
make
dep option to dynamically determine dependencies. You might be
able to make use of Daybo Logic's dependency generator.
3.5 Globally converting code with
macros
(quick transition)
In order to convert existing code to use RTTB rather than fread( )
and fwrite( ) calls directly use the header file userttb.h after
including
rttb.h:
#include "rttb.h"
#define RTTB_CONTAINERNAME "tarball.rttb"
#include "userttb.h"
userttb.h has macros for existing functions, fopen( ) and other functions will be mapped to rttb_fread( ). Note that this is different than the define RTTB_USING_FUNCTIONS, which simply shortens the names rttb_fread to fread etc. Do not do this:
#define RTTB_USING_FUNCTIONS
#include "rttb.h"
#define RTTB_CONTAINERNAME "tarball.rttb"
#include "userttb.h"
Luckily I have added some code in userttb.h to prevent this happening. As the names are shared these different type of replacing fread( ) calls are mutually exclusive.
Note: Normal calls to fopen( ) do not ask for a container name (an
RTTB
file). In order to support exisitng code, I have made it
mandatory
to define the container name so that calls to fopen( ) don't have to be
changed are are fully compatible with C's
fopen( ). Define RTTB_CONTAINERNAME to be the RTTB's filename
before including userttb.h.
3.6 The example programs
The example programs supplied are to help one understand how to use
the library. It's possible uses. Under the subdirectory
examples
these programs are available. Usually they are not useful tools,
otherwise I'd put them in the tools subdirectory.
odd : This example reads in every other character from the README document and writes out a nonsense file called README.2 which, as it contains every other character, should be unreadable. README should be in a file called readme.rttb in the directory the example is run from. readme.rttb may contain whatever other rubbish you want, as long as README is in there somewhere.
BabeBrowser : This program is for Win32 only, it uses the Borland C++Builder VCL framework, so unless you have this development environment you cannot build it. Never fear, I have precompiled binaries on the site. BabeBrowser has a file called babes.rttb which contains multiple, browsable JPEGs of women. babes.rttb is a large file and is therefore available from an FTP server, not supplied in the distribution package. If you want to try the BabeBrowser, fetch babes.rttb from the RTTB website downloads page seperately.
4.0 Types used by the program
4.1 Error numbers
4.2 User macros
4.3 Custom configuration (need source not
bin distributions)
4.4 Complete function listings
5.0 A hackers guide, introduction
5.1 The debug code
5.2 The three tier trust code model, why I chose
it.
5.3 The view of user code (not trusted, level
2)
5.4 The view of outer code (sheltering,
level 1)
5.5 The view of the core code (level 0)
5.6 How to write an effective sheltering module
5.7 How to write core code patches.
5.8 Core-only types
5.9 Core Initializers
5.10 Core function listings for use of
sheltering code
5.11 Core-only function listings.
5.12 RTTB file format