# $Id: TIPS,v 1.30 1998/06/17 13:16:27 zeller Exp $ -*- autoconf -*-
# DDD tips of the day.

# Copyright (C) 1998 Technische Universitaet Braunschweig, Germany.
# Written by Andreas Zeller <zeller@ips.cs.tu-bs.de>.
# 
# 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 2 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, write to the Free Software Foundation, Inc.,
# 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# 
# DDD is the data display debugger.
# For details, see the DDD World-Wide-Web page, 
# `http://www.cs.tu-bs.de/softech/ddd/',
# or send a mail to the DDD developers <ddd@ips.cs.tu-bs.de>.

# 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(`srcdir',srcdir()/macros.m4,macros.m4))dnl

! 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]@ ips.cs.tu-bs.de).


! First tips.

Welcome to DDD!
You can get help on all items by pointing at them and pressing F1.
And don't worry, there is the LBL(Help) menu with much more information...

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).

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, 
let it run in the separate execution window
(LBL(Program, Run in Execution Window)).


! Intermediate tips.

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).

To enable source line numbers, set the source indentation
(LBL(Edit, Preferences, Source, Source Indentation))
to LBL(5) or more.

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(Source, Back) and LBL(Source, Forward) 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 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.

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)!

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).

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

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

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)).

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.


! Professional tips.

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.ai.mit.edu).  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)
