* gdbint.texinfo (Host Definition): Remove description of

[deliverable/binutils-gdb.git] / gdb / doc / gdbgui.texinfo

\input texinfo      @c -*-texinfo-*-
@c Copyright 1994, 1995, 2001 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c of @set vars.  However, you can override filename with makeinfo -o.
@setfilename gdb.info
@c
@include gdb-cfg.texi
@c
@ifset GENERIC
@settitle Using the Graphical Interface to @value{GDBN}
@end ifset
@ifclear GENERIC
@settitle Using the Graphical Interface to @value{GDBN} (@value{TARGET})
@end ifclear
@setchapternewpage odd
@c %**end of header

@c Since this interface is so new, there is much missing still.
@c Desired but unimplemented features are commented out.

@iftex
@c @smallbook
@c @cropmarks
@end iftex

@finalout
@syncodeindex ky cp

@c readline appendices use @vindex
@syncodeindex vr cp

@c !!set GDB manual's edition---not the same as GDB version!
@set EDITION 4.14

@c !!set GDB manual's revision date
@set DATE April 2001

@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.

@dircategory Programming & development tools
@direntry
START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY
@end direntry
@c
@c
@ifinfo
This file documents the graphical interface to the GNU debugger @value{GDBN}.


This is Edition @value{EDITION}, @value{DATE},
of @cite{Using the Graphical Interface to @value{GDBN}}
for GDB Version @value{GDBVN}.

Copyright (C) 1994, 1995, 2001 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Using the Graphical Interface to ``GDB'' and
``Starting up GUI GDB'', with the Front-Cover texts being ``A GNU
Manual,'' and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end ifinfo

@titlepage
@title Using the Graphical Interface to @value{GDBN}
@subtitle The GNU Source-Level Debugger
@ifclear GENERIC
@subtitle (@value{TARGET})
@end ifclear
@sp 1
@subtitle Edition @value{EDITION}, for @value{GDBN} version @value{GDBVN}
@subtitle @value{DATE}
@author Stanley T.@: Shebs
@page
@tex
{\parskip=0pt
\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par
\hfill {\it Debugging with @value{GDBN}}\par
\hfill \TeX{}info \texinfoversion\par
\hfill doc\@cygnus.com\par
}
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1994, 1995, 2001 Free Software Foundation, Inc.
@sp 2

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Using the Graphical Interface to ``GDB'' and
``Starting up GUI GDB'', with the Front-Cover texts being ``A GNU
Manual,'' and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end titlepage
@page

@ifinfo
@node Top
@top Using the Graphical Interface to @value{GDBN}
@end ifinfo

This file describes a graphical interface to @value{GDBN},
the GNU symbolic debugger.

@node Invocation
@chapter Starting up GUI @value{GDBN}

If @value{GDBN} has been configured to use the graphical interface,
then you will get the interface automatically upon startup.

When running as a Unix program and using the X11-based interface,
you must of course be using an X server and/or workstation,
and your @code{DISPLAY} environment variable must be set correctly.
If either of these is not true, then @value{GDBN} will still start up,
zbut will use only the traditional command interface.

The exact layout and appearance of the windows will depend on the host
system type.  For instance, @value{GDBN} on MS-Windows will display
its windows inside a larger window, while on X on a GNU/Linux or a
Unix machine, each window is a separate toplevel window.  However,
general behavior and layout is consistent across all platforms;
omissions or restrictions on particular platforms, if not documented
as unavoidable, should be considered bugs and reported.

All @value{GDBN} windows have a common structure.  Each window has an
associated menu bar, which may be at the top of the window or perhaps
elsewhere.  Some of the menus and menu items in the menu bar are
common to all @value{GDBN} windows, while others are specific to
particular types of windows.  Below the menu bar is the working data
area of the window.  If the data is too large to display all at once,
the data area will have scroll bars on its right and bottom sides.
Below the data area are two optional features; a status/data line, and
a button box.

@section Menus

@subsection File Menu

The standard file menu provides operations that affect the overall state
of @value{GDBN}, mainly file operations, but other things as well.

@table @code
@item About @value{GDBN}...
Displays the startup window for @value{GDBN}.

@item File...
Lets you set the combined executable and symbol file that @value{GDBN}
will use.  (Like the @samp{file} command in the command-line version
of @value{GDBN}.)

@item Target...
Brings up a dialog that you can use to connect @value{GDBN} to a
target program.  The dialog is described in more depth later.  (Like
the @samp{target} command.)

@item Edit...
Starts up an editor to modify the source file being displayed.

@item Exec File...
Lets you set the executable file that @value{GDBN} will use.
(Like the @samp{exec-file} command.)

@item Symbol File...
Lets you set the symbol file that @value{GDBN} will use.
(Like the @samp{symbol-file} command.)

@item Add Symbol File...
Lets you add additional symbol files.
(Like the @samp{add-symbol-file} command.)

@item Core File...
Lets you set the core file that @value{GDBN} will use.
(Like the @samp{core-file} command.)

@item Shared Libraries...
(Like the @samp{sharedlibrary} command.)

@item Quit
Quits @value{GDBN}.
(Like the @samp{quit} command.)
@end table


@c @subsection Commands Menu

