	TOOLS subdirectory
	------------------

`grab-statics'
--------------

If you wish to use unchecked source files and libraries, you can still check
variables declared in those files using the `grab-statics' script. This looks
through the unchecked files and extracts the variables into another file
in a form that the bounds checking library can read at run time.

To use, simply give `grab-statics' a list of object files and library
archives, and it will make an object (.o) file that you can link with
your program.

Examples:

	% grab-statics /lib/libc.a

	- Create a list of statics in `statics-libc.a.o'

	% grab-statics /usr/X11R6/lib/libX11.a unchecked.o

	- Create two lists in `statics-libX11.a.o' and `statics-unchecked.o.o'

Assuming your program uses libc, libX11 and unchecked.o, you could link your
program with the following line at run-time:

	% gcc -fbounds-checking check1.o check2.o unchecked.o \
		statics-libX11.a.o statics-unchecked.o.o statics-libc.a.o \
		-L/usr/X11R6/lib -lX11 -o prog

Run the program with unchecked warnings turned on, eg.

sh	% GCC_BOUNDS_OPTS='-warn-unchecked-statics' prog
csh	% setenv GCC_BOUNDS_OPTS '-warn-unchecked-statics'; prog

Installing `grab-statics'
-------------------------

`grab-statics' is a shell script that uses the program `find-objects.c' to
do the hard work. This in turn uses Gnu's BFD library to read object files
and library archives. BFD is not supplied with these patches, you will need
to download it separately. It is usually distributed with GDB, so one place
you could get it is:

	ftp://sunsite.doc.ic.ac.uk/gnu/gdb-4.14.tar.gz

Some systems, such as Linux, may come with it preinstalled. Look for
`libbfd*' in /usr/lib.

To make the program, do:

	% cd bounds/tools
	% make grab-statics

I usually run the program in-place, so there is no `make install' as such.
Look at the beginning of the `grab-statics' script if you want to install
it somewhere intelligent. There are some directories hardwired there that
you may need to change. If anyone has ideas about where this ought to be
installed, mail me.

Bugs & limitations with `grab-statics'
--------------------------------------

You have to link your binaries statically if you want to use `grab-statics'.
If someone can approach me with a coherent explanation of how DLL jumptables
and indirections work, I can probably make it work with dynamic linking too.

You can, in theory, do:
	grab-statics /lib/libc.so.5
but in practice this doesn't seem to work (on Linux). I don't know enough about
how DLLs work so we can do this. Use static linking for now.

It doesn't deal with multiple symbols in different libraries with the same
name very intelligently. So suppose you have `ctime' in your C library, and
you've redefined it in your own code. Then you will get `ctime' marked as
an unchecked object with a pointer to your own `ctime', but with the size
of the `ctime' in the C lib. To get round this at the moment, you need to
hack `grab-statics.in' to include `ctime' in the list of excluded symbols.

Only tested under Linux/ELF at the moment. Your mileage may (will) vary.

No `make install' rule yet.

You need Gnu BFD.

`pack-up' and `pack-up-bin'
---------------------------

These are tools that I use to make the final source & binary distributions.
You don't need to touch these, unless you want to be really kind & send
me a binary that works on your machine.
