Add support for FreeBSD/i386 ELF.

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

\input texinfo      @c -*-texinfo-*-
@c Copyright 1988 1989 1990 1991 1992 1993 1994 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.13

@c !!set GDB manual's revision date
@set DATE January 1995

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

@ifinfo
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.  zoo@cygnus.com is developing this facility.
@format
START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@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 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@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\@prep.ai.mit.edu.)\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 Free Software Foundation, Inc. 
@sp 2

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@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,
but will use only the traditional command interface.

The exact layout and appearance of the windows will depend on the host
system type.  For instance, GDB under Windows will display its windows
inside a larger window, while under Unix/X, 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 GDB 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 GDB
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 GDB, mainly file operations, but other things as well.

About GDB...

Displays the startup window for GDB.

File...

Lets you set the combined executable and symbol file that GDB will use.
(Like "file".)

Target...

Brings up a dialog that you can use to connect GDB to a target program.
The dialog is described in more depth later.
(Like "target".)

Edit...

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

Exec File...

Lets you set the executable file that GDB will use.
(Like "exec-file".)

Symbol File...

Lets you set the symbol file that GDB will use.
(Like "symbol-file".)

Add Symbol File...

Lets you add additional symbol files.
(Like "add-symbol-file".)

Core File...

Lets you set the core file that GDB will use.
(Like "core-file".)

Shared Libraries...

(Like "sharedlibrary".)

Quit

quits GDB.
(Like @samp{quit}.)


@c @subsection Commands Menu

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

@subsection Windows Menu

The windows menu allows access to all the windows available in GDB.
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.

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

@subsection View Menu

All windows have a 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 help menu includes access to GDB's online help.

@section Windows

@subsection Command Window

The command window provides access to the standard GDB command
interpreter.  In nearly all cases, commands typed into this window
will behave exactly as for a non-windowing GDB. 

Note that not all changes to GDB will be reflected in this window.  For instance,
if you were to type a "step" command, then click on the "step" menu item in
the source window, then go back, and type another "step" command, the command
buffer will only show two steps, when you have actually done three.  GDB will
put a "..." 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 GDB, the command ``tcl <tcl code>''
@c will be available.

The command window has no status line or button box.

@subsection Files Window

The files window lists all of the files that were used to build the
executable.

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

The View menu for this window includes the following items:
Name/Full Pathname
@c Sort by Name
@c Sort by Section&Offset
@c Show All Included Files
@c Included File Indentation...

@subsection Source Window

A 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 View menu for this window includes the following items:
Show Line Numbers
Show Breakdots
@c Jump to PC (if pc changes, scroll back so PC is centered)
@c Tab... (set tabbing)

@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 GDB 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 GDB is configured with --enable-gdbtk, then upon startup, it will
open windows.

@node Index
@unnumbered Index

@printindex cp

@contents
@bye