@ifclear GPS

@ifinfo
@node Top, Introduction, (dir), (dir)
@top Using the GNU Visual Debugger

Using the GNU Visual Debugger

GVD, the GNU Visual Debugger

Version @value{GVDVersion}

Date: $Date: 2002/12/10 14:12:44 $

Copyright @copyright{} 2000-2001, ACT Europe.
This document may be copied, in whole or in part, in any form or by any
means, as is or with alterations, provided that (1) alterations are clearly
marked as alterations and (2) this copyright notice is included
unmodified in any copy.

@menu
* Introduction::
* Description of the main windows::
* Integrating GVD::
* Debugging a program remotely::
* Environment::
* Frequently Asked Questions::

@detailmenu
 --- The Detailed Node Listing ---

Description of the main windows

* The Menu Bar::
* The Tool Bar::
* The Call Stack Window::
* The Data Window::
* The Breakpoint Editor::
* The Memory Window::
* The Explorer Window::
* The Source Window::
* The Assembly Window::
* The Debugger Console::
* The Status Line::

Integrating GVD

* General Information::
* Using GVD with Glide::
* Using GVD with Emacs::
* Using GVD with XEmacs::
* Using GVD as a Library::
* Using GVD as a Corba Object::

Debugging a program remotely

* Using GVD with a Remote Debugger::
* Using GVD with a Remote Program::

Environment

* Command Line Options::
* Environment Variables::
* Files::
* Limitations::
* Reporting bugs::

Frequently Asked Questions

@end detailmenu
@end menu
@end ifinfo

@c --------------------------------------------------------------------
@node Introduction
@chapter Introduction
@c --------------------------------------------------------------------

@noindent
GVD is a graphical front-end for text-based debuggers such as GDB.
A knowledge of the basics of the underlying debugger used by GVD will help
understanding how GVD works and what kind of functionalities it provides.
Please refer to the debugger-specific documentation (e.g the GDB documentation)
for more details.

The purpose of a debugger such as GVD is to allow you to see what is going on
within another program while it executes, or what a program was doing
at the moment it crashed.

@c --------------------------------------------------------------------
@node Description of the main windows
@chapter Description of the main windows
@c --------------------------------------------------------------------

@noindent

@menu
* The Menu Bar::
* The Tool Bar::
* The Call Stack Window::
* The Data Window::
* The Breakpoint Editor::
* The Memory Window::
* The Explorer Window::
* The Source Window::
* The Assembly Window::
* The Debugger Console::
* The Status Line::
@end menu

