# $Id: TIPS 6884 2008-03-09 20:42:06Z apg $ -*- autoconf -*-
# DDD tips of the day.

# Copyright (C) 1998 Technische Universitaet Braunschweig, Germany.
# Copyright (C) 2000 Universitaet Passau, Germany.
# Written by Andreas Zeller <zeller@gnu.org>.
# 
# This file is part of DDD.
# 
# DDD is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
# 
# DDD is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public
# License along with DDD -- see the file COPYING.
# If not, see <http://www.gnu.org/licenses/>.
# 
# DDD is the data display debugger.
# For details, see the DDD World-Wide-Web page, 
# `http://www.gnu.org/software/ddd/',
# or send a mail to the DDD developers <ddd@gnu.org>.

# This is a list of tips for DDD.  Every time DDD is started, one tip
# will be selected from this file and will be displayed in the `Tip of
# the day' dialog.
#
# - Lines starting with `#' and `!' are comments.
#   `!` comments will appear in the resource file, `#' comments will not.
# - Blank lines or comments separate two tips (they are not ignored).
#   Multiple blank lines are treated as one.  If you want to have a
#   blank line in a tip, put a space or tab in it.
# - Text will appear in the dialog as it is in this file.  This is
#   done on purpose in order to have more freedom in the layout of the
#   tips than with automatic word-wrapping, but this also means that
#   you have to avoid excessively long lines in this file.
# - This file is processed by M4 and may contain typesetting macros.
#   See `ddd/macros.m4' for details.
# - Tips should be concise: 3 lines or less.

