GNOME.org

Nemiver Manual

1. Overview

Nemiver 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.

1.1. Perspectives

Nemiver 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.

2. Getting Started

This section explains how to start Nemiver and gives a basic overview of the application.

2.1. Starting Nemiver

You can start Nemiver in the following ways:

Applications menu

Choose Programming ▸ Nemiver Debugger.

Command line

Type nemiver, then press Return.

Additional Command-line Options

You can find a list of options that can be passed to Nemiver on the command line by typing nemiver --help-all.

2.2. The Nemiver window

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

Figure 1 Nemiver Window

The Nemiver window contains the following elements:

Menubar

The menus on the menubar contain all of the commands you need to use Nemiver.

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 Section 3.3 ― Setting Breakpoints.

Registers

This tab displays all of the CPU registers and their values. For more information, see Section 3.4.1 ― Registers.

Memory

This tab displays a view of the current state of a specific memory location. For more information, see Section 3.4.2 ― Memory.

2.3. 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.

2.3.1. Debugging an Executable Program

2.3.1.1. Using the Workbench

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

Figure 2 Execute Dialog

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.

2.3.1.2. 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:

  • nemiver /usr/bin/progname
  • nemiver 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 Nemiver from processing them: nemiver "prognam --arg1 --arg2".

2.3.2. Attaching to a Running Program

2.3.2.1. Using the Workbench

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

Figure 3 Attach Dialog

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.

2.3.2.2. 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 nemiver --attach foo or nemiver --attach 1121.

2.3.3. Loading a Core File

2.3.3.1. 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:

Figure 4 Load Core File Dialog
2.3.3.2. Using the Command Line

Core files cannot be loaded from the command line.

2.3.4. Remote Debugging

Nemiver allows you to connect to a remote debugging server.

2.3.4.1. Using the Workbench

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

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.

2.3.4.2. Using the Command Line

Nemiver does not provide a way to connect to a remote server using the command line

3. Using Nemiver

This section describes how to use Nemiver to debug your application.

3.1. 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, Nemiver 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 Section 3.2 ― Inspecting Variables), or set additional breakpoints (see Section 3.3 ― Setting Breakpoints).

3.2. Inspecting Variables

Nemiver 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:

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.

Nemiver 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.

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

3.3. Setting Breakpoints

There are several different ways to set breakpoints in Nemiver. Nemiver 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:

    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, Nemiver will display a list of all matching functions and ask you to pick the one you want.

3.3.1. 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.

Enabled Breakpoint

Disabled Breakpoint

3.3.2. 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 Nemiver 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:

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()), Nemiver will not be able to determine which files were used to build these modules until they are actually loaded.

3.4. Advanced Debugging

3.4.1. 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.

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.

3.4.2. 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.

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.

4. Session Save and Restore

Nemiver 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.

4.1. Saving Sessions

Nemiver 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 Nemiver, you can do so by selecting File ▸ Save Session To Disk.

4.2. Resuming Saved Sessions

4.2.1. Using the Workbench

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

Figure 5 Session Dialog

4.2.2. 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: nemiver --session 3.

5. About Nemiver

Nemiver was written by Dodji Seketeli and Jonathon Jongsma, with contributions from many others. To find more information about Nemiver, please visit the Nemiver 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.

  • Nemiver Manual