BuGLe alpha release
===================

This is an alpha release, and may not due what you want. However, I am
successfully using BuGLe in my work. If you have problems installing,
please refer to the TROUBLESHOOTING file. It has, however, been tested
on GNU/Linux and on FreeBSD.  I would like to support all POSIX
platforms that use X, dynamic loading and something like LD_PRELOAD; if
your platforms meet these requirements but you can't get it to work
then let me know why. Windows may one day be supported, but certainly
not yet.

Here are a few things you can do so far
- capture a log of what a program does (won't capture everything yet)
- check for GL errors after every call
- force a wireframe mode
- capture a video
- run inside a gdb-like debugger, with breakpoints on GL functions and
  (optionally) stopping after every error.

To build, you will need the following:
- Perl 5
- A version of gcc that supports the -fdump-translation-unit flag
  (gcc 3.2 or higher is recommended).
- A C++ compiler (probably g++)
- OpenGL header files, including glext.h. The best OpenGL header files
  are those from the Mesa project (pre-installed on many systems).
  Avoid the header files provided by NVIDIA, as they have numerous
  errors [this may no longer be true, but it is untested].
- To do video capture, you will need libavcodec/libavformat from ffmpeg.

If you are upgrading, you MUST uninstall the previous version first. If
you don't have the built tree around to do `make uninstall', then at
the very least remove all the files from /usr/local/lib/bugle/ (or
wherever you install them). Newer versions install may install fewer
libraries here, and old libraries will confuse bugle.

If you have trouble with your system headers, see the file
TROUBLESHOOTING for instructions on using Mesa headers to compile
BuGLe.

To run usefully, you will need a configuration file
$HOME/.bugle/filters. You can copy the example file doc/examples/filters.
Execute your program something like the following:

$ BUGLE_CHAIN=trace LD_PRELOAD=/usr/local/lib/libbugle.so glxgears

where BUGLE_CHAIN specifies a combination of filters to use. The name
references a section in the configuration file; the example file
documents the configurations it provides. For more details, see the
manual page for bugle.

The debugger is called gldb and is documented in the manual page.

Feedback
========
I am interested in getting feedback about this tool: bugs you've found
(but first read this file and the FAQ to make sure it isn't already
known), suggestions for improvements, whatever. My address is
bmerry@users.sourceforge.net.
