# &app; Manual

## Overview

&app; is an ongoing effort to write a standalone graphical debugger that integrates well in the GNOME desktop environment. It currently features a backend which uses the well known GNU Debugger gdb to debug C / C++ programs.

### Perspectives

&app; is designed as a generic graphical workbench and a plugin system that can offer several different perspectives. Currently the only perspective provided is a debugging perspective, but in the future, there may be perspectives added for memory debugging with valgrind, or for profiling tools such as oprofile.

## Getting Started

This section explains how to start &app; and gives a basic overview of the application.

### Starting &app;

You can start &app; in the following ways:

Applications menu

- Choose Programming Nemiver Debugger.

Command line

- Type `&appcmd;`, then press Return.

  #### Additional Command-line Options

  You can find a list of options that can be passed to &app; on the command line by typing `&appcmd; --help-all`.

### The &app; window

When you start &app;, you will see a window that looks very much like the following:

#### &app; Window

Shows &app; main window.

The &app; window contains the following elements:

Menubar

- The menus on the menubar contain all of the commands you need to use &app;.

Toolbar

- The toolbar contains the basic debugging actions that can be used to run or step through the program being debugged.

Source View Notebook

- When source files are open, this area will display source files of the program being debugged.

Status Notebook

- The Status notebook contains several tabs for displaying information about the program being debugged. These include the following:

  Call Stack

- Displays the current state of the call stack of the program being debugged.

Variables

- Displays a list of all local variables and function arguments, in addition to their values and types.

Target Terminal

- If the program being debugged prints any output to the terminal, it will be displayed in this tab.

Breakpoints

- This tab displays a list of all breakpoints that have been set. You can view the source code of a particular breakpoint by double-clicking an item in the list or by right-clicking and selecting Go to Source from the menu. In addition, breakpoints can be deleted, enabled, or disabled in this tab. For more information about breakpoints, see nemiver-sect-breakpoints.

Registers

- This tab displays all of the CPU registers and their values. For more information, see nemiver-sect-registers.

Memory

- This tab displays a view of the current state of a specific memory location. For more information, see nemiver-sect-memory.

### Choosing a Program to Debug

There are several ways to begin debugging a program. Nemiver allows you to load a local executable file, load a core file, attach to a running process, or connect to a remote debugging server.

#### Debugging an Executable Program

##### Using the Workbench

To select an executable program to debug, select File Execute... , which should display the following dialog:

###### Execute Dialog

Shows dialog for selecting an executable to run

In this dialog, you can select the program to be debugged, any arguments or options to be passed to the executable on the command line, the working directory to run the executable in, and any Environment Variables that should be set when the executable is being debugged.

##### Using the Command Line

To start an executable program to debug from the command line, simply specify the name of the executable. You can either give an absolute path to the executable, or if it is in the path, you can simply give the basename of the executable. For example, if `/usr/bin` is in your path, both of the following are valid:

- `&appcmd; /usr/bin/progname`

- `&appcmd; progname`

###### Passing Options on the Command Line

If you would like to pass command line options to the program that you are debugging, you should enclose them in quotes to prevent &app; from processing them: `&appcmd; "prognam --arg1 --arg2"`.

#### Attaching to a Running Program

##### Using the Workbench

Select the menu item File Attach to Running Program... , which should display the following dialog:

###### Attach Dialog

Shows dialog for attaching to a running program

Select a process from the list and click OK to start debugging the selected program. There may be a lot of processes listed in the dialog, so you can filter the list to only ones that that you are interested in by typing some text into the text entry located just below the list.

##### Using the Command Line

To attach to a running program from the command line, use the `--attach` option. The `--attach` option accepts either a pid or a process name. So, for example, to debug the running process `foo` which has a pid of 1121, you could either type `&appcmd; --attach foo` or `&appcmd; --attach 1121`.

#### Loading a Core File

##### Using the Workbench

Select the menu item File Load Core File... to bring up the following dialog, which will let you load a core file:

###### Load Core File Dialog

Shows dialog for loading a core file

##### Using the Command Line

Core files cannot be loaded from the command line.

#### Remote Debugging

&app; allows you to connect to a remote debugging server.

##### Using the Workbench

To connect to a remote debugging server, select File Connect to Remote Target...

Remote Debugging Dialog

Select the executable to load and the location where any shared libraries are located, and then fill in the details about connecting to the remote server.

##### Using the Command Line

&app; does not provide a way to connect to a remote server using the command line

## Using &app;

This section describes how to use &app; to debug your application.

### Basic Debugging Actions

The basic debugging actions are available on the main toolbar, in the Debug menu, and as keyboard shortcuts. The most common actions are listed below:

Continue

- Starts the program. The program will run until it hits a breakpoint or until the program ends, unless it is interrupted manually by the user by clicking Stop. This action can be activated from the keyboard with F5.

Next

- Executes the next statement, and stops when it reaches the next line in this file. Some debuggers may call this action "Step Over". This action can be activated from the keyboard with F6.

Step

- Executes the next statement, stepping into the function if possible. Some debuggers may call this action "Step In". This action can be activated from the keyboard with F7.

Step Out

- Finishes execution of the current function and stops when it returns to the calling function. This action can be activated from the keyboard with Shift F7.

Restart

- Reloads the current executable and starts execution from the beginning. This action can be activated from the keyboard with Shift F5.

Stop

- Manually interrupt execution of the program. This action is only available when the debugger is running the executable (e.g. after a user has clicked Continue). This action can be activated from the keyboard with F9.

