DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
Using the graphical interface of debug

Configuration

The layout of the graphical debugger is configurable by the user. The user may specify:

The configuration is specified in a series of files in the configuration directory. The configuration directory may be specified on the command line or as an X resource (see ``Invoking the debugger'' and ``Customization''). Each file in the configuration directory contains the configuration specification for a single window. The name of the file provides the name used for that window.

The default configuration directory is /usr/ccs/lib/debug_config. To create your own configuration, we suggest you copy the files from /usr/ccs/lib/debug_config into your own directory and modify them as desired (deleting, adding or renaming a file if you want to remove, add or change the name of a given window).

If a configuration file is unreadable or empty or contains an invalid configuration specification, the debugger's default configuration will be used.

A configuration specification consists of keywords, user-defined names and numbers. Names are used for menu titles, button labels, button mnemonics and button command specifications. Any name containing whitespace must be enclosed in quotation marks. Names may not span multiple lines.

Whitespace is ignored, except within quoted names. A comment begins with a pound sign (#) or an exclamation point (!) character and continues until the end of the line. Comments are also ignored.

A configuration for a single window is made up of a series of descriptors. Each descriptor begins with a keyword (possibly followed by an argument) and the descriptor body. The body of the descriptor is enclosed in curly brackets ({}). For example, the descriptor that specifies the panes that will be contained in a given window might look like:

   Panes {
           status 1 60
           stack 4 60
           source 10 60 source_pane_menu
   }
The valid descriptors are: The order of the descriptors is not important except that the MenuBar descriptor and the Panes descriptor (if it contains a popup menu identifier) must come before the descriptor for any individual Menu.

The Flags descriptor takes no arguments. It defines global attributes for the window. The body of the descriptor consists of a list of flags, one per line. Currently, the only flag defined is autoload. If this flag is defined for a given window, that window is always displayed when the debugger is invoked or a new window set is created. An example Flags descriptor follows:

   Flags {
           autoload
   }
Every window configuration specification must contain a Panes descriptor. The Panes descriptor takes no arguments. It describes the panes that will be displayed in this window. The body of the Panes descriptor consists of a series of pane specifications, one per line. Each line contains the type of the pane to be displayed. The pane type may optionally be followed by a decimal number describing the number of lines to display for the pane. If the number of lines is specified, it may optionally be followed by another decimal number indicating the number of columns. If either the line or column specifiers are missing, debug provides default values. The final entry in a pane specification is a menu identifier. The menu identifier specifies that this pane will provide a popup menu; it is used later on as an argument to the Menu descriptor. The menu identifier is only used within the configuration file and has no affect on the appearance of the debugger itself.

The valid pane types are as follows:

The line specifier has no affect on the Status pane (it always has 1 line). The column specifier has no affect on the Event pane, the Process pane, the Stack pane, the Status pane or the Symbol pane. A window will be as wide as its widest element, even if it contains a pane with a smaller column specifier.

If a pane defines a popup menu, that menu may be accessed by moving the pointer over the pane and clicking MENU.

A pane may be specified only once per window, but the same pane may appear in multiple windows. If a pane (other than the ``Status pane'') is not specified for any window, the debugger will report an error. An example Panes descriptor follows:

   Panes {
           status
           symbols 8
           source 10 60 source_pane_menu
   }
The MenuBar descriptor is also required for each window. It takes no arguments. It defines the menu buttons that will appear in the menu bar at the top of the window. Each button in the menu bar invokes a pull down menu. The body of the descriptor consists of a series of lines, each specifying an item in the menu bar. Each line contains a user-defined name that will appear as the label for the menu button. The menu name is optionally followed by a mnemonic specification. The mnemonic consists of an underscore (_) followed by a single character. The character should be one of the characters in the menu name. The mnemonic is followed by a menu identifier name. This identifier is used later on as an argument to the Menu descriptor. It is only used within the configuration file and has no effect on the appearance of the debugger itself. An example MenuBar descriptor follows:
   MenuBar {
           File _F file_menu
           Edit _E edit_menu
           View _V view_menu
           Help _H help_menu
   }

A Menu descriptor is required for all menus defined in the MenuBar or Panes descriptors. The Menu descriptor takes a single argument, the menu identifier used in the MenuBar or Panes descriptor. The Menu descriptor describes the options available in a given menu. The body of the descriptor consists of a series of button specifications, one per line. Each button specification contains a user-defined name that will appear as the label for the that button. The button name is optionally followed by a mnemonic specification. The mnemonic consists of an underscore (_) followed by a single character. The character should be one of the characters in the button name. The mnemonic is followed by the button action. The button action is an identifier that describes the action that results when the corresponding button is activated. The list of valid button actions is presented below.

Three button actions take an additional argument:


f.menu menu_identifier

f.menu is the action that creates a sub-menu. menu_identifier is just like the identifier used in a MenuBar descriptor. The identifier must appear as the argument in a subsequent Menu descriptor.

f.exec command

f.exec forks a process to execute command. If command contains whitespace, it should be surrounded by quotation marks.

f.debug_command command

f.debug_command passes command to the command line debugger. If command contains whitespace, it should be surrounded by quotation marks.
The f.separator button action is special in that it does not need a name and does not create a new button. It simply draws a line between the buttons that come before and after it and serves as a way of organizing a menu visually. The f.popup button action causes a debugger window to be popped up. The name given to the button must match the name of one of the debugger windows.

An example Menu descriptor follows:

   Menu edit_menu {
           "Set Current" _S f.set_current
           ""               f.separator
           Copy          _C f.copy
           Cut           _t f.cut
           Paste         _P f.paste
           Delete        _D f.delete
           Undo          _U f.undo
   }
The final descriptor type is the Buttons descriptor. The Buttons descriptor is entirely optional. If no button descriptors appear, the window will not contain a Button Bar. The Buttons descriptor takes as an argument a location specifier, which can be either top or bottom. The location specifier determines the placement of the Button Bar within the window. If two or more Buttons descriptors contain the same location specifier (top or bottom), then the corresponding Button Bar will contain multiple panels of buttons. You move from one panel to another by clicking SELECT on the Next Panel button, which will automatically be created as the first button in the Button Bar. Any number of Buttons descriptors can be created for both top and bottom Button Bars in each window.

The body of the Buttons descriptor is identical to the body of the Menu descriptor. That is, it consists of a series of button specifications, one per line. Each button specification contains a button name, optional mnemonic and button action. The only difference between the bodies of the Buttons and Menu descriptors is that the f.menu and f.separator actions are not valid in a Buttons descriptor.

An example Buttons descriptor follows:

   Buttons top {
           Run            _R f.run
           Return         _t f.return
           "Run Until..." _U f.run_until
           Command        _C f.popup
   }
The valid button action names for Menu and Buttons descriptors are as follows:

f.animate_disassembly -
``Animate Disassembly''

f.animate_source -
``Animate Source''

f.animation_dialog -
``Animation''

f.button_dialog -
``Button Configuration''

f.cancel_dialog -
``Cancel''

f.cd_dialog -
``Change Directory''

f.change_dialog -
``Change''

f.close_window -
``Close Window''

f.command_pane_help -
``Pane Help''

f.copy -
``Copy''

f.create_dialog -
``Create''

f.cut -
``Cut''

f.debug_command -
``Debug command''

f.delete -
``Delete text''

f.delete_breakpoint -
``Delete Breakpoint''

.delete_event -
``Delete event''

.destroy -
``Destroy''

f.disable_event -
``Disable''

f.disassembly_mode_dialog -
``Disassembly Mode''

f.disassembly_pane_help -
``Pane Help''

f.dump_dialog -
``Dump''

f.enable_event -
``Enable''

f.exception_dialog -
``Exception''

f.exec -
``Exec command''

f.exit -
``Exit''

f.export -
``Export''

f.frame_direction_dialog -
``Frame Direction''

f.grab_core_dialog -
``Grab core''

f.grab_process_dialog -
``Grab process''

f.granularity_dialog -
``Granularity''

f.halt -
``Halt''

f.ignore_exceptions_dialog -
``Ignore Exceptions''

f.ignore_signals_dialog -
``Ignore Signals''

f.input_dialog -
``Input''

f.interrupt -
``Interrupt''

f.jump_dialog -
``Jump''

f.kill_dialog -
``Kill''

f.language_dialog -
``Language''

f.map_dialog -
``Map''

f.menu (Menu descriptor only)
f.move_dialog -
``Move''

f.new_source -
``New Source''

f.new_window_set -
``New Window Set''

f.next_instruction -
``Next Instruction''

f.next_statement -
``Next Statement''

f.on_stop_dialog -
``On Stop''

f.open_dialog -
``Open Source''

f.output_dialog -
``Output Action''

f.paste -
``Paste''

f.path_dialog -
``Source Path''

f.pin -
``Pin''

f.popup -
``Popup window button''

f.process_pane_help -
``Pane Help''

f.release -
``Release''

f.release_running -
``Release''

f.release_suspended -
``Release''

f.return -
``Return''

f.run -
``Run''

f.run_until_dialog -
``Run Until''

f.save -
``Save''

f.save_as_dialog -
``Save As''

f.save_layout -
``Save Layout''

f.script_dialog -
``Script''

f.search_dialog -
``Search''

f.separator (Menu descriptor only)
f.set_breakpoint -
``Set Breakpoint''

f.set_current -
``Set current''

f.set_value_dialog -
``Set value''

f.set_watchpoint -
``Set Watchpoint''

f.show_function_dis_dialog -
``Show Function Dis''

f.show_function_source_dialog -
``Show Function Source''

f.show_line_dialog -
``Show Line''

f.show_location_dialog -
``Show Location''

f.show_type_dialog -
``Show Type''

f.show_value_dialog -
``Show Value''

f.signal_dialog -
``Signal''

f.source_pane_help -
``Pane Help''

f.sources_menu -
``Sources''

f.stack_pane_help -
``Pane Help''

f.step_dialog -
``Step''

f.step_instruction -
``Step Instruction''

f.step_statement -
``Step Statement''

f.stop_dialog -
``Stop''

f.stop_on_function_dialog -
``Stop on Function''

f.symbols_dialog -
``Symbols''

f.syscall_dialog -
``Syscall''

f.symbols_pane_help -
``Pane Help''

f.table_of_contents_help -
``Table of Contents''

f.undo -
``Undo''

f.unpin -
``Unpin''

f.version -
``Version''

f.windows_menu -
``Windows''

f.window_sets_menu -
``Window Sets''

The following sample configuration file defines the Symbols window in the debugger's default configuration, and is taken from /usr/ccs/lib/debug_config/Symbols:

   Panes {
           status 1 60
           symbols 8 60 symbols_pane_menu
   }
   

MenuBar { File _F file_menu Edit _E edit_menu View _w view_menu Control _C control_menu Event _v event_menu Properties _P properties_menu Help _H help_menu }

Buttons top { Pin _i f.pin Unpin _U f.unpin Symbols... _S f.symbols_dialog Command _m f.popup Disassembly _D f.popup Event _t f.popup Process _r f.popup Source _o f.popup }

Menu file_menu { Windows _W f.windows_menu Sources _S f.sources_menu "Window Sets" _i f.window_sets_menu "" f.separator "Save Layout" _L f.save_layout "Close Window" _C f.close_window Exit _x f.exit }

Menu edit_menu { Export _E f.export Pin _P f.pin Unpin _U f.unpin }

Menu view_menu { Dump... _D f.dump_dialog "" f.separator "Show Value..." _S f.show_value_dialog "Set Value..." _V f.set_value_dialog "Show Type..." _T f.show_type_dialog }

Menu control_menu { Run _R f.run Return _t f.return "Run Until..." _U f.run_until_dialog "" f.separator "Step Statement" _S f.step_statement "Step Instruction" _I f.step_instruction "Next Statement" _N f.next_statement "Next Instruction" _x f.next_instruction "Step..." _e f.step_dialog "" f.separator Jump... _J f.jump_dialog Halt _H f.halt }

Menu event_menu { "Set Watchpoint" _W f.set_watchpoint "Stop on Function..." _F f.stop_on_function_dialog Stop... _S f.stop_dialog "" f.separator Syscall... _y f.syscall_dialog "On Stop..." _O f.on_stop_dialog "" f.separator Signal... _i f.signal_dialog Cancel... _C f.cancel_dialog Destroy _e f.destroy Kill... _K f.kill_dialog "Ignore Signals..." _g f.ignore_signals_dialog "" f.separator Exception... _x f.exception_dialog "Ignore Exceptions..." _n f.ignore_exceptions_dialog }

Menu properties_menu { "Button configuration..." _B f.button_dialog Language... _L f.language_dialog Symbols... _S f.symbols_dialog }

Menu help_menu { Version _V f.version "Status Pane Help..." _u f.status_pane_help "Symbols Pane Help..." _S f.symbols_pane_help "Table of Contents..." _T f.table_of_contents_help }

Menu symbols_pane_menu { Dump... _D f.dump_dialog "Set Watchpoint" _W f.set_watchpoint "Show Type..." _T f.show_type_dialog "Show Value..." _S f.show_value_dialog }


Next topic: Technical tips
Previous topic: Resource settings

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004