# Debugging

To debug is human. To fix it is divine...

Well, the human part is what this section is about. The divine part is up to you!

When a program does not behave in the way it is supposed to, we say the program contains a bug or bugs. This does not refer to compilation errors — those are simply errors and they are relatively easy to clear, because the compiler tells you where the problems are. On the other hand, bugs are errors that happen during the execution of the program and they can be hard (sometimes very hard!) to detect.

Any program that you think is bug-free is never completely bug-free. All we can try to do is to reduce the number of bugs contained in the program. The process of removing bugs is known as debugging, and the tool that is used for debugging is called the debugger. Anjuta provides a very user-friendly and powerful debugging environment (actually, a GUI wrapper over gdb, a powerful command line debugging tool and standard on Linux).

A debugger tracks and traces the execution of the program and provides various views of information needed to study the execution of the program.

## Start and stop

The debugger is always started with a program loaded. There are two ways to do this:

- Running an executable

- Attaching to a process

### Running an executable

Choose the menu item Debug Run Target… to display a dialog box where you can select:

- The program that you want to debug
- The command line parameters
- If you want a terminal or not (the Anjuta terminal plugin is used)
- If you want to stop the program at the beginning or not

The drop-down menu of the target drop-down combination box is already filled with all executables of the current project. But you can select another executable not part of the project. The debugger accepts libtool executable, it means script,generated by libtool, wrapping the real executable. Note that an URI is expected here, not a file path even if the debugger currently supports only local files.

When you have set everything you can click on Execute to start the debugger, load your program and stop at its beginning if requested.

In order to better user the debugger, it is strongly recommended to debug program with debugging information (-g for gcc) and no optimization (-O0 for gcc).

### Attaching to a Process

It is also possible to attach to a running process and debugging it by choosing the menu item Debug Attach to Process …. A list of all the process running on the system will appear.

#### Attach to Process dialog

Attach to Process dialog

Select the process to attach to and click OK to start the debugger, attach to the selected process and stop it.

It is currently not possible to load symbol informations for the attached process. They should be included in the process.

### Restarting an executable

After running an executable at least one time, you can choose the menu item Debug Restart Target to restart your program. It is just a shortcut that will stop the debugger if it is currently running and restart it with the last executable without displaying the start dialog.

### Stopping the Debugger

Choose the menu item Debug Stop Debugger to stop the debugger. This option will kill the program which is being debugged. If the debugger has been attached to a running process, it will just detach from it without killing it. You will get a confirmation box if a program is currently attached or running.

### Adding source directories

Choose the menu item Debug Add source paths… to display a dialog box allowing you to add and remove source directories.

Most executables include full file paths, so defining the directories where are the source files is not useful. But some executables include only file names without paths, in this case, the source files will be searched in all these directories by the debugger. The directories order can be important if several files have the same name, so you can change it using the Up and Down buttons. The directories list is send to the debugger when it is started. After changing it, you need to restart the debugger to take it in account.

## Execution

Execution of a program in the debugger can be finely controlled. The program can be executed in single steps, or allowed to continue until it encounters a breakpoint. Executing like this is essential for tracking program behavior. Like a video editing session, the program can be executed in slow motion with the ability to go forward, pause, stop, and so on. You cannot go backward yet though.

The methods those can be used to execute a program in the debugger are described in the next sections. These commands are available only when the program is already started.

### Single stepping (step in)

Choose the menu item Debug Step In or click on the Step In icon in the Debug toolbar to step into a program.

Single stepping executes only one statement of the program (from the place where it has stopped) and then returns control. If the statement that is executed contains one or more functions, the debugger tries to step inside the functions (in the sequence in which the functions are executed). Once the statement is executed and control is passed back, it is possible to study the various program parameters.

If the Disassembly window has the focus when this command is selected, it executes only one assembler instruction.

### Single stepping (step over)

Choose the menu item Debug Step Over or click on the Step Over icon in the Debug toolbar to step over statements in a program.

Step over is similar to step in, except that it does not step inside any function in the statement being executed. The statement will be executed in one go.

If the Disassembly window has the focus when this command is selected, it executes one assembler instruction but does not stop inside if this instruction is a call to a subroutine.

If a dynamic library is loaded during the step, the program will not stop at the end of the step. But it will run until it finds a breakpoint or you stop it.

### Single stepping (step out)

Choose the menu item Debug Step Out or click on the Step Out icon in the Debug toolbar to step out in a program.