By default, after loading an executable, &app; creates a breakpoint at `main()`, so when execution reaches `main()`, it will stop and wait for input. You can then step through the program, examine variables (see nemiver-sect-inspecting-variables), or set additional breakpoints (see nemiver-sect-breakpoints).

### Inspecting Variables

&app; displays a list of all local variables in the Variables tab of the Status Notebook. If you'd like to examine a different variable (or even an arbitrary expression), you can use the Variable Inspector. To bring up the Variable Inspector, select Debug Inspect a Variable. When the variable inspector comes up, you'll see a window that looks similar to the following:

Variable Inspector Dialog

You can type any variable name or a simple expression (such as `pFoo->bar`) into the input box, and if the variable is valid and in scope, it will be display details about that expression.

Alternately, if you select the name of a variable in the source editor, and then launch the Variable Inspector, it will attempt to display information about the selected variable name.

#### Keyboard Shortcut

You can also start the Variable Inspector by pressing F12.

&app; will also let you display a list of all global variables in an application in a separate dialog. To display the Global Variables dialog, select Debug Show Global Variables or press Ctrl G.

Global Variables Dialog

For some programs (especially C++ programs), listing all of the global variables may take a very long time.

### Setting Breakpoints

There are several different ways to set breakpoints in &app;. &app; automatically sets a breakpoint at `main()` when you first begin debugging a new executable. If you want to set additional breakpoints you can do one of the following:

- Click in the margin next to the line where you want the breakpoint to be set

- Place your cursor on a line where you want the breakpoint to be set and set the breakpoint by either selecting Debug Toggle Breakpoint at Cursor, or by pressing F8

- Set a breakpoint at a specific function name or at a specific location in a file by selecting Debug Set Breakpoint... or by pressing Ctrl B. This will bring up a dialog that looks like the following:

  Set Breakpoint Dialog

  You can specify a breakpoint at a particular location in a file, or by function name. If there are more than one function with the same name, &app; will display a list of all matching functions and ask you to pick the one you want.

#### Disabled Breakpoints

Breakpoints can be either enabled or disabled. The debugger will stop execution whenever it reaches an enabled breakpoint but will not be affected by any breakpoints in the disabled state. This allows you to temporarily remove a breakpoint without actually deleting it.

To disable or enable a breakpoint, click the checkbox next to the breakpoint number you want to enable or disable in the Breakpoints tab of the Status Notebook. Alternately, you can press Shift F8 to enable or disable a breakpoint that is set on the line that the cursor is currently on.

The following figures show the difference between enabled and disabled breakpoints in the source editor.

Illustration of an enabled breakpoint

Enabled Breakpoint

Illustration of a disabled breakpoint

Disabled Breakpoint

#### Opening Source Files

Sometimes you don't know exactly the function name or line number where you want a breakpoint to be set, so you must open a source file to figure it out. You could just open arbitrary files from the filesystem, but &app; can also provide a list of source files that were used to build the executable and allow you to select from this list. When you select File Open Source File..., the following window should be displayed:

Shows dialog for opening source files

To select an arbitrary file from the filesystem, choose the Select from Filesystem option. To select from a list of files that produced the executable, choose Select from Target Executable.

##### Determining Source Files for Dynamically Loaded Modules

If the target executable loads modules at runtime (e.g. using `dlopen()`), &app; will not be able to determine which files were used to build these modules until they are actually loaded.

### Advanced Debugging

#### Registers

The register editing widget is located in the Registers tab of the Status Notebook. Alternately, you can press Alt F5 to jump directly to the correct tab.

The Register Editing Widget

This widget shows the current values of all of the CPU registers. You can edit the register values by clicking in the Value column and entering a new value. If the value for the register changed since the last time the debugger stopped, it will be highlighted in red.

#### Memory

The memory widget allows you to view a section of memory directly. This enables you to get a lower-level view of what's happening while your program is running.

The Memory Editing Widget

To display a segment of memory in the memory view widget, enter a memory address in the Address field. If the address is valid for the program being debugged, the memory view will display the memory values starting at the specified address. Memory values can be displayed in byte format, word format (2 bytes), or long word format (4 bytes) by choosing an option from the Group By drop-down menu. The memory values will automatically be updated as you step through the program.

In addition to viewing the memory values, you can also use the memory widget to modify memory values. You can edit either the hex byte representation (the left-hand section of the memory widget), or the ASCII representation (the right-hand section of the memory widget). All changes will be applied immediately.

## Session Save and Restore

&app; can save your debugging sessions for you so that you can resume them at a later time. This includes saving information such as which executable is being debugged, what environment variables are set, what command-line options are passed to the executable, which files are open, and which breakpoints are set so that you can get back to where you left off last time as quickly as possible.

### Saving Sessions

&app; will save your session automatically on exit, so you don't even have to worry about it. However, if you want to explicitly save the session before closing &app;, you can do so by selecting File Save Session To Disk.

### Resuming Saved Sessions

#### Using the Workbench

Select File Resume Saved Session... and select a session from the list.

##### Session Dialog

Shows dialog for resuming a saved session

#### From the Command Line

If you know the session ID of the session you want to run, you can start that debugging session from the command line. For example, if you want to run session number 3, you can do so with the following command: `&appcmd; --session 3`.

## About &app;

&app; was written by Dodji Seketeli and Jonathon Jongsma, with contributions from many others. To find more information about &app;, please visit the &app; project website.

To report a bug or make a suggestion regarding this application or this manual, see the Feedback section of the GNOME User Guide.

This program is distributed under the terms of the GNU General Public license as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license can be found at this link, or in the file COPYING included with the source code of this program.