@iftex
@cindex screen shot
@image{main-window, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{main-window}
@end ifhtml

@c --------------------------------------------------------------------
@node The Menu Bar
@section The Menu Bar
@c --------------------------------------------------------------------

The menu bar provides operations that act either at a global level, or on
a specific debugger. Since GVD can handle multiple debuggers at the same
time, the commands that deal with debugging on a specific module always
use the current debugger to perform the various operations specified by the
menus. Key shortcuts are available for the most common operations, and
are displayed in the menus themselves.
Here is a detailed list of the menu items that can be found in the menu bar:

@end ifclear
@c GPS

@ifset GPS
@c -------------------------------------------------------------------- 
@node The Debug Menu
@section The Debug Menu
@cindex menu
@cindex debug
@cindex debugger
@c --------------------------------------------------------------------

@noindent
The @code{Debug} entry in the menu bar provides operations that act at a
global level. Key shortcuts are available for the most common operations, and
are displayed in the menus themselves.
Here is a detailed list of the menu items that can be found in the menu bar:
@end ifset

@ifclear GPS
@subsection Program
@cindex program
@end ifclear

@table @b
@ifclear GPS
   @item Run/Start...
@cindex run
@cindex start
@end ifclear
@ifset GPS
   @item Run...
@cindex run
@end ifset
Opens a dialog window allowing you to specify the arguments to pass to the
program to be debugged, and whether this program should be stopped at the
beginning of the main subprogram. If you confirm by clicking on the @i{OK}
button, the program will be launched according to the arguments entered.

   @item Step
@cindex step
Execute the program until it reaches a different source line.

   @item Step Instruction
@cindex stepi
Execute the program for one machine instruction only.

   @item Next
@cindex next
Execute the program until it reaches the next source line, 
stepping over subroutine calls.

   @item Next Instruction
@cindex nexti
Execute the program until it reaches the next machine instruction,
stepping over subroutine calls.

   @item Finish
@cindex finish
Continue execution until selected stack frame returns.

   @item Continue
@cindex continue
Continue execution of the program being debugged.

   @item Interrupt
@cindex interrupt
Asynchronously interrupt the program being debugged. Note that depending on
the state of the program, you may stop it in low-level system code that does
not have debug information, or in some cases, not even a coherent state. Use
of breakpoints is preferable to interrupting programs. Interrupting programs
is nevertheless indispensable in some situations, for example when the
program appears to be in an infinite (or at least very time-consuming) loop.

@ifset GPS
   @item Terminate
@cindex terminate
Terminate your debug session, by closing the data window and the debugger
console, as well as terminating the underlying debugger (e.g @code{gdb}) used
to handle the low level debugging.
@end ifset

@end table

@ifclear GPS
@subsection File
@end ifclear
@ifset GPS
@subsection Debug
@end ifset

@table @b

@ifclear GPS
   @item Open Program...
@end ifclear
@ifset GPS
   @item Connect to Board...
@cindex connect
@cindex board
@cindex target
@cindex cross debugger
Opens a simple dialog to connect to a remote board. This option is only
relevant to cross debuggers.

   @item Load File...
@cindex load
@end ifset

@anchor{open program menu}
Opens a file selection dialog that allows you to choose a program to
debug. The program to debug is either an executable for native debugging, or
a partially linked module for cross environments (e.g VxWorks).

@ifclear GPS
Do not use this menu to edit a source file, see the @ref{The Explorer Window},
or the @ref{open source menu}.

@item New Debugger...
@cindex new debugger
@anchor{new debugger menu}
Opens a dialog to create a new debugger window. By default,
the @i{Replace Current Debugger} check button is active, and
the new debugger window will replace
the current debugger. Otherwise, it will be added in the main window as an
additional debugger.
This dialog allows you to specify the name of the executable to debug by
entering its name in the @i{Program File entry}, or by clicking on the
@dots{} button to open a file selection dialog. You can also select
the machine on which your underlying debugger (e.g GDB) will run. By default,
the debugger will run on the current machine (the machine on which GVD is
running), so you only need to specify a value if you want to do remote
debugging.
For more information, see @ref{Debugging a program remotely}.

@end ifclear

   @item Add Symbols...
@cindex add symbols
Add the symbols from a given file/module. This corresponds to the gdb
command @i{add-symbol-file}. This menu is particularly useful under VxWorks
targets, where the modules can be loaded independently of the debugger.
For instance, if a module is independently loaded on the target (e.g. using
windshell), it is absolutely required to use this functionality,
otherwise the debugger won't work properly.

@ifclear GPS
   @item Open Core Dump...
@cindex core file
@anchor{core files}
This will open a file selection dialog that allows you to debug a core file
instead of debugging a running process. Note that you must first specify an
executable to debug before loading a core file.

   @item Edit Source
@cindex edit source
Launches an external editor that will open the file currently displayed
in the source window (see @ref{The Source Window}). You can specify the name of
the external editor by using the @ref{preferences dialog}.

   @item Open Source...
@cindex open source
@anchor{open source menu}
Opens a file selection dialog that allows you to load any source file in the
source window. You can also directly open the source files used in your
application by using @ref{The Explorer Window}.

   @item Open Session...
@cindex session
Opens a dialog giving you the list of sessions that are saved in the
@file{$HOME/.gvd/sessions} directory on Unix systems, and
@file{%HOME%\.gvd\sessions} on Windows systems. The @i{Session List} area
lists all
such sessions. The @i{Session} field shows the current selection (which can
be specified either by entering the name on the keyboard, or by clicking in the
@i{Session List} window). The right area gives you a list of sub-sessions,
or of debuggers launched during a selected session. You can select any of the
debuggers of a specific session in order to replay one, some, or all of them.
To select the debuggers, either click on the check box on the left of each
item, or use the @i{Select All} and @i{Unselect All} buttons.
If you confirm by clicking on the @i{OK} button, GVD will open a new
debugger for each sub-session selected and will replay all the commands
automatically.

   @item Save Session As...
Opens a dialog similar to the @i{Open Session} dialog, allowing you to specify
the name of the session to save, and what sub-sessions/debuggers to save.
By default, this will save all the sub-sessions ran in GVD since start up.

@end ifclear
@c GPS

   @item Attach...
@cindex attach
Instead of starting a program to debug, you can instead attach to an
already running process. To do so, you need to specify the process id
of the process you want to debug. The process might be busy in an
infinite loop, or waiting for event processing. Note that as for
@ref{core files}, you need to specify an executable before attaching to a
process.

   @item Detach
@cindex detach
Detaches the currently debugged process from the underlying debugger.
This means that the executable will continue to run independently. You can use
the @i{Attach To Process} menu later to re-attach to this process.

@ifset GPS
   @item Debug Core File...
@cindex core file
@anchor{core files}
This will open a file selection dialog that allows you to debug a core file
instead of debugging a running process. Note that you must first specify an
executable to debug before loading a core file.

   @item Kill
@cindex kill
Kills the process being debugged.
@end ifset

@ifclear GPS
   @item Change Directory...
@cindex change directory
Open a directory selection dialog to change the directory in the underlying
debugger. This is useful before executing a process, or when loading a
file using a relative path.

   @item Close
@cindex close
@anchor{close menu}
Closes the current debugger. If this is the only debugger, the main window
will remain visible, but with a gray area instead of the notebook containing
the Data, Explorer, Source and Debugger windows.
To create a new debugger, see also the @ref{new debugger menu}.

   @item Exit
@cindex exit
Saves the window settings and exit GVD.
@end ifclear
@c GPS

@end table

@ifclear GPS

@subsection Edit
The only item currently available in this menu is the preferences menu.

@subsubsection Preferences...
@anchor{preferences dialog}
Opens a dialog window allowing you to modify the global preferences of GVD.
To enable the new preferences, you simply need to confirm by pressing the
@i{OK} button. The preferences will be saved in a file located in
@file{$HOME/.gvd/preferences} on Unix systems, and
@file{%HOME%\.gvd\preferences} on Windows systems.

To simply test your changes, you can use the @i{Test} button. Pressing
the @i{Cancel} button will undo all your changes.

The preferences dialog is composed of five areas, accessible through the
tabs at the top of the dialog, labeled @i{General}, @i{Source}, @i{Data},
@i{Command}, @i{Memory}, @i{Helpers}. Each page corresponds to a section of
preferences.

@table @b
@item General
Gives access to the general preferences in GVD.

@table @i
@item Break On Exceptions
Specifies whether a breakpoint on all exceptions should be set by default
when loading a program.

@item Status Bar Time Out
Specifies the time interval after which a message in the status bar will
disappear. Messages that have disappeared can be displayed using the arrow
in the bottom left area of the main window.

@item File Extensions
Indicates the filename extensions that are recognized for each of the
following supported languages: Ada, C, C++.
Each text entry is a semicolon separated list of filename extensions, e.g
@code{.ads;.adb} for Ada files.
@end table

@item Source
You can modify the preferences for the @i{Explorer}, @i{Source}, and
@i{Assembly} windows, in particular the font and colors used to highlight
elements.

@table @i
@item Display Explorer Tree
Indicates whether the list of files should be displayed.

@item File Name Background
Indicates the color used for the background of the file name in the editor.
This is also used for the background of the current frame in the Call Stack
window.

@item Font
Indicates the font used in the editor.

@item Show Line Numbers
Specifies whether line numbers should be displayed in the code editor.

@item Show Lines with Code
Specifies whether dots should be displayed in the code editor for lines that
contain code.

@item Automatic Display of Variables
Specifies whether tool tips should appear automatically to display the value
of the variable under the cursor.

@item Syntax Highlighting
Indicates whether the editor should provide color highlighting.

@item Strip Carriage Return
Indicates whether Carriage Return characters should be stripped when reading a
file.  GVD tries to detect this automatically, but in some rare cases it can be
useful to enable this option manually.

@item Comments
Indicates color to be used used for comments.

@item Strings
Indicates color to be used for string literals.

@item Keywords
Indicates color to be used for keywords.

@item Current Line
Indicates color to be used for highlighting the current line in the editor
@end table

@item Data
Lets you change the preferences of the @i{Data Window}, in particular
the fonts and colors used to display the data graphically.

@table @i
@item Clickable Item
Indicates color to be used for the items that are click-able (e.g pointers).

@item Title Background
Indicates color to be used for the background of the title.

@item Changed Data
Indicates color to be used to highlight fields that have changed since the last update.

@item Auto-Refreshed
Indicates color to be used for auto-refreshed items.

@item Frozen
Indicates color to be used for frozen items.

@item Separate Window
Specifies whether the Data window should be a separate window.

@item 3D Look
Specifies whether the items should have a 3d look.

@item Item Name
Indicates font to be used for the name of the item.

@item Item Value
Indicates font to be used to display the value of the item.

@item Item Type
Indicates font to be used to display the type of the item.

@item Hide Big Items
@anchor{hiding big items}
Specifies whether items larger than a given size will start in a hidden state.

@item Big Item Height
Specifies that items taller than this value will start hidden.

@item Detect Aliased (shared data structures)
If enabled, do not create new items when an item with the same address is
already present on the canvas.

@item Display Grid Points
Specify whether the grid should be displayed in the canvas.

@item Auto-Align Displays on Nearest Grid Point
Specify whether items should be aligned on the grid.

@item Show Call Stack
@anchor{Show Call Stack}
If enabled, display the Call Stack window by default.
@end table

@item Command
Enables you to change the preferences of the @i{Debugger Console}, also
known as the @i{Command Window}.

@table @i
@item Color Highlighting
Sets the color used to highlight debugger commands and prompts.
@item Font
Sets the font name and size for the @i{Debugger Console}. Note that it
is recommended to use a fixed size font such as Courier to get a better
looking display.
@end table

@item Memory
Gives access to the preferences related to the memory view window.
The values are currently not taken into account.

@table @i
@item Font
Sets the font name and size to display the contents of the memory. It
is recommended that you use a fixed size font such as Courier to get a better
looking display.

@item Default Color
Indicates the color to be used by default in the memory view window.

@item Color Highlighting
Indicates the color to be used for highlighted items in the memory view.

@item Selection
Indicates the color to be used for selected items in the memory view.

@item Modified
Indicates the color to be used for modified items in the memory view.
@end table

@item Helpers
@anchor{helpers menu}
Helpers are external programs that are used by GVD to perform specific
actions.

@table @i
@item Edit Sources
This command specifies the program used by the @i{Edit Current Source} menu.
This specification uses two special arguments: 
@i{%f} which is replaced by the full path name to the current file,
and @i{%l} which is replaced by the current line number.
This specification is superseded by the environment variable
@code{GVD_EDITOR} if it exists (see also @ref{GVD_EDITOR}).
Try e.g using "xterm -e /bin/vi %f +%l" if you prefer vi.

On windows system, you need to use the following syntax to start a
batch script (@file{.bat} files):
@cindex example
@smallexample
  cmd /c script.bat %f
@end smallexample
In particular, you need to us this syntax if you want to start
glide.bat, as provided by ACT.

@item List Processes
This command generates a list of processes
suitable for process actions such as attach. Under Windows, a stand alone
executable called @code{winps} is provided to implement this capability.

Note that the format expected by GVD of this command is the process id
in the first column, and then additional information (displayed as is).

@item Remote Shell
Command to be used to establish a remote connection
(see @ref{Using GVD with a Remote Debugger}).
@item Remote Copy
Command to be used to copy files remotely
(see @ref{Using GVD with a Remote Debugger}).
@item HTML Browser
@anchor{HTML browser}
Command to be used to browse HTML files, in particular the HTML version of this
help file.

By default, GVD will reuse an existing netscape browser. You can force
the use of a new netscape by changing the "HTML browser" helper to
@cindex example
@smallexample
netscape -no-session-management
@end smallexample

@end table

@end table

@subsection Command

@table @b
   @item Command History
Opens a dialog with the list of commands executed in the current session.
You can select any number of items in this list and replay the selection
automatically.

   @item Clear Window
Clears the debugger console window. This removes the recording of interchanges
between GVD and the underlying debugger, and resets the scrollbar
accordingly.

@end table

@end ifclear
@c GPS

@subsection Data
@cindex menu
@cindex data
@noindent
Note that most items in this menu need to access the underlying debugger
when the process is stopped, not when it is running. This means that you first
need to stop the process on a breakpoint or interrupt it, before using
the following commands. Failing to do so will result in blank windows.

@table @b
   @item Call Stack
@cindex call stack
      Displays the Call Stack window.
      See @ref{The Call Stack Window} for more details.

   @item Threads
@cindex thread
      Opens a new window containing the list of threads currently present in
      the executable as reported by the underlying debugger. For each thread,
      it will give information such as internal identifier, name and status.
      This information is language- and debugger-dependent. You should refer to
      the underlying debugger's documentation for more details.
      As indicated above, the process being debugged needs to be stopped
      before using this command, otherwise a blank list will be displayed.

      When supported by the underlying debugger, clicking on a thread will
      change the context (variables, call stack, source file) displayed,
      allowing you to inspect the stack of the selected thread.

   @item Tasks
@cindex task
      For GDB only, this will open a new window containing the list of Ada
      tasks currently present in the executable. Similarly to the thread
      window, you can switch to a selected task context by clicking on it, if
      supported by GDB. See the GDB documentation for the list of
      items displayed for each task.

      As for the thread window, the process being debugged needs to be stopped
      before using this window.

@iftex
@cindex screen shot
@image{tasks, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{tasks}
@end ifhtml

   @item Protection Domains
@cindex protection domain
      For VxWorks AE only, this will open a new window containing the
      list of available protection domains in the target. To change to a
      different protection domain, simply click on it. A @c{*} character
      indicates the current protection domain.

@ifset GPS
   @item Assembly
@cindex assembly
      Opens a new window displaying an assembly dump of the current code
      being executed.
      See @ref{The Assembly Window} for more details.
@end ifset

   @item Edit Breakpoints
@cindex breakpoint
      Opens an advanced window to create and modify any kind of breakpoint
      (see @ref{The Breakpoint Editor}).
      For simple breakpoint creation, see the description of the source window.

   @item Examine Memory
@cindex memory view
      Opens a memory viewer/editor. See @ref{The Memory Window} for more
      details.

@ifset GPS
   @item Command History
@cindex command
@cindex history
      Opens a dialog with the list of commands executed in the current session.
      You can select any number of items in this list and replay the selection
      automatically.
@end ifset

   @item Display Local Variables
@cindex local variables
      Opens an item in the Data Window containing all the local variables
      for the current frame.

   @item Display Arguments
@cindex arguments
      Opens an item in the Data Window containing the arguments
      for the current frame.

   @item Display Registers
@cindex registers
      Opens an item in the Data Window containing the machine registers
      for the current frame.

   @item Display Any Expression...
@cindex display expression
      Opens a small dialog letting you specify an arbitrary expression
      in the Data Window. This expression can be a variable name, or a
      more complex expression, following the syntax of the underlying debugger.
      See the documentation of e.g gdb for more details on the syntax.
      The check button @i{Expression is a subprogram call} should be enabled
      if the expression is actually a debugger
      command (e.g @code{p/x var}) or a procedure call in the program being
      debugged (e.g @code{call my_proc}).

   @item Refresh
@cindex refresh
      Refreshes all the items displayed in the Data Window.
@end table

@ifclear GPS

@subsection Help
@table @b
   @item GVD Manual...
Opens this documentation in an HTML browser (as specified in the
@ref{HTML browser}).

   @item About...
Opens a simple information box about GVD.
@end table

@c --------------------------------------------------------------------
@node The Tool Bar
@section The Tool Bar
@c --------------------------------------------------------------------

@noindent
   The tool bar can be detached from the main window, using the left area:
   click on this left gray area, and move your mouse outside the window. The
   tool bar will be detached and its form will also change from a horizontal
   bar to a vertical bar with two columns.
   To move it back to the main window, double click on the left area.

@table @b
  @item Run
Executes the program using the arguments set previously (e.g on the command
line).
  @item Start
Same as @i{Run}, but stops at the beginning of the main subprogram.

  @item Step
Executes the program until it reaches a different source line.

  @item Stepi
Executes the program for one machine instruction only.

  @item Next
Executes the program until it reaches the next source line, stepping
over subroutine calls.

  @item Nexti
Executes the program until it reaches the next machine instruction, stepping
over subroutine calls.

  @item Finish
Continues execution until selected stack frame returns.

  @item Cont
Continues execution of the program being debugged.

  @item Up
Goes up one frame in the call stack.

  @item Down
Goes down one frame in the call stack.

  @item Interrupt
Asynchronously interrupts the program being debugged. Note that depending on
the state of the program, you may stop it in low level system code that does
not have debug information, or in some cases, not even a coherent state. Use
of breakpoints is in general preferable to interrupting programs.

@end table

@end ifclear
@c GPS

@c --------------------------------------------------------------------
@node The Call Stack Window
@section The Call Stack Window
@cindex call stack
@c --------------------------------------------------------------------

@noindent
   The call stack window gives a list of frames corresponding to the current
   execution stack for the current thread/task.

@iftex
@cindex screen shot
@image{call-stack, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{call-stack}
@end ifhtml

   The bottom frame corresponds to the outermost frame where the thread is
   currently stopped. This frame corresponds to the first function
   executed by the current thread (e.g main if the main thread is in C).
   You can click on any frame to switch to the caller's context, this will
   update the display in the source window. See also the up and down
   buttons in the tool bar to go up and down one frame in the call stack.

@cindex contextual menu
   The contextual menu (right mouse button) allows you to choose which
   information you want to display in the call stack window (via check buttons):
   @itemize @bullet
      @item Frame number: the debugger frame number (usually starts at 0 or 1)
      @item Program Counter: the low level address corresponding to the
            function's entry point.
      @item Subprogram Name: the name of the subprogram in a given frame
      @item Parameters: the parameters of the subprogram
      @item File Location: the filename and line number information.
   @end itemize

   By default, only the subprogram name is displayed.
   You can hide the call stack window by closing it, as for other windows, and
   show it again using the menu @code{Data->Call Stack}.

@c --------------------------------------------------------------------
@node The Data Window
@section The Data Window
@cindex data
@cindex data window
@c --------------------------------------------------------------------

@c --------------------------------------------------------------------
@subsection Description
@c --------------------------------------------------------------------

@noindent
@cindex menu
@cindex contextual menu
   The data window contains all the graphic boxes that can be accessed
   using the @i{Data->Display} menu items, or the data window
   @i{Display Expression...} contextual menu, or the source window
   @i{Display} contextual menu items, or finally the
   @i{graph} command in the debugger console.

   For each of these commands, a box is displayed in the data window
   with the following information:

@iftex
@cindex screen shot
@image{canvas, 9.8cm}
@end iftex

@ifhtml
@cindex screen shot
@image{canvas}
@end ifhtml

   @itemize @bullet
   @item A title bar containing:
@cindex title bar
     @itemize @bullet
     @item The number of this expression: this is a positive number starting
       from 1 and incremented for each new box displayed. It represents the
       internal identifier of the box.

     @item The name of the expression: this is the expression or variable
       specified when creating the box.

     @item An icon representing either a flash light, or a lock.
@cindex icon
       This is a click-able icon that will change the state of the box from
       automatically updated (the flash light icon) to frozen (the lock
       icon).
       When frozen, the value is grayed, and will not change until you change
       the state. When updated, the value of the box will be recomputed each
       time an execution command is sent to the debugger (e.g step, next).

     @item An icon representing an 'X'.
@cindex icon
       You can click on this icon to close/delete any box.
     @end itemize

   @item A main area.
     The main area will display the data value hierarchically
     in a language-sensitive manner. The canvas knows about data structures
     of various languages (e.g @code{C}, @code{Ada}, @code{C++}) and will
     organize them accordingly.
     For example, each field of a record/struct/class, or each item of an
     array will be displayed separately. For each subcomponent, a thin box
     is displayed to distinguish it from the other components.
   @end itemize

@cindex contextual menu
   A contextual menu, that takes into account the current component selected
   by the mouse, gives access to the following capabilities:
   @table @b
     @item Close @i{component}
Closes the selected item.

     @item Hide all @i{component}
@cindex hide
Hides all subcomponents of the selected item. To select a particular field
or item in a record/array, move your mouse over the name of this
component, not over the box containing the values for this item.

     @item Show all @i{component}
@cindex show
Shows all subcomponents of the selected item.

     @item Clone @i{component}
@cindex clone
Clones the selected component into a new, independent item.

     @item View memory at address of @i{component}
@cindex memory view
Brings up the memory view dialog and explore memory at the address of the 
component.

     @item Set value of @i{component}
Sets the value of a selected component. This will open an entry box
where you can enter the new value of a variable/component. Note that
GDB does not perform any type or range checking on the value entered.

     @item Update Value
@cindex update value
Refreshes the value displayed in the selected item.

     @item Show Value
@cindex show value
Shows only the value of the item.

     @item Show Type
@cindex show type
Shows only the type of each field for the item.

     @item Show Value+Type
Shows both the value and the type of the item.

@c ??? Should have screen shot with value + type

     @item Auto refresh
@cindex auto refresh
Enables or disables the automatic refreshing of the item upon program execution
(e.g step, next).

   @end table

@cindex contextual menu
   A contextual menu can be accessed in the canvas itself (point the mouse to
   an empty area in the canvas, and click on the right mouse button) with the
   following entries:
   @table @b
     @item Display Expression...
@cindex display expression
      Open a small dialog letting you specify an arbitrary expression
      in the Data Window. This expression can be a variable name, or a
      more complex expression, following the syntax of the current language and
      underlying debugger.
      See the documentation of e.g gdb for more details on the syntax.
      The check button @i{Expression is a subprogram call} should be enabled
      if the expression is actually not an expression but rather a debugger
      command (e.g @code{p/x var}) or a procedure call in the program being
      debugged (e.g @code{call my_proc}).

     @item Align On Grid
@cindex align
Enables or disables alignment of items on the grid.

     @item Detect Aliases
@cindex aliases
Enables or disables the automatic detection of shared data structures.
Each time you display an item or dereference a pointer, all
the items already displayed on the canvas are considered and their addresses
are compared with the address of the new item to display. If they match,
(for example if you tried to dereference a pointer to an object already
displayed) instead of creating a new item a link will be displayed.

     @item Zoom in
@cindex zoom in
Redisplays the items in the data window with a bigger font

     @item Zoom out
@cindex zoom out
Displays the items in the data window with smaller fonts and pixmaps. This
can be used when you have several items in the window and you can't see all
of them at the same time (for instance if you are displaying a tree and
want to clearly see its structure).

     @item Zoom
@cindex zoom
Allows you to choose the zoom level directly from a menu.

   @end table

@c --------------------------------------------------------------------
@subsection Manipulating items
@c --------------------------------------------------------------------

@subsubsection Moving items
@noindent
All the items on the canvas have some common behavior and can be fully
manipulated with the mouse.
They can be moved freely anywhere on the canvas, simply by clicking on
them and then dragging the mouse. Note that if you are trying to move
an item outside of the visible area of the data window, the latter will
be scrolled so as to make the new position visible.

Automatic scrolling is also provided if you move the mouse while dragging
an item near the borders of the data window. As long as the mouse
remains close to the border and the button is pressed on the item,
the data window is scrolled and the item is moved. This provides an
easy way to move an item a long distance from its initial position.

@subsubsection Colors
@noindent
Most of the items are displayed using several colors, each
conveying a special meaning. Here is the meaning assigned to all colors
(note that the exact color can be changed through the preferences
dialog; these are the default colors):

@iftex
@cindex screen shot
@image{colors, 10cm}
@end iftex

@ifhtml
@cindex screen shot
@image{colors}
@end ifhtml

@table @b

@item black
This is the default color used to print the value of variables or
expressions.

@item blue
@cindex C
@cindex Ada
This color is used for C pointers (or Ada access values), i.e. all the variables
and fields that are memory addresses that denote some other value in
memory.

You can easily dereference these (that is to say see the value pointed to)
by double-clicking on the blue text itself.

@item red
This color is used for variables and fields whose value has changed since
the data window was last displayed. For instance, if you display an array
in the data window and then select the @i{Next} button in the tool bar, then
the elements of the array whose value has just changed will appear in red.

@cindex menu
As another example, if you choose to display the value of local variables in
the data window (@i{Display->Display Local Variables}), then only the
variables whose value has changed are highlighted, the others are left in
black.

@end table

@subsubsection Icons
@cindex icon
@noindent
Several different icons can be used in the display of items. They also
convey special meanings.

@table @b

@item trash bin icon
This icon indicates that the debugger could not get the value of the
variable or expression. There might be several reasons, for instance the
variable is currently not in scope (and thus does not exist), or it might
have been optimized away by the compiler. In all cases, the display will be
updated as soon as the variable becomes visible again.

@item package icon
This icon indicates that part of a complex structure is currently hidden.
Manipulating huge items in the data window (for instance if the variable
is an array of hundreds of complex elements) might not be very helpful. As a
result, you can shrink part of the value to save some screen space and make it
easier to visualize the interesting parts of these variables.

Double-clicking on this icon will expand the hidden part, and clicking on
any sub-rectangle in the display of the variable will hide that part and
replace it with that icon.

See also the description of the contextual menu to automatically show or hide
all the contents of an item. Note also that one alternative to hiding
subcomponents is to clone them in a separate item (see the contextual menu
again).

@end table

@c --------------------------------------------------------------------
@node The Breakpoint Editor
@section The Breakpoint Editor
@cindex breakpoint editor
@cindex breakpoint
@c --------------------------------------------------------------------

@iftex
@cindex screen shot
@image{breakpoints, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{breakpoints}
@end ifhtml

@noindent
@cindex menu
The breakpoint editor can be accessed from the menu
@i{Data->Edit Breakpoints}. It gives access to the different kind of
breakpoints: on source location, subprogram, address, variables, exceptions.

The top area provides an interface to easily create the different kinds of
breakpoints, while the bottom area lists the existing breakpoints and
their characteristics.

It is possible to access to advanced breakpoint characteristics by clicking
on the @i{Advanced} button, which will display a new area on the right of the
window, where you can specify commands to run automatically after a breakpoint
is hit, or specify how many times a selected breakpoint will be ignored.
If running VxWorks AE, you can also change the Scope and Action
of breakpoints.

@subsection Scope/Action Settings for VxWorks AE
@cindex VxWorks AE

@noindent
In VxWorks AE breakpoints have two extra properties:

@itemize @bullet
@item Scope:
@cindex scope
 which task(s) can hit a given breakpoint. Possible Scope values are:
 @itemize @minus
  @item task:
@cindex task
   the breakpoint can only be hit by the task that was active when the
   breakpoint was set. If the breakpoint is set before the program is
   run, the breakpoint will affect the environment task
  @item pd:
@cindex protection domain
   any task in the current protection domain can hit that breakpoint
  @item any:
   any task in any protection domain can hit that breakpoint. This
   setting is only allowed for tasks in the Kernel domain.

 @end itemize

@item Action:
@cindex action
 when a task hits a breakpoints, which tasks are stopped:
 @itemize @minus
  @item task:
@cindex task
   stop only the task that hit the breakpoint.
  @item pd:
@cindex protection domain
   stop all tasks in the current protection domain
  @item all:
   stop all breakable tasks in the system

 @end itemize
@end itemize

These two properties can be set/changed through the advanced breakpoints
characteristics by clicking on the @i{Advanced} button. There are two
ways of setting these properties:

@itemize @bullet

@item Per breakpoint settings:
 after setting a breakpoint (the default Scope/Action values will be
 task/task), select the @i{Scope/Action} tab in the @i{Advanced} settings.
 To change these settings on a given breakpoint, select it from
 the breakpoints list, select the desired values of Scope and Action and click
 on the @i{Update} button.

@item Default session settings:
 select the @i{Scope/Action} tab in the
 @i{Advanced} settings. Select the desired Scope and Action settings, check
 the @i{Set as session defaults} check box below and click the @i{Close}
 button. From now on, every new breakpoint will have the selected values
 for Scope and Action.

@end itemize

@c --------------------------------------------------------------------
@node The Memory Window
@section The Memory Window
@cindex memory view
@c --------------------------------------------------------------------

@iftex
@cindex screen shot
@image{memory-view, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{memory-view}
@end ifhtml

@noindent
The memory window allows you to display the contents of memory by
specifying either an address, or a variable name.

@cindex C
@cindex hexadecimal
To display memory contents, enter the address using the C hexadecimal notation:
0xabcd, or the name of a variable, e.g foo, in the @i{Location} text entry.
In the latter case, its address is computed automatically. Then either press
@i{Enter} or click on the @i{View} button. This will display the memory with
the corresponding addresses in the bottom text area.

@cindex ASCII
You can also specify the unit size (@i{Byte}, @i{Halfword} or @i{Word}),
the format (@i{Hexadecimal}, @i{Decimal}, @i{Octal} or @i{ASCII}), and you
can display the corresponding ASCII value at the same time.

@cindex key
The @i{up} and @i{down} arrows as well as the @key{Page up} and @key{Page down}
keys in the memory text area allows you to walk through the memory in
order of ascending/descending addresses respectively.

Finally, you can modify a memory area by simply clicking on the location
you want to modify, and by entering the new values. Modified values will
appear in a different color (red by default) and will only be taken into
account (i.e written to the target) when you click on the @i{Submit changes}
button. Clicking on the @i{Undo changes} or going up/down in the memory
will undo your editing.

Clicking on @i{Close} will close the memory window, canceling your last
pending changes, if any.

@ifclear GPS

@c --------------------------------------------------------------------
@node The Explorer Window
@section The Explorer Window
@c --------------------------------------------------------------------

@noindent
@iftex
@cindex screen shot
@image{explorer, 6cm}
@end iftex

@ifhtml
@cindex screen shot
@image{explorer}
@end ifhtml

The explorer window provides  fast access to the files contained in the
module you want to debug (and that have been compiled with debug information).
Note that you can have multiple entries with the same file name if there
are identical file names in different places (which can be either
different files, e.g @code{/usr/include/signal.h} and
@code{/usr/include/sys/signal.h}, or identical files reached through different
source paths).

Each file can be opened (by clicking on the @code{+} icon on the left of
the file name, or double clicking on the file name, giving access to
language sensitive information such as packages, functions, tasks, etc...
You can then open each of these sections and by selecting an item,
the source editor will select and jump to this item.

Note: some items are disabled until an executable is loaded by means of the
Open Program, the Open Core Dump, or the Attach Process menu, or by means of
the corresponding commands in the debugger console.

   Contextual menu:
   @table @b
     @item Hide System Files
Hides the files that are part of the system.
This currently only affects Ada programs compiled with GNAT, and will hide the
GNAT run-time files used by the executable.

     @item Reload Files
Recomputes the list of files. this is particularly useful when the program
uses shared libraries that are not known until the program references
them.

     @item Delete Files Not Found
Deletes the files that cannot be found on the file system. Note that this
operation can take a long time to complete.

     @item Show Current File
Highlights the file containing the current execution point.
   @end table

@c --------------------------------------------------------------------
@node The Source Window
@section The Source Window
@c --------------------------------------------------------------------

@noindent
   The source window is composed of two main areas. The first is a small
   column on the left containing the following information:

@end ifclear
@c GPS

@ifset GPS
@c --------------------------------------------------------------------
@node Using the Source Editor when Debugging
@section Using the Source Editor when Debugging
@cindex source file
@cindex editing
@cindex debug
@c --------------------------------------------------------------------

@noindent
   When debugging, the left area of each source editor provides the
   following information:
@end ifset

   @table @b
     @item Lines with code
In this area, blue dots are present next to lines for which the debugger
has debug information, in other words, lines that have been compiled with
debug information and for which the compiler has generated some code.
Currently, there is no check when you try to set a breakpoint on a non dotted
line: this will simply send the breakpoint command to the underlying
debugger, and usually (e.g in the case of gdb) result in setting a
breakpoint at the closest location that matches the file and line that you
specified.
     @item Current line executed
@cindex current line
This is a green arrow showing the line about to be executed.

     @item Lines with breakpoints
@cindex breakpoint
For lines where breakpoints have been set, a red mark is displayed on top
of the blue dot for the line. You can add and delete
breakpoints by clicking on this area (the first click will set a breakpoint,
the second click will remove it).
   @end table

@iftex
@cindex screen shot
@image{tooltips, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{tooltips}
@end ifhtml

@cindex syntax highlighting
@cindex tooltip
   The second area in the source window is a text window on the right that
   displays the source files, with syntax highlighting.
   If you leave the cursor over a variable, a tooltip will
   appear showing the value of this variable. Automatic tooltips can be
   disabled in the preferences menu.
@cindex preferences
   See @ref{preferences dialog}.

@ifclear GPS
   The contextual menu of the source window contains the following entries.
@end ifclear

@ifset GPS
@cindex contextual menu
   When the debugger is active, the contextual menu of the source window
   contains a sub menu called @code{Debug} providing the following entries.
@end ifset

Note that these entries are dynamic: they will apply to the entity
found under the cursor when the menu is displayed (depending on the current
language). In addition, if a selection has been made in the source window the
text of the selection will be used instead. This allows you to display
more complex expressions easily (for example by adding some comments to your
code with the complex expressions you want to be able to display in the
debugger).

   @table @b
     @item Print @i{selection}
@cindex print
Prints the selection (or by default the name under the cursor) in the
debugger console.

     @item Display @i{selection}
@cindex display
Displays the selection (or by default the name under the cursor) in the
data window. The value will be automatically refreshed each time the process
state changes (e.g after a step or a next command). To freeze the display
in the canvas, you can either click on the corresponding icon in the data
window, or use the contextual menu for the specific item (see
@ref{The Data Window} for more information).

     @item Print @i{selection}.all
Dereferences the selection (or by default the name under the cursor) and
prints the value in the debugger console.

     @item Display @i{selection}.all
Dereferences the selection (or by default the name under the cursor) and
displays the value in the data window.

     @item View memory at address of @i{selection}
@cindex memory view
Brings up the memory view dialog and explores memory at the address of the 
selection.

     @item Set Breakpoint on Line @i{xx}
@cindex breakpoint
Sets a breakpoint on the line under the cursor, in the current file.

     @item Set Breakpoint on @i{selection}
Sets a breakpoint at the beginning of the subprogram named @i{selection}

     @item Continue Until Line @i{xx}
@cindex continue until
Continues execution (the program must have been started previously) until 
it reaches the specified line.

     @item Show Current Location
@cindex current location
Jumps to the current line of execution. This is particularly useful after
navigating through your source code.

@ifclear GPS

     @item Display Line Numbers
Enables or disable the display of line numbers on the left of the source
editor.

     @item Show Lines with Code
Enables or disables the display of lines with code, as described above.

     @item Show...
A sub menu composed of the following options:
     @table @b
        @item Source Code
Shows only the source code.

        @item Asm Code
Shows only the assembly code around the current execution point.
See @ref{The Assembly Window} for more details.

        @item Asm and Source
Shows both the source code and the assembly window at the same time.
     @end table

@end ifclear
@c GPS

   @end table

@c --------------------------------------------------------------------
@node The Assembly Window
@section The Assembly Window
@c --------------------------------------------------------------------

It is sometimes convenient to look at the assembly code for the subprogram
or source line you are currently debugging.

@ifclear GPS
You can access the assembly window by right-clicking in the source
window, and selecting one of the menus "Show Asm Code" or "Show Asm and
Source", the later will allow you to see both the source code and the
matching assembly code.
@end ifclear

@ifset GPS
You can open the assembly window by using the menu @code{Debug->Data->Assembly}.
@end ifset

@iftex
@cindex screen shot
@image{assembly, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{assembly}
@end ifhtml

The current assembly instruction is highlighted with a green
arrow on its left.  The instructions corresponding to the current source
line are highlighted in red by default. This allows you to easily see
where the program counter will point to, once you have pressed the "Next"
button on the tool bar.

Moving to the next assembly instruction is done through the "Nexti"
(next instruction) button in the tool bar. If you choose "Stepi"
instead (step instruction), this will also jump to the subprogram
being called.

For efficiency reasons, only a small part of the assembly code around the
current instruction is displayed.
You can specify in the @ref{preferences dialog} how many instructions
are displayed by default. Also, you can easily
display the instructions immediately preceding or following the
currently displayed instructions by pressing one of the @key{Page up} or
@key{Page down} keys, or by using the contextual menu in the assembly
window.

A convenient complement when debugging at the assembly level is the
ability of displaying the contents  of machine registers.
When the debugger supports it (as gdb does), you can select the
@code{Data->Display Registers} menu to get an item in the canvas that will
show the current contents of each machine register, and that will be updated
every time one of them changes.

You might also choose to look at a single register.
With gdb, select the @code{Data->Display Any Expression}, entering
something like

@cindex example
@smallexample
output /x $eax
@end smallexample

in the field, and selecting the toggle button "Expression is a subprogram
call". This will create a new canvas item that will be refreshed every
time the value of the register (in this case eax) changes.

@c --------------------------------------------------------------------
@node The Debugger Console
@section The Debugger Console
@cindex debugger
@cindex debugger console
@c --------------------------------------------------------------------

@noindent
This is the text window located at the bottom of the main window.
In this console, you have direct access to the underlying debugger,
and can send commands (you need to refer to the underlying debugger's
documentation, but usually typing @i{help} will give you an overview of
the commands available).

If the underlying debugger allows it, pressing @key{Tab} in this 
window will provide completion for the command that is being typed (or for
its arguments).

There are also additional commands defined to provide a simple
text interface to some graphical features.

@ifclear GPS

These commands, as documented below, enable you to create scripts that
automatically change the graphical
aspect of GVD. They also permit, through the use of the @code{--tty} command
line option, a better integration of GVD into other integrated environments
and editors like GNU Emacs.

@end ifclear
@c GPS

Here is the complete list of such commands. The arguments between square
brackets are optional and can be omitted.

@table @command
@item graph (print|display) expression [dependent on display_num] [link_name name]
@cindex graph print
@cindex graph display
This command creates a new item in the canvas, that shows the value of
@var{Expression}. @var{Expression} should be the name of a variable, or one
of its fields, that is in the current scope for the debugger.

The command @code{graph print} will create a frozen item, that is not
automatically refreshed when the debugger stops, whereas @code{graph display}
displays an automatically refreshed item.

The new item is associated with a number, that is visible in its title bar.
These numbers can be used to create links between the items, using the
second argument to the command, @var{dependent on}. The link itself (i.e. the
line) can be given a name that is automatically displayed, using the third
argument.

@item graph (print|display) `command`
This command is similar to the one above, except it should be used to
display the result of a debugger command in the canvas.

For instance, if you want to display the value of a variable in hexadecimal
rather than the default decimal with gdb, you should use a command like:

@cindex example
@smallexample
graph display `print /x my_variable`
@end smallexample

This will evaluate the command between back-quotes every time the debugger
stops, and display this in the canvas. The lines that have changed will
be automatically highlighted (in red by default).

This command is the one used by default to display the value of registers
for instance.

@item graph (enable|disable) display display_num [display_num ...]
@cindex graph enable
@cindex graph disable
This command will change the refresh status of items in the canvas. As
explained above, items are associated with a number visible in their title
bar.

Using the @code{graph enable} command will force the item to be automatically
refreshed every time the debugger stops, whereas the @code{graph disable}
command will freeze the item.

@item graph undisplay display_num
@cindex graph undisplay
This command will remove an item from the canvas

@item view (source|asm|source_asm)
@cindex view
@cindex asm
This command indicates what should be displayed in the source window.
The first option indicates that only the source code should be visible,
the second one specifies that only the assembly code should be visible,
and the last one indicates that both should be displayed.

@end table

@ifclear GPS

@c --------------------------------------------------------------------
@node The Status Line
@section The Status Line
@c --------------------------------------------------------------------

@noindent
This is the line located at the bottom of the main window. This area
will contain information about events, and errors such as parsing errors.
After a time out (that can be changed in the preferences menu), each
message disappears and is added to the history of messages that can be
accessed using the arrow located at the left of the status line.

@c --------------------------------------------------------------------
@node Integrating GVD
@chapter Integrating GVD
@c --------------------------------------------------------------------

@menu
* General Information::
* Using GVD with Glide::
* Using GVD with Emacs::
* Using GVD with XEmacs::
* Using GVD as a Library::
* Using GVD as a Corba Object::
@end menu

@noindent
@node General Information
@section General Information
     To have GVD run as an inferior in other front ends, you can either set up
     your debugger front end such that @i{gvd --tty} is invoked instead of
     the inferior debugger, or use GVD as a library.
     When GVD is invoked using the @i{--tty} option, it enables its TTY
     interface, taking additional debugger commands from standard input and
     forwarding debugger output to standard output, just as if the inferior
     debugger had been invoked directly. All remaining GVD functionalities stay
     unchanged. Note that the @i{--tty} option is currently not supported
     on Windows systems.

     The @i{--tty} option also implies the GDB @i{-fullname} option, when
     GDB is used as the underlying debugger.

     You may also invoke @i{gvd --tty} directly, entering GVD commands from
     your TTY, or use GVD as the end of a pipe, controlled by a remote program.
     Be aware, however, that the TTY interface does not support line editing and
     command completion. Also, do not try to run GVD with GVD as inferior
     debugger.

@node Using GVD with Glide
@section Using GVD with Glide
     Select @i{Ada->Project->Edit Current}, go in the @i{[Ada Menu]}
     section, in the @i{Debugging the application:} field, enter
     @i{gvd --tty $@{main@}}.
     Save. Then launch the debugging session by using the menu
     @i{Ada->Debug}.
     In the source window, you can display variables graphically using the
     contextual menu on top of a variable, or after selecting an expression.
     The display will be done in GVD's canvas window.

     If you activate the option in the menu @i{Ada->Options->Tight Integration
     with GVD}, then a new frame from Emacs will be swallowed directly in
     the GVD window (This is currently specific to Unix systems). This means
     that the source window of GVD will be completely replaced by the Glide
     window, and thus will be a full editor. It also provides cross-references,
     which might help you debug your code.

     If you are not using project files with Glide, you might want to
     use the following lisp function to automatically start gvd on your
     executable, with Glide used as the source editor. Just copy the following
     code to your @file{~/.emacs} configuration file (create it if it doesn't
     exist).

@cindex example
@smallexample
   (auto-load 'ada-gdb-application "ada-mode" "" t)
   (defun gvd (executable-name)
     "Start gvd on EXECUTABLE-NAME, with emacs as the source window."
     (interactive "FExecutable: ")
     (let ((ada-tight-gvd-integration t)
	   (ada-prj-default-debugger  "gvd"))
       (ada-gdb-application nil executable-name)))
@end smallexample

@node Using GVD with Emacs
@section Using GVD with Emacs
     Use @i{M-x gdb} to start a debugging session. At the prompt, enter
     @i{gvd --tty} and the name of the program to be debugged. Process as
     usual.

     A file @file{gvd.el} is provided with the GVD binaries and in the
     @file{distrib/} directory of the GVD sources.
     This file provides a function called @code{gvd},
     that can be used just like the standard @code{gdb} command, but that
     adds some special arguments to the command line so that an Emacs frame
     is automatically swallowed inside GVD and used as the source editor (see
     description in @ref{Using GVD with Glide}).

     Simply load that file in Emacs, with a command like
@cindex example
@smallexample
  (load "/complete/path/gvd.el")
@end smallexample
     in your @file{.emacs} configuration file, and then use the command
     @key{M-x gvd} to launch GVD.

@node Using GVD with XEmacs
@section Using GVD with XEmacs
     In XEmacs 21 and later, select @i{Tools->Debug (GDB)}. At the prompt,
     enter @i{gvd --tty} and the name of the program to be debugged.
     Proceed as usual.

@node Using GVD as a Library
@section Using GVD as a Library
     GVD can also be used as a library. Note that this is still work in
     progress. The interface provided by GVD to other programs can
     be found in the file @file{gvd-api.ads}, and @file{gvd-api.h}.
     Note that to integrate GVD code in Ada applications, the recommended
     way is to use the various high-level packages provided by GVD directly.
     The @file{gvd-api.ads} file is provided mainly for integrating GVD with other
     languages. This API is provided as a C API, so that any language that can
     interface with C can use it. For more information, refer directly to
     the @file{gvd-api.ads} file.

@node Using GVD as a Corba Object
@section Using GVD as a Corba Object
     Future development plans of GVD include transforming GVD into a Corba
     object, so that it can be used easily by other applications in any
     language, and in particular in the context of the GNOME framework.

@c --------------------------------------------------------------------
@node Debugging a program remotely
@chapter Debugging a program remotely
@c --------------------------------------------------------------------

@menu
* Using GVD with a Remote Debugger::
* Using GVD with a Remote Program::
@end menu

@noindent
It is possible to have the inferior debugger run on a remote host. This is
useful when the remote host has a slow network connection or when GVD is
available on the local host only.

Furthermore, the inferior debugger may support debugging a program on a remote
host. This is useful when the inferior debugger is not available on the remote
host - for instance, because the remote system does not have a general-purpose
operating system powerful enough to run a full featured debugger. When
developing in a cross environment (e.g VxWorks, Lynx OS), you will be in such
situation.

@node Using GVD with a Remote Debugger
@section Using GVD with a Remote Debugger
To debug a program running on a remote machine you have two main options:
either run GVD on the remote machine, using the remote capabilities of the X
windowing system;
or run GVD on the host machine, and run the underlying debugger on the remote
machine.

For the first option,  you must open a shell on the remote machine (using e.g
telnet or rlogin), set the DISPLAY environment variable to the
value of your local display, and launch gvd from your remote machine.
For example, assuming your local machine is called @i{local}, and your display
is the default display @i{local:0}, your remote machine is called @i{remote}.
you can do the following (assuming you are using an sh-like shell):

@cindex example
@smallexample
$ rlogin remote
$ DISPLAY=local:0
$ export DISPLAY
$ gvd
@end smallexample

You also need to ensure that @i{remote} is allowed to access @i{local:0} by
e.g using the xhost utility on Unix.

For the second option, gvd will internally use the standard @i{rsh} and
@i{rcp} utilities. These are standard tools available on all Unix systems and
on Windows NT/2000 as well.

First make sure that rsh/rcp can be used from your local to your remote machine
without having to enter a password. This is usually done via the configuration
of a @i{.rhosts} file in your remote home directory that will typically look
like:

@cindex example
@smallexample
local user-name
@end smallexample

local is the name of the local machine you want to rlogin from, and the .rhosts
file needs to be present in the home directory on the remote machine.

To check whether you can use gvd in remote mode, try the following, using a
shell window on your local machine:

@cindex example
@smallexample
$ rsh remote gdb
@end smallexample

This should launch gdb on the remote machine.

Note that on some systems, rsh is called differently. In particular under
HPUX, the remote shell capability is called remsh. For those systems, and
also in order to use other remote utilities such as ssh/scp, you can change
the default remote shell and copy by using the @ref{helpers menu}.

After ensuring that you have the proper setup in place, to run the debugger on
a remote host @i{remote}, either invoke GVD as

@cindex example
@smallexample
gvd --host 'remote' remote-program
@end smallexample

or use the @i{File->New Debugger...} menu in GVD.

If you need to use a different username on the remote host, you can 
replace @i{remote} by @i{user@@remote} where @i{user} is the username on the
remote machine, and @i{remote} is the remote machine, as previousely explained.
To verify that this is supported by your version of @i{rsh}, try the
following:

@cindex example
@smallexample
$ rsh user@@remote gdb
@end smallexample

If this does not work, you can create a simple script that transforms
@i{user@@remote} into the proper syntax, e.g. @i{remote -l user} and
specify this script as the default remote shell and copy programs.

There are a few caveats to be aware of in remote mode:

  The remote debugger is started in your remote home directory. Hence, you must
  specify an absolute path name for @i{remote-program} (or a path name relative
  to your remote home directory). The same applies to remote core files.
  Also, be sure to specify a remote process id when debugging a running program.

  To access files remotely, GVD will first try to read the files locally,
  assuming that you have the remote files mounted locally at the same
  location (using e.g NFS+symbolic links, or Samba). If GVD it cannot find the
  files locally, it will then try to copy the files from the remote machine,
  using rcp. As for rsh, you need to make sure that rcp can be called without
  having to enter a password, and you can also replace rcp by similar remote
  copy utilities such as scp. Note that the file
  selection dialogs (change directory, open file, @dots{}) will scan the local
  directory, so you will need to know in advance the complete path if your
  remote files are not mounted on your local host.

@node Using GVD with a Remote Program
@section Using GVD with a Remote Program

  The GDB debugger allows you to run the @i{debugger program} on a remote
  machine (called @i{program host}) while GDB runs on the local machine.

  The section @i{Remote debugging} in the GDB documentation contains all the
  details. Basically, the following steps are required:

  Transfer the executable to the remote target.

  Optionally start gdbserver on the remote target (e.g on Lynx OS). This
    is not needed for environments such as VxWorks.

  Start GVD using a properly configured cross GDB, e.g powerpc-wrs-vxworks-gdb
  for a GDB configured for VxWorks PowerPC and specify the name of the remote
  target, as well as the protocol used to communicate with it. To specify
  the cross-GDB and the remote target, you can use either the --debugger and
  --target command line options, e.g:

@cindex example
@smallexample
gvd --debugger powerpc-wrs-vxworks-gdb --target my_target:wtx
@end smallexample

  or using the @i{Debugger Name}, @i{Program Host} and @i{Protocol} entries in
  the @i{File->New Debugger} menu item.

@iftex
@cindex screen shot
@image{process, 12.7cm}
@end iftex

@ifhtml
@cindex screen shot
@image{process}
@end ifhtml

You can also combine GVD remote mode and GDB remote mode, running
GVD, GDB and the debugged program each on a different machine.

@c --------------------------------------------------------------------
@node Environment
@chapter Environment
@c --------------------------------------------------------------------

@menu
* Command Line Options::
* Environment Variables::
* Files::
* Limitations::
* Reporting bugs::
@end menu

@node Command Line Options
@section Command Line Options

@cindex example
@smallexample
Usage:
   gvd [options...] executable-file
       [--dargs [debugger options]] [--pargs [program options]]
@end smallexample

@noindent
The options recognized by GVD are:

@table @b
@item --debugger DEBUG
use DEBUG as the underlying debugger.

@item --jdb
assume a Java debugger. This option is currently not fully supported.

@item --host HOST
Run inferior debugger on HOST. See
@ref{Using GVD with a Remote Debugger} for more information.

@item --target TARG:PRO
Load program on machine TARG using protocol PRO.
Note that TARG can contain the @code{:} character for e.g specifying the
port number. The last colon will be used by GVD as the separator between
the target and the protocol. For instance, assuming you want to connect
to a board named @i{bare} on port 1234 using the @i{remote} protocol, you
would specify:

@cindex example
@smallexample
gvd --target bare:1234:remote
@end smallexample

See @ref{Using GVD with a Remote Program} for more information.

@item --log-level [0-4]
Set level of logging (Default is 3).
This option can be useful when reporting bugs in GVD, in which case the
maximum level of logs (4) gives more details, but will also generate
more disk activity, which can slow down GVD significantly if the
log file is located through a network disk.

@item --editor-window=xid
Use xid as the editor X window id.
GVD takes advantage of this option by integrating the specified window
as the source editor.
This option is not currently supported on Windows.
Note that the best way to use this option is directly through Glide or Emacs,
as explained in @ref{Using GVD with Glide}. Glide will automatically pass the
correct xid value.

@item --tty
Use controlling tty as the debugger console.
This option is very useful for integrating GVD in other debugger front ends
(e.g Emacs), since in this mode, GVD appears as the underlying debugger to
the caller. See @ref{Integrating GVD} for more details.
This option is not currently supported on Windows.

@item --version
Show the GVD version and exit.

@end table

@noindent
The @code{--dargs} section let you specify an arbitrary number of options
to pass to the underlying debugger.

@noindent
Similarly, the @code{--pargs} section let you specify options to pass to the
debugged program.

@noindent
For example, if you want to pass the @code{--nx} option to GDB, and the
options @code{--file foo --version} to the debugged program @code{my_code}
you would launch GVD as follows:

@cindex example
@smallexample
gvd my_code --dargs --nx --pargs --file foo --version
@end smallexample

@c --------------------------------------------------------------------
@node Environment Variables
@section Environment Variables
@c --------------------------------------------------------------------

@noindent
The following environment variables can be set to override some default
settings in GVD:

@table @samp
   @item GVD_ROOT.
Override the default root directory specified when GVD
is built (during the @i{configure} process, see the file @code{INSTALL} in
the GVD sources for more details) to access information such as the location
of the translation files.

   @item GVD_HOME.
Override the variable HOME if present. All the configuration files and
directories used by GVD are either relative to $HOME/.gvd (%HOME%\.gvd under
Windows) if GVD_HOME is not set, or to $GVD_HOME/.gvd (respectively
%GVD_HOME%\.gvd) if set.

   @item GVD_EDITOR.
@anchor{GVD_EDITOR}
Override the default editor as found in the @ref{helpers menu}.

@end table

@c --------------------------------------------------------------------
@node Files
@section Files
@c --------------------------------------------------------------------

@noindent

@table @file
   @item $HOME/.gvd
GVD state directory
   @item $HOME/.gvd/log
@anchor{log file}
Log file created automatically by GVD. This log file contains all the input
and output exchanged between GVD and the underlying debugger. You can
specify the level of logs (from no log to very verbose) by using the
@code{--log-level} command line option. Using a high level of log can be
useful to track communication problems between GVD and the underlying debugger,
but will slow down GVD if $HOME is located on a network disk.

   @item $HOME/.gvd/preferences
Contains all the preferences in XML format, as specified in the
@ref{preferences dialog}.

   @item $HOME/.gvd/window_settings
Contains all the settings of the windows (window sizes, pane
offset) in XML format. These settings are saved automatically when quitting
GVD, and loaded automatically at start up. To reset the settings, simply
remove this file.

   @item $HOME/.gvd/sessions
Directory containing the GVD sessions.

   @item $HOME/.gvd/sessions/@i{session}
Each file in the @code{sessions} directory represents a particular session
saved by the user.

   @item $HOME/.gdbinit   GDB initialization file
@end table

@c --------------------------------------------------------------------
@node Limitations
@section Limitations
@c --------------------------------------------------------------------

@menu
* General Limitations::
* Limitations using GDB::
@end menu

@noindent
@node General Limitations
@subsection General Limitations
@noindent
     If command output is sent to the debugger console, it is impossible for GVD     to distinguish between the output of the debugged program and the output
     of the inferior debugger. This problem can be avoided by launching the
     program separately and then attaching it in GVD.

     Output that confuses GVD includes:

     @itemize @bullet
       @item Primary debugger prompts (e.g '(gdb) ')
       @item Secondary debugger prompts (e.g '>')
       @item Confirmation prompts (e.g '(y or n)')
     @end itemize

     If your program outputs any of these strings, you should run it in the
     separate execution window.

     If the inferior debugger changes the default TTY settings, for instance
     through a @i{stty} command in its initialization file, GVD will likely
     become confused. The same applies to debugged program which change the
     default TTY settings.

@node Limitations using GDB
@subsection Limitations using GDB
@noindent
     Some GDB settings are essential for GVD to work correctly. These settings
     with their correct values are:

     @itemize @bullet
     @item set height 0
     @item set width 0
     @item set verbose off
     @item set prompt (gdb) 
     @end itemize

     GVD sets these values automatically when invoking GDB; if these values
     are changed, there may be some malfunctions, especially in the data
     display.

@c --------------------------------------------------------------------
@node Reporting bugs
@section Reporting bugs
@c --------------------------------------------------------------------

@noindent
If you encounter a bug in GVD, you can report it to
@uref{mailto:report@@gnat.com} if you are a supported user (to become a
supported user, contact @uref{mailto:sales@@gnat.com}), or to the
public gvd development list (@uref{mailto:gvd-devel@@lists.act-europe.fr}).

Please try to include a detailed description of the problem, including
sources to reproduce it if possible, and/or a scenario describing the
actions performed to reproduce the problem. Saving your session and
the log file (see @ref{log file}) can help automate this process.

@c ---------------------------------------------------------------------
@node Frequently Asked Questions
@chapter Frequently Asked Questions
@c ---------------------------------------------------------------------

@noindent
This chapter includes the answers to some questions that are
frequently asked by people trying to use GVD for specific tasks. Some
of the answers are not specific to GVD itself, but rather to the
underlying debugger.

@itemize @bullet

@item My Ada program seems to fail during elaboration. How can I debug it ?

@enumerate A
@item If your program was compiled with GNAT, the main program is
generated by the binder. This program is an ordinary Ada (or C if the
@option{-C} switch was used) program, compiled in the usual manner,
and fully debuggable provided that the @option{-g} switch is used on
the @command{gnatlink} command (or -g is used in the
@command{gnatmake} command itself).

The name of this package containing the main program is
@file{b~xxx.ads/adb} where xxx is the name of the Ada main unit given
in the gnatbind command, and you can edit and debug this file in the
normal manner. You will see a series of calls to the elaboration
routines of the packages, and you can debug these in the usual manner,
just as if you were debugging code in your application.

@end enumerate

@item How can I debug the Ada run-time library ?

@enumerate A
@item The run time distributed in binary versions of GNAT hasn't been
compiled with debug information. Thus, it needs to be recompiled
before you can actually debug it.

The simplest is to recompile your application by adding the switches
@option{-a} and @option{-f} to the @command{gnatmake} command
line. This extra step is then no longer required, assuming that you
keep the generated object and ali files corresponding to the GNAT run time
available.

Another possibility on Unix systems is to use the file @file{Makefile.adalib}
that can be found in the adalib directory of your GNAT installation and
specify e.g @option{-g -O2} for the @option{CFLAGS} switches.

@end enumerate

@end itemize

@end ifclear
@c GPS
