This README is meant to address basic usage of Alleyoop until I get
around to writing some real documentation.


Basic Usage:
------------

To run Alleyoop, execute the following command at a shell prompt:

	alleyoop

This will start the main user interface. At this point you will likely
wish to click on the "Run" toolbar button (or use the shortcut keys:
Control+R) which will prompt you to enter the name of a program to
debug and any command-line arguments you wish to pass. Beware that
environment variables in the command-line entered in the prompt will
NOT be expanded.

An easier way to do this (in my opinion, anyway) is to specify the
program on the command-line:

	alleyoop ./a.out -v --arg1=foo aout.in

The example above will initialise Alleyoop to run the command:

	./a.out -v --arg1=foo aout.in

when you click on the Run toolbar button.


Command-line Arguments and Environment Variables:
-------------------------------------------------

Because the debugging symbols in the program (and/or shared libraries
that the program depends on) may not contain the full path of the
source code for said object, you might need to use one of the
following command-line arguments:


-I, --include

These arguments allow you to specify a single source path for Alleyoop
to scan when you request it to load a source preview or launch an
editor. You may use these as many times as you like.


-R, --recursive

These arguments, like -I or --include, allow you to specify a source
path to Alleyoop. The difference is that -R and --recursive will also
add all subdirectories of the path specified to Alleyoop's internal
list of source paths.


ALLEYOOP_INCLUDE_PATH

Also for your convenience, there exists an environment variable,
ALLEYOOP_INCLUDE_PATH, that Alleyoop will also use for this
purpose. Like the PATH and LD_LIBRARY_PATH environment variables,
directory names are delimited using the colon (:) character.

Note: paths passed to Alleyoop via the command-line arguments take
precedence over any specified in the environment variable under the
assumption that the user will have likely set ALLEYOOP_INCLUDE_PATH
for all the core libraries that the the programs he/she is interested
in debugging while using the command-line arguments for source paths
limited to the program itself.


Other command-line arguments for Alleyoop include:


--tool

This command-line argument allows you to specify which Valgrind tool
you want to use by default for this particular "Alleyoop Debug
Session". An example usage might be:

	alleyoop --tool=addrcheck



-h, --help

Gee, I wonder ;-)


-v, --version

Prints the version and then exits.


Using Alleyoop:
---------------

Okay, now that you've been introduced to starting Alleyoop and its
various command-line arguments, lets take a look at how to actually
use Alleyoop.

The first thing you are likely to notice is a big white rectangular
area right below the toolbar/searchbar. This is the most important
user interface element because this is where the errors will be
reported.

Once you hit that Run button in the toolbar, messages will start to
appear. You should immediately notice that each line o text will have
a side-ways triangle next to it. When you click on one of these
triangles, the error message will expand to present you with more
information. Generally, this information will consist of at least 1
call-chain[1]. When multiple call-chains appear, they will be
separated by a singleton line giving further information about the
error. Usually, call chains after the first will be used to provide
you with clues as to where memory involved in the error was allocated
or freed.

Each line of a call-chain will normally have a side-ways triangle next
to it as well. Expanding a call-chain tree node will, presuming
Alleyoop can find the source file, load a preview of the source code
involved in the error (you can configure the numbr of lines of context
you wish to see in the preview, by default the number of context lines
are 2 lines above and below the line with the error).

There are several operations that you can do with a call-chain node:

1) Double-clicking a call-chain node with the left mouse button will
launch your preferred editor on the source file containing the error
(using the command-line you configured in the Preferences dialog).

2) Right-clicking a call-chain node will popup a context menu allowing
you to:

  a) Cut/Copy: Selecting either of these items will copy the current
     error condition into your clipboard buffer in the format used by
     Valgrind.

  b) Suppress[2]: This item will open a suppression editor dialog
     pre-filled with the currently selected call-chain
     information. The suppression editor will also default the
     Suppression-Type and System-call values if it can.

  c) Edit in ...: These items all launch the editor specified in the
     menu name on the source file containing the error (similar to
     double-clicking a call-chain node as explained above).

     Note: The GNU/Emacs item is special - it first tries to use
     `emacsclient -n +${lineno} "${filename}"`. Failing that, it
     falls back to launching a new emacs editor.


Using the Search Bar:
---------------------

Like suppressions, the Search Bar (located just below the toolbar) can
be a valuable tool in limiting the errors you see to those that you
care about seeing.

Unlike suppressions, however, they:

1) do not act like as a blacklist (instead, they act more as a
whitelist).

2) are not permanantly applied - clearing the search will restore the
full error log.


You are currently able to search using the following criteria:

Error contains: This option can be used to search for substrings in
the error summary (toplevel node for each error).

Function contains: Search for errors with a particular function in the
call-chain.

Object contains: Search for errors with a particular shared library
(or other object) in a call-chain.

Source filename contains: Search for errors where a function in the
call-chain is in a particular source file.


Note: Regular Expressions can be used when searching.


Appendix:
---------

1. A call-chain is the first few parent stack frames leading up to the
error.

2. A suppresion is a way of ignoring specific errors produced by your
program. For further information, see Valgrind's documentation.