Step out will execute the current function until it returns. The program will be stopped once it exits from the function. Step out is not really single stepping, because it does not only execute a single statement — it executes the whole function until that function returns to the calling function.

### Run/Continue

Choose the menu item Debug Run/Continue or click on the Run/Continue icon in the Debug toolbar to continue the execution of a program.

This option continues the execution of the program until a breakpoint is encountered, or the program exits.

### Run To

Choose the menu item Debug Run to Cursor or click on the Run to Cursor icon in the Debug toolbar to run until the line at cursor is reached.

This option continues the execution of the program until the line or the address (if the Disassembly window has the focus) where the cursor is reached.

### Stop Program

While the program is running and has control, no debugging tasks can be performed. To obtain control while the program is running, choose the menu item Debug Pause Program or click on the Pause Program icon in the Debug toolbar. This will interrupt the program and return control to the debugger.

## Breakpoints

When debugging a program, it is useful to be able to stop the execution of the program at a particular point, so that the state of the program can be examined at that location. Breakpoints enable this to happen. Breakpoints can be set at different locations in a source file and then the program is allowed to run. When a breakpoint is encountered, the execution of the program is suspended, enabling expressions to be evaluated, variables to be inspected, the stack trace to be studied, and so on.

### Listing Breakpoints

The Breakpoint list window can be opened by choosing View Breakpoints

#### Breakpoint view

Breakpoint view

The view has the following columns:

Location

  This is the position of the breakpoint in the source file. When the breakpoint is set by the debugger, you can get additional information like the function where is the breakpoint.

Address

  This field is filled with the address of the breakpoint when it is set by the debugger.

Type

  This displays always "breakpoint". It will be used in a next version supporting different kind of breakpoints.

Condition

  This is the breakpoint condition, it is empty if no condition is defined.

Pass count

  When the debugger is not running, this column displays the pass count of the breakpoint, zero if it is not defined.

  When the debugger is running, if pass count is zero, this column displays the number of time this breakpoint has been triggered. If pass count is not zero, both numbers are displayed. The pass count is the second number.

State

  This is the state of the breakpoint. You could have.

  - Pending: breakpoint is not set in your program.

  - Permanent: breakpoint is set (id number in given inside the parenthesis).

  - Temporary: breakpoint is set but will be deleted if reached.

All breakpoints are kept across anjuta session even if they correspond to a non existing place. In this case their state are set as pending.The interface try to set them each time the program is started or a new dynamic library is loaded.

### Adding or Setting Breakpoints

Choose the menu item Debug Add Breakpoint… or Add Breakpoint… in the breakpoint list popup menu to open the add breakpoint dialog.

#### Breakpoint add dialog

Breakpoint add dialog

You need to enter the location and optionally, the break condition and the pass count then click OK to set the breakpoint.

Location

  Enter the location at which to set the breakpoint. It has to be specified in one of the following formats:

  1. File_name:Line_number

  2. Function_name

  3. File:Function_name

  The first one is obvious — The location refers to the line number Line_number in the source file File. The second refers to the first line of the function Function_name. The third is similar to the second, except that this notation is used where there is more than one function with the name Function_name in the program. It is possible to differentiate between them by providing the File, so the notation refers to the function Function_name in the file File.

Condition

  The Condition parameter displays a associated expression which should evaluate to a Boolean value — that is, the evaluation of the expression should result in either TRUE(1) or FALSE(0). If the final evaluation value is not a Boolean value, then it will be appropriately type casted to a Boolean.

  Every time the breakpoint is encountered during the execution, the break condition will be evaluated. The debugger will break the execution only if the evaluation results in a TRUE value, otherwise it will continue the execution as though there had been no breakpoint.

  The default value, if you left this field blank, of Break condition is TRUE. The debugger will always break the execution at the breakpoint location.

Pass Count

  The Pass count is an integer (unsigned) value which tells the debugger to skip the breakpoint that number of times before it is considered. Pass count has a higher priority than the Break condition. Only when the Pass count reaches zero will the debugger evaluate the Break condition (if any condition is present). If there is no condition, the debugger will break the execution once the Pass count counts down to zero.

  The default value, if you left this field blank, of the Pass count is zero. The breakpoint will be considered when it is first encountered.

A breakpoint may also be set by selecting a line in the editor and choosing the menu item Debug Toggle Breakpoint in the editor popup menu item or the Toggle Breakpoint icon in the Debug toolbar.

Breakpoints can be added even if the debugger is not started or in dynamic library not loaded yet. But they cannot be added while a program is running under control of the debugger.