# Include Macro definitions
include(ifdef(`macros',macros(),ifdef(`srcdir',srcdir()/macros.m4,macros.m4)))


! Initial tip (number 0) - shown after wrap-around.

If you have any more DDD tips of the day,
please send them to the DDD developers EMAIL([ddd]@ gnu.org).


! First tips.

Welcome to DDD!
You can get help on all items by pointing at them and pressing F1.
And don't worry, you can undo most mistakes...

Whenever you're stuck, try LBL(Help, What Now).  This will analyze the
current DDD state and give you some hints on what to do next.

Buttons with a small triangle in the upper right corner are special:
pressing and holding BUTTON(1) on them will pop up a menu 
with additional options.

You can interrupt @GDB@ and the current program by clicking on
LBL(Program, Interrupt) or pressing KEY(Esc).

If you made a mistake, try LBL(Edit, Undo).  This will undo the most
recent debugger command and redisplay the previous program state.

There are three ways to show the value of a variable:
ITEM You can view its value, simply by pointing at it;
ITEM You can print its value in the debugger console, using LBL(Print ());
ITEM You can display it graphically, using LBL(Display ()).

A quick way to manipulate variables, breakpoints, and displays
is to press BUTTON(3) on them.

Double-clicking on any value in the data display 
will toggle more details.

If your program needs special terminal capabilities such as readline
or curses, let it run in the separate execution window 
(LBL(Program, Run in Execution Window)).


! Intermediate tips.

You can save space in the data window by 
ITEM hiding details (LBL(Show/Hide)),
ITEM rotating structs (LBL(Rotate)), and 
ITEM clustering variables (LBL(Undisp, Cluster)).

If you want to customize the DDD fonts, see
LBL(Edit, Preferences, Fonts).

To change the text background color, write into FILE(~/.[ddd]/init):
CODE([Ddd]*XmText.background:      ) VAR(color)
CODE([Ddd]*XmTextField.background: ) VAR(color)
CODE([Ddd]*XmList.background:      ) VAR(color)

When using GDB, all text fields have command and argument completion
with KEY(Tab), just like the shell.  In a file selection box, type part of
a filename, hit KEY(Tab), and voila!  It's completed.

You can always recenter the command tool
by selecting LBL(View, Command Tool),
or by pressing KEY(Alt+8).

To scroll the data display, most users find a EMPH(panner)
much more convenient than two scrollbars.
Check out LBL(Edit, Preferences, Startup, Data Scrolling).

To limit the number of array elements in a data display, set
LBL(Edit, GDB Settings, Limit on array elements to print).

If DDD cannot find a source, set the @GDB@ source path via 
LBL(Edit, @GDB@ Settings) or enter 
SAMP(dir sourcedir_1:sourcedir_2:...:sourcedir_n) at the GDB prompt.

You can quickly set breakpoints
by double-clicking in the breakpoint area.

To see the EMPH(actual) type of a C++ object in GDB, set
LBL(Edit, GDB Settings, Set printing of object's derived type).

To display VAR(data) in hexadecimal format, display it and choose
LBL(Convert to Hex) from the LBL(Display ()) menu, 
or enter KBD(graph display /x VAR(data)) at the GDB prompt.

To send a signal to your program,
use LBL(Status, Signals, Send).

To quickly display variable values,
double-click on the variable name.

After looking up an item or stepping through the program, you can use
LBL(Edit, Undo) and LBL(Edit, Redo) to return to earlier locations.

You can repeat the last command by hitting KEY_RETURN.
Use KEY(Ctrl+B) and KEY(Ctrl+F) to search the command history.

You can move breakpoints by dragging them.  
Just press and hold BUTTON(1) on a breakpoint,
move it to the new position and release BUTTON(1) again.

To make your program ignore signals, use LBL(Status, Signals) and
unset the LBL(Pass) button for the appropriate signal.

You can save space by disabling toolbar captions.
See LBL(Edit, Preferences, Startup, Toolbar Appearance).

To quickly edit breakpoint properties, 
double-click on a breakpoint symbol.

To have GDB start your program automatically upon startup,
put the following lines in your FILE(.gdbinit) file:
CODE(break main)      - or some other initial function
CODE(run       )      - possibly giving arguments here


! Advanced tips.

To get rid of these tips of the day, unset
LBL(Edit, Preferences, Startup, Show Tip of the Day).

To redirect stderr from the execution window to the debugger console,
add SAMP(2>/dev/tty) to the arguments of your program.

To display the first VAR(n) elements of a variable-length array VAR(ptr),
enter KBD(graph display VAR(ptr)\1330\135@ VAR(n)) at the GDB prompt.

To undisplay a specific record member once and for all, select it in a
display and click on LBL(Undisp).  Confirming with LBL(Apply to All)
suppresses the member in other displays, too.

To display data in a smaller font, try LBL(Data, Themes, Small Values).
The pattern describes the expressions you want to see in smaller font:
SAMP(*) matches all expressions.

You can have each of DDD, @GDB@ and the debugged program run on
different machines.  See the DDD KBD(--rhost) option for details.

You can copy breakpoints by dragging them while pressing KEY(Shift).
Just press and hold KEY(Shift)+BUTTON(1) on a breakpoint,
move it to the new position and release BUTTON(1) again.

To save and restore data displays, cut, copy and paste them via
the LBL(Edit) menu.  Together with CODE(xclipboard), you can manage
arbitrary collections of data displays.

Do you want to stop this debugging session and resume later?
Use LBL(File, Save Session)!

You can interact with DDD even while the debuggee is executing:
DDD automatically interrupts program execution for a moment.  
This works whenever program execution is initiated by LBL(Run) or LBL(Cont).

To debug a child process, put a call to SAMP(sleep) in the child right
after the SAMP(fork) call.  Run the program and attach to the child process
using LBL(File, Attach to Process).

If your program prints a lot of text on standard error, try
redirecting standard error to a file (via SAMP(2> VAR(FILE))), or add
to FILE(~/.[ddd]/init): CODE([Ddd]*lineBufferedConsole: off).

If the inferior debugger does not support stderr redirection, try
invoking DDD using KBD(--debugger 'VAR(NAME) 2> VAR(FILE)').

Using GDB, you can define your own canned sequences of commands.
Try LBL(Commands, Define Command).

To use GDB with Solaris CC, compile with SAMP(-xs).
GDB wants debugging info in the executable.

To use GDB with G77, compile with SAMP(-fdebug-kludge).  This gives
rudimentary information on COMMON and EQUIVALENCE variables in GDB.
See the G77 documentation for details.

Double-clicking on a function call will lead you to the definition of
the function.  Use LBL(Edit, Undo) to return to the function call.

Disabled breakpoints can be used as bookmarks.
Use LBL(Source, Edit Breakpoints) to list all breakpoints;
then, click on LBL(Lookup) to jump to a breakpoint location.

You can assign user-defined buttons to frequently used commands.
Try LBL(Commands, Edit Buttons).

In the Breakpoint and Display Editors,
you can toggle the selection with KEY(Ctrl)+BUTTON(1).
This allows you to select non-contiguous ranges of items.

To change the properties of multiple breakpoints at once,
select them in the breakpoint editor (LBL(Source, Edit Breakpoints))
and click on LBL(Properties).

Even while in the source window, 
you can enter and edit GDB commands:
Just type the command and press KEY_RETURN.

You can record commands to be executed when a breakpoint is hit.
In the LBL(Breakpoint Properties) panel, try LBL(Record) and LBL(End).

You can easily resume a saved DDD VAR(session)
by invoking DDD as KBD([ddd] =VAR(session)).

If the DDD source window keeps on scrolling until the end of source is
reached, try changing the SAMP(glyphUpdateDelay) resource.  See the
DDD manual for details.

To customize display appearance, you can write your own themes.
For details, see the  manual "Writing DDD Themes".

For further DDD customization (e.g. colors), see the FILE([Ddd])
app-defaults file from the DDD WWW Site or the DDD source
distribution.  Copy resources to FILE(~/.[ddd]/init) and edit as desired.


! Tips from professionals.

In GCC, SAMP(-Wall) does not enable all warnings.  See the GCC
documentation for other warnings you might consider useful.
BY(J.H.M. Dassen, jdassen@ wi.leidenuniv.nl)

To get a global idea of what a process or program does or is doing,
use a system call tracer, like SAMP(strace), SAMP(truss), or SAMP(trace).
BY(J.H.M. Dassen, jdassen@ wi.leidenuniv.nl)

If you suspect memory corruption caused by problematic pointers, 
try linking with Electric Fence SAMP(efence) or the SAMP(dbmalloc) library.
See the DDD WWW page for links.
BY(J.H.M. Dassen, jdassen@ wi.leidenuniv.nl)

Prevention is better than cure.  Document your assumptions using
CODE(<assert.h>) or GNU NANA.  See the DDD WWW page for links.
BY(J.H.M. Dassen, jdassen@ wi.leidenuniv.nl)

The debugger isn't a substitute for good thinking.  But, in some
cases, thinking isn't a substitute for a good debugger either.  The
most effective combination is good thinking and a good debugger.
QUOTE(Steve McConnell, Code Complete)

When you're totally stuck, try to find a helpful ear.  In my experience,
nothing helps you more in debugging than to try to explain your problem
(what your code should do, and what it actually does) to someone else.
BY(J.H.M. Dassen, jdassen@ wi.leidenuniv.nl)

! If you have other questions, comments or suggestions, contact The King via
! electronic mail to EMAIL(elvis@ graceland.gnu.org).  The King will
! try to help you out, although he may not have time to fix your problems.
! QUOTE(Free Software Foundation, GNU Hello Manual)