Alleyoop

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

The example above will initialise Alleyoop to run the command:

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

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.

An example usage case might be:

  alleyoop -R /cvs/evolution -- evolution --launch-composer

Note: the "--" switch terminates the options meant specifically for Alleyoop, letting it know that all following arguments should not be interpreted.

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=memcheck

-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 of 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 suppression is a way of ignoring specific errors produced by your program. For further information, see Valgrind's documentation.

Webstite by: Vadim Peretokin Design: Luka Cvrk · Sponsored by B4Contact · Released under a Creative Commons Licence