### Editing Breakpoints

It is possible to change the condition and the pass count by selecting the breakpoint in the breakpoint list and click in the popup menu item Edit Breakpoint.

Edit the entries as required and click on OK to commit the changes.

### Deleting Breakpoints

Select the breakpoint in the breakpoint list view and click on Remove Breakpoint to delete it.

A existing breakpoint may also be deleted by selecting the line in the editor and choosing the menu item Debug Toggle Breakpoint, the editor popup menu item Toggle Breakpoint or the Toggle Breakpoint icon in the Debug toolbar.

It is possible to remove all breakpoints by clicking on Debug Remove All Breakpoints or on Remove All Breakpoints in the breakpoint list popup menu.

### Enabling or Disabling Breakpoints

Click on the Enable column of the Breakpoint list window or in the menu item Enable Breakpoint to enable or disable the selected breakpoint. The breakpoint will be enabled or disabled, depending on its current state.

To disable all breakpoints, click on Debug Disable All Breakpoints or on Disable All Breakpoints in the breakpoint list popup menu.

## Expressions

### Listing local variable

When a program is running under the control of the debugger, the Locals list window can be opened by choosing View Locals

Local variables of the current frame (the current function in which the program control is present) are displayed in the Locals list window. During execution of the program (eg. during single stepping), local variables will be updated. If any variable value was changed in the last debugging step, its value will be highlight in red. The variables are presented in a tree form for easy view.

#### Local variables

Local variables

The value of a local variable can be modified by selecting it and clicking in the value column.

Gdb is more and more often used as a back end for a graphical front end. It has been improved recently in this area. It is recommended to use the latest version (6.6) of gdb. On older version, gdb can crash when the front end ask for an pointer with an invalid (but not used) value.

### Listing watched expressions

Inspecting or evaluating an expression provides the result only once. To continuously monitor some variables or expressions, use expression watch.

Choose the menu item View Watches to display the expression watch window.

### Adding an expression to watch

Right-click on the expression watch window to open the Operation menu. Choose the menu item Add Watch…. Alternatively, you can use Debug Add Watch… A dialog prompting for the expression will appear. Enter the expression and click OK.

By default watch expression are updated automatically each time the program is stopped. This can be changed in the add watch dialog or later using the Automatic update menu item in the expression watch window popup menu. A watched expression can be update manually by choosing Update Watch or Update All in the previous menu.

It is not necessary to have the debugger running to add a new watch expression. If the debugger is not running or the corresponding expression cannot be found, the front end will try to create the watch expression, each time the program is stopped.

### Removing an expression from watch

Select the watch expression that you want to remove in the expression watch window, then open the Operation menu, clicking with the right mouse button, and choose the menu item Remove to remove it.

All watch can be removed by choosing Remove All in the popup menu of the expression watch window.

### Evaluating expressions

When control is returned from a program — possibly at a breakpoint — it is possible to evaluate expressions or inspect the values of variables in the program. Choose the menu item Debug Inspect/Evaluate …, Inspect/Evaluate … in the popup menu of the editor or click the Inspect button on the Debug Toolbar.

A window will appear showing the evaluation of the expression highlighted in the editor. You can evaluate a new expression by clicking on the name column and entering the new one.

The expression can be added directly in the list of watched expressions by clicking on Add button.

### Inspecting expressions in editor window

When the debugger is active with the program stopped, you can get the value of an expression just by putting the pointer over it and stay here for a few time. If the expression is already present in the local or watch window, its value is displayed in a tool tips window.

It is currently working only for simple variable, not for structures or arrays.

## Stack Trace

### Stack Window

The Stack trace window shows the contents of the program stack. It lists all of the functions and their arguments in the sequence they were called. There is also a number representing each call. This number is called the Frame. Each call in the trace exists in a different frame. This starts from frame 0 (the last function called) and grows higher as the function nesting become deeper.

Choose the menu item View Stack, to open the stack trace for the program being debugged.

#### Stack trace window

Stack trace window

A small arrow points to the currently selected frame in the stack trace. By default, this will be frame 0, the last function called. All of the evaluation and inspection of expressions or variables will be with reference to this selected frame. The scope of the variables or expressions being evaluated will be limited to the selected frame only. The same applies for new expressions only in the watch.

### Setting the current frame