@c The commands menu consists of items that let you run and control the program being
@c debugged.
@c 
@c @table @code
@c @item Run
@c 
@c @item Step
@c 
@c @item Next
@c 
@c @item Finish
@c 
@c @item Stepi
@c 
@c @item Nexti

@subsection Windows Menu

The @samp{Windows} menu allows access to all the windows available in
@value{GDBN}.  The first part of the menu lists all of the predefined
individual windows.  If the window exists already, its item will be
marked as such; selecting the item will cause the window to be put in
front if it is obscured.  If it does not exist, then it will be
created.

The second part of the menu lists additional windows that you may have
created, such as source windows or variable displays.

@display
Command
---
Source
Assembly
---
Registers
Variables
---
Files
@c ---
@c <extra windows>
@end display

@subsection View Menu

All windows have a @samp{view} menu, but its contents are highly
specific to window type.  For instance, a source window will have a
view menu item to control the display of line numbers, but a register
window will instead have an option to choose the radix in which to
display register contents.  You can find the full description of view
options with each window type.

@subsection Help Menu

The @samp{Help} menu includes access to @value{GDBN}'s online help.

@section Windows

@subsection Command Window

The @samp{Command} window provides access to the standard @value{GDBN}
command interpreter.  In nearly all cases, commands typed into this
window will behave exactly as for a non-windowing @value{GDBN}.

Note that not all changes to @value{GDBN} will be reflected in this
window.  For instance, if you were to type a @samp{step} command, then
click on the @samp{step} menu item in the source window, then go back,
and type another @samp{step} command, the command buffer will only
show two steps, when you have actually done three.  @value{GDBN} will
put a ``@dots'' into the command buffer when operations in other
windows are done, as a reminder that the command buffer is incomplete.

@c Also note that as a side effect of having the interface and possibly an
@c associated scripting language built in, additional commands may be
@c available.  For instance, if tcl is in @value{GDBN}, the command 
@c ``tcl <tcl code>'' will be available.

The command window has no status line or button box.

@subsection Files Window

The @samp{Files} window lists all of the files that were used to build the
executable.

Clicking on the @samp{xxx} in the left margin expands/contracts the
display of included files and symbols defined by the file.

The @samp{View} menu for this window includes the following items:

@table @code
@item Name/Full Pathname
@c @item Sort by Name
@c @item Sort by Section&Offset
@c @item Show All Included Files
@c @item Included File Indentation...
@end table

@subsection Source Window

A @samp{Source} window displays a single file of source code.

The left margin includes an indicator for the current PC, breakpoints
and potential breakpoints, and (optionally) line numbers.

The @samp{View} menu for this window includes the following items:

@table @code
@item Show Line Numbers
@item Show Breakdots
@c @item Jump to PC (if pc changes, scroll back so PC is centered)
@c @item Tab... (set tabbing)
@end table

@section Extensions

[description of gdbtk details]

@c 
@c GDBTK Interface Design
@c 
@c This is the working document describing the design of the GDBTK
@c interface.  Note that overall layout applies only to the default setup;
@c it is expected that debugger users will be able to customize extensively.
@c 
@c Default Startup
@c 
@c One source window, shows source as in "list main", does *not* set a
@c break at main or run or anything.  No current PC indicator, only put
@c in when something runs.
@c 
@c Source Window
@c 
@c For native, "run" button is always the same, for cross, it's actually
@c a "target" button that pops up appropriate dialog to get connected.
@c Once remote target is active, change button to "run".
@c 
@c Be able to toggle assembly interleaved between source.
@c 
@c Command Window
@c 
@c Is an *optional* window.
@c 
@c Behavior mimics command-line @value{GDBN} running in an Emacs buffer as much
@c as possible.
@c 
@c Assembly Window
@c 
@c Be able to toggle source interleaved between assembly.
@c 
@c Target Info Window
@c 
@c Contents similar to "info target".
@c 
@c Should expand into process and thread info also.
@c 
@c File Info Window
@c 
@c Contents similar to "info files".
@c 
@c Include data shown in "info sources" as well as "info files".
@c 
@c Register Info Window
@c 
@c Contents similar to "info registers".
@c 
@c Add view option(s) for classes of registers.
@c 
@c Stack Info Window
@c 
@c Combines backtrace, frame, and local var displays.
@c 
@c Signals Dialog
@c 
@c Includes all signals whose handling may be controlled, plus
@c checkboxes for what to do with each.
@c 
@c Settings Dialog(s)
@c 
@c Include all variables that can be "set" and "show"n.
@c 
@c General Principles
@c 
@c All windows should have a menu that allows access to other windows.
@c Selection of item either brings up for first time or brings to front.
@c 
@c All windows should have a "view" menu that controls formatting
@c options for that window.
@c 
@c Windows should usually be scrollable.  Windows that display largish
@c horizontal things should be horizontal and vertical scrollbars.
@c 
@c To do standard modification, add commands or tcl code to .gdbtkinit.
@c 
@c Be able to record window positions so they come up in the same way
@c the next time.  Could scribble on .gdbtkinit perhaps, or else an
@c aux file that can be sourced by .gdbtkinit.

@section How to Build

If @value{GDBN} is configured with @samp{--enable-gdbtk}, then upon
startup, it will open windows.

@node Index
@unnumbered Index

@printindex cp

@contents
@bye