6.17;debug, revision 6.17, 86/12/02
DEBUG -- Invoke the Language Level Debugger.
usage:
DEBUG [-WPn|-NWP] [-NC] [-SRC|-SRC_T|-SRC_R|-NSRC] [-SDIR pathname]
[-R[EAD] pathname] [-GLOB] [-SMAP] [-SET arg_string]
{-PROC process_name | target [args...]}
FORMAT
DEBUG [options] {-PROC process_name | target [args...]}
The Language Level Debugger (DEBUG) lets you debug programs written in Pascal,
FORTRAN, or C. The DOMAIN Language Level Debugger Reference manual details the
debugger. After you've invoked it, you can enter DEBUG's 'HELP' command to
read other help files that explain how to operate the debugger.
PREPARING A FILE FOR DEBUGGING
In order to use DEBUG to debug a program, you must have compiled your source
code with the correct compiler option. Each compiler supports four command
options (-DB, -DBA, -DBS, or -NDB) that affect DEBUG's access to a program.
-DB, the default, gives you limited access to the debugger. -DBA and -DBS
both give you full access to the debugger. With -DBA, the compiler removes
any optimizations which might interfere with debugging. With -DBS, the
compiler allows any optimizations specified by the -OPT option. If you
compile with -NDB, you cannot debug the file.
INVOKING THE DEBUGGER
To invoke DEBUG, enter a command having one of the following two formats:
$ DEBUG debug_options target [args...]
or
$ DEBUG debug_options -PROC process_name
The necessary arguments and options are described below. By default, the
window from which you invoke DEBUG is divided into three windowpanes. One
windowpane will contain all I/O for the program you are debugging. Another
windowpane will contain all the DEBUG commands you enter and all the responses
from DEBUG. A third windowpane will display the source code of the program
you are debugging.
ARGUMENTS
One of the following two arguments is required on the command line.
target [args...]
(optional) Specify the pathname of the file containing the program you
wish to debug, plus any arguments which that program may
require.
-PROC process_name
(optional) Perform explicit cross-process debugging. This primes
DEBUG to watch for target invocation in an already-existing
process (specified by 'process_name'). After you invoke
DEBUG with this option, it will watch the given process for
the invocation of a program. When the invocation of the
target program occurs, DEBUG will wake up and take control
of the target program, and give you the regular DEBUG
access to it. You cannot debug an already running program,
or a process which is already the target of another
debugger.
This feature is especially useful when the normal
invocation of DEBUG and a target perturbs the environment
enough to make a bug disappear. In this case, creating a
new process for DEBUG and directing it to watch the old
process will help ensure that the target runs in the same
environment as when it runs alone. Cross-process debugging
is also helpful for programs which perform graphics or in
some way alter or control the window(s) of the process in
which they run, thus making normal, within-process
debugging impossible.
OPTIONS
Note that all DEBUG options MUST PRECEDE the pathname of the target program.
Default options are indicated by "(D)."
-NC Prevent DEBUG from copying the target object file.
Instead, DEBUG maps the object file so that you can write
breakpoints directly into the object file.
-R[EAD] pathname
Invoke a DEBUG command file with the specified pathname.
This option may appear only once on the command line.
-SET arg_string
Set debug variable prior to invoking the target program.
'arg_string' is the body of a valid Set command. The
string must be quoted if it contains spaces, so that the
command line parser sees it as one argument. See Example 2
below. If you submit a -SET option which does not have an
assignment operator (=, :=) in 'arg_sring', the Set command
will be interactive as it is during normal DEBUG operation.
-WPn Specify size of DEBUG windowpane from 10% to 90%. 'n' may
equal 10, 20, 30, 40, 50, 60, 70, 80, or 90. Default if
omitted: DEBUG creates a windowpane in the top 50% of the
window.
-NWP Do not create DEBUG windowpanes. Instead, DEBUG will
perform input and output operations using the error input
and error output streams in your transcript pad.
-SRC
-SRC_T
-SRC_R (D) These options cause DEBUG to display the source file(s)
which were used to make the target program being debugged.
The -SRC option lets DEBUG choose where the source will be
displayed. The -SRC_T option makes DEBUG put the source at
the top of the window; the -SRC_R option makes DEBUG put
the source on the right-hand side of the window.
-NSRC Suppress creation of a source-display windowpane.
-SDIR pathname
This option provides alternative directory pathnames for
finding the source file(s), when one of the -SRC options is
used. It may be given any number of times on the command
line. The working directory is always checked and hence
need not be specified.
-GLOB Enable DEBUG to enter routines in global address space.
-SMAP Print a brief section map of the target program loading
operation.
DEBUG STARTUP FILES
When you invoke DEBUG it looks in your login home directory for a file named
"user_data/startup_debug". If it finds the file DEBUG processes its contents
as a sequence of DEBUG commands. DEBUG then looks in the working directory
for a file named "startup_debug" and similary processes it. No error occurs
if one or both files are not found. Startup file processing preceeds
processing of a file given in a -READ option.
SAVING A DEBUG SESSION
To save your dialog with DEBUG, use the Display Manager's command "PN" to name
the debugger's transcript pad anytime before you issue the debugger's quit
command. Type HELP PN for more information.
EXAMPLES
1. $ debug my_prog Tells the debugger to debug the file
named my_prog.
2. $ debug -read s1 my_prog Invokes the debugger for a debugging
session with file my_prog, and starts
the session by executing the commands
stored in file s1.
3. $ debug -src -set "`max_array_dim = 8" my_prog
Sets the `MAX_ARRAY_DIM variable as
you invoke DEBUG; allows DEBUG to
select the most appropriate type of
source display.
RELATED TOPICS
More information is available. Type:
- HELP DEBUG COMMAND
for a brief description of a particular Debug command. For example,
$ HELP DEBUG DEF
displays brief information about the DEBUG command, DEFINE.
- HELP DEBUG COMMAND_V
for a full (verbose) description of a particular Debug command. For example,
$ HELP DEBUG DEF_V
displays complete information about the DEBUG command, DEFINE.
You may also access the command descriptions from within DEBUG itself by
typing
> HELP command
or
> HELP command_V