Double-clicking on any frame in the stack trace set that frame as the currently selected frame (the arrow will point to the frame, indicating that it has been selected as the current frame). Alternatively, open the Operation menu by right-clicking on the Stack trace window, and choose the menu item Set current frame to set the frame.

Changing the stack frame changes the Locals list window content, but not the expression watch window as each expression is evaluated in the frame used when it was defined.

## Thread

### Thread Window

The Thread window show all threads used by the program and display the current thread. Choose the menu item View Thread, to open this window.

A small arrow points to the current thread. When the program is stopped, it correspond to the thread which has been interrupted. Each thread has its own stack frame,so changing the current thread change the current stack frame.

### Setting the current thread

Double-clicking on any thread in the thread list will set that thread as the currently selected thread (the arrow will point to the thread, indicating that it has been selected as the current thread). Alternatively, open the Operation menu by right-clicking on the Thread list window, and choose the menu item Set current thread to set the thread.

Changing the thread changes the value of CPU registers and the current stack frame, so the Locals list window change too.

## CPU

### Register window

It is possible to examine the contents of the internal registers of the CPU (microprocessor). Choose the menu item View Registers. A window listing all of the available registers in the microprocessor and their corresponding contents will appear.

If any register value was changed in the last debugging step, its value will be highlight in red. It is possible to change one register value by selecting it and clicking in the value column.

### Memory window

Choose the menu item View Memory , to open the memory window for the program being debugged. This window shows the contents of all memory.

The first is the memory address in hexadecimal, the second is the memory content in hexadecimal too and the last column is the memory content in ASCII.

The addressing space of even a 32 bits microprocessor is quite big(4 Giga bytes), so it is very difficult to go to a particular address with the scrollbar. But you can click on the right mouse button, get a new menu and select Goto address to get a small edit box where you can enter an address in hexadecimal.

### Disassembly window

Choose the menu item View Disassembly , to open the disassembly window for the program being debugged.

The first column is the address in hexadecimal. In the second column, you can have a label starting at the beginning of the line and ended with a colon or a assembler instruction starting after 4 space characters.

Again, as the addressing space is very big, the scrollbar is quite useless. You can click on the right mouse button, get a new menu and select Goto address to get a small edit box where you can enter an address in hexadecimal. The position in the disassembly window will be changed to the program counter value when the program is stopped.

## Others

There are a number of other debugger features used less frequently and not very well integrated in the new front end but which are still working.

### Dynamically loaded Libraries

To obtain a list of the dynamic libraries used by the program, choose the menu item DebugInfo Shared Libraries. This will bring open a window which will list all the shared libraries the program has loaded and their locations in the memory. It also shows whether the symbol table is loaded or not (Yes/No).

#### Shared Libraries window

Shared Libraries window

### Kernel Signals

Kernel signals are a way of signaling between processes in Linux. The list of signals available for a program can be displayed by choosing the menu item DebugInfo Kernel Signals. A window will open which lists all of the signals available in the system along with a brief description of each signal.

#### Kernel Signals window

Kernel Signals window

There are three columns which specify what to do when the signal is received:

1. Stop — this tells the debugger whether to stop the program execution (and return control) when the program receives this signal.

2. Print — this tells the debugger whether to display the received signal.

3. Pass — this tells the debugger whether to pass the signal to the program.

The popup menu that is displayed when you click on the right mouse button has all its item disabled because the corresponding functions are not implemented yet.

### Information about used files

It is possible to get some information about the files used by the debugged program. by choosing the menu item Debug Information Target files. A window will open displaying all informations.

### Information about debugged program

It is possible to get some information about the debugged program by choosing the menu item Debug Information Program. A window will open displaying all informations.

### Information about kernel structure

It is possible to get some information kernel data on the current process by choosing the menu item Debug Information Kernel user struct. A window will open displaying all informations.

### Information about global variables

It is possible to list all global variables by choosing the menu item Debug Information Info Global Variable. A window will open listing all global variables.

### Information about the current frame

It is possible to obtain information about the currently selected frame by choosing the menu item Debug Information Info Current Frame. A window will open describing the current frame.

### Information about the current function arguments

It is possible to obtain information about the arguments of the current function by choosing the menu item Debug Information Arguments. A window will open describing the arguments.

### User command

To send directly a command to the back end choose the menu item Debug Debugger command. This will bring a small dialog where you can enter commands that will be send to the debugger when you press Return.

The front end sends this command directly to the back end without doing any check. By example if you set a breakpoint like this, it will not appear in the breakpoint list window. It is better to avoid using this command unless you know exactly what you are doing.