wguibrow.gml

开放源码的编译器open watcom 1.6.0版的源代码

.chap The &brname
.*
:CMT. :helplvl level=3.
.if &e'&dohelp eq 0 .do begin
.section Introduction
.do end
.*
.np
.ix '&br'
Imagine being assigned to a project with thousands of lines of C++
source code.
Learning the relationship between the objects of such an application
can be very difficult.
The &br was developed to solve this very problem &mdash. to help
developers better understand the source code they are working with.
Information such as the class inheritance hierarchy and the call tree
for an application can be studied while using the &br..
Once you have located a symbol, you can quickly view the source file
that contains its definition or list all the files that reference it.
Viewing these relationships helps you understand how the program works.
.np
This chapter describes the many tasks you can perform with the &br,
including creating and opening a Browser database file, configuring
the Browser session, and viewing the list of all symbols in your
program, the class inheritance hierarchy, and call structure.
.*
.section Using the &br
.*
.np
This section discusses the following topics:
.begbull $compact
.bull
Starting the &br
.bull
Starting the &br through the &wide
.bull
Quitting the &br
.bull
The &br Menu Bar
.endbull
.*
.beglevel
.*
.section Starting the &br
.*
.np
.ix '&br' 'start'
.ix 'start' '&br'
To start the &br, double click on the &br icon.
This opens the &br window.
The caption bar of this window displays the current option file and
Browser database file.
The message
.mono no browser file
appears on this line if a database file is not currently selected.
.np
The &br is an integrated tool that you can open from the &vip so that
you can browse the source code of the project you are working on.
Refer to the &vip guide for further information on the &ide..
.*
.section *refid=brquit Quitting the &br
.*
.np
.ix '&br' 'leave'
.ix 'leave' '&br'
To exit the &br, choose
.us Exit
from the
.us File
menu of the &br window.
If you made changes to the options during the &br session, a message
box appears prompting you to save the changes.
.np
Choose
.ul
No
in the message box to close the &br session without saving.
Any options changed within the session are lost.
.np
Choose
.ul
Yes
in the message box to save the current options to the current option
file, if one exists, and exit the &br session.
If no option file exists, a
.us Save As
dialog appears that allows you to specify the option file to which you
want to save the new options.
.onestep
.step Select
.us Cancel
to return to the main &br window without saving the options.
.orstep Select
.us OK
to close the dialog and exit the &br session.
.endstep
.*
.section The &br Menu Bar
.*
.np
.ix '&br' 'Menu Bar'
The Browser's menu bar consists of the following eight menus:
.begpoint $break
.point File
Create, open, and configure Browser files; save and load options
.point View
Choose a global view for the current database file
.point Detail
View detailed information for a symbol
.point Tree
Choose the nodes to display for a tree view
.point Locate
Find symbols within the current global view
.point Options
Configure the &br session
.point Windows
Select from the list of &br windows currently open
.point Help
Access on-line help information
.endpoint
.*
.endlevel
.*
.section Browser Files
.*
.np
.ix '&br' 'files'
.ix 'module file' 'in &br'
To browse your source code, you must first create a &br module
file for each source file that you wish to browse.
Currently, browsing is supported by the &watc compilers only
(&watf does not support browsing).
To create a &br module file, specify the "db" option when you
compile the source file.
If you are using the &wide, select
.us Emit Browser Information
from the
.us Debugging Switches
panel of the
.us Compiler Switches
dialog.
The &br module file will have the same name as the source file and
an extension of ".MBR".
.np
Once the &br module files have been created, these files are merged
and a &br database file is created.
This process eliminates redundant information such as duplicate
definitions that occur when a header file is included by many source
files.
Browser database files have the extension ".DBR".
.np
The &br allows you to configure your session and saves this
configuration to an options file.
Options files have the extension ".OBR".
The file name
.fi setup.obr
is the default name of the options file.
The default options file is automatically loaded by the Browser when
the Browser is started.
.*
.beglevel
.*
.section Creating a Browser Database File within the Browser
.*
.ix '&br' 'create database file'
.ix 'database file' 'create in &br'
.begstep
.step Choose
.us New
from the
.us File
menu.
.result
This opens the
.us New Browser File
dialog where you enter the name of the Browser database file you are
creating.
.figure *depth='1.32' *scale=56 *file='brow1' Use the New Browser File dialog to create a new Browser database file.
.step Type the name and path
of the new Browser database file.
.orstep Click on the
.us Files
button to open a second dialog that allows you to browse the directory
structure for an existing Browser database file.
Select an existing file and change its name.
If you do not change its name, a message box appears when you press
.us OK
asking if you want to overwrite the
existing file.
.step Click on
.us OK.
.result
This opens a
.us Module
window that will eventually contain a list of the module files that
will make up the database file.
.step Click on the
.us Add
button in the
.us Module
window.
.result
This opens the
.us Select Module File(s)
dialog where you choose the module files to add to the database file.
.step Select the module files
to add to the database file and click on
.us OK.
.orstep Double click
on the desired module file.
.result
This closes the
.us Select Module File(s)
dialog and adds the selected module file to the Browser file component
list.
Each module file on the components list has a check box.
When added, this check box is marked with an X, indicating that the
module file is enabled.
.step Continue with steps 4 and 5
until you have added all desired module files to the component list.
.figure *depth='2.32' *scale=52 *file='brow2' The Modules dialog displays the selected module files.
.step Click on
.us OK
on the
.us Module
window.
.result
This closes the
.us Module
window and creates the database file.
.endstep
.*
.section Creating a Browser Database File from the Command Line
.*
.np
.ix '&br' 'create database file from command line'
.ix 'database file' 'create from command line'
It is also possible to create the Browser database file from the
command line.
This allows you to make Browser database file creation
part of your standard build procedure.
When you do this, the batch build
procedure will automatically update your database file.
Updating the Browser database file occurs only if changes have been
made to a module file within the database file.
.np
.ix '&br' 'merger utility'
.ix 'merger' 'with &br'
A separate utility, called the merger, is used to create the database
file.
The name of the merger program is
.fi wbrg.exe.
.ix 'MBR files'
Its command line consists of the name of the database file and a list
of the module files (.MBR files) to be merged.
The name of the database file must be preceded by a
.mono database
command.
.ix 'DBR files'
The default extension given to the database file is ".DBR".
The list of module files must be preceded by a
.mono file
command.
The module file names must be separated by commas or enclosed by curly
braces and separated by spaces.
The list of module file names can contain wild cards.
The following are examples of valid merger commands.
In each case, the module files
.fi m1.mbr
and
.fi m2.mbr
will be processed and the database file
.fi db.dbr
will be created.
.millust begin
wbrg database db file m1, m2
wbrg database db file { m1 m2 }
wbrg file m1, m2 database db
wbrg file { m1 m2 } database db
.millust end
.np
It is also possible to specify a command file that contains merger
commands.
.ix 'CBR files'
Command files have the extension ".CBR".
Consider a command file, called
.fi merge.cbr,
containing the following merger commands.
.millust begin
database db
file m1
file m2
.millust end
.np
The following example will achieve the same results as the previous
example.
.millust begin
wbrg @merge
.millust end
.np
.ix 'merger' 'quiet option'
.ix 'quiet option'
If you want to suppress the listing of file names that the merger
produces as it is working, you can include the "quiet" option on the
command line or in the command file.
.*
.section Opening an Existing Browser Database File
.*
.ix '&br' 'open database file'
.ix 'database file' 'open in &br'
.ix 'open' 'database file in &br'
.begstep
.step Choose
.us Open
from the
.us File
menu.
.result
This opens the
.us Open Browser Database File
dialog where you select the database file you want to open.
.step Select a database file to open and click on
.us OK.
.orstep Double click
on the desired database file.
.result
This closes the
.us Open Browser Database File
dialog.
.begnote
.mnote Note:
You can have only one database file open at a time.
If you open a second database file, the &br discards the first and
displays information for the second.
.endnote
.endstep
.*
.section Working with Browser Module Files
.*
.np
.ix 'Module file' 'in &br'
.ix '&br' 'working with module files'
Once a Browser database file is loaded, you might want to edit the list
of modules originally used to create the database file.
Editing the list of modules allows you to temporarily remove modules
from the database or add modules to the database.
For example, you may decide that you only want to browse a particular
module or set of modules or you may have forgotten a module when the
database was originally created.
.np
The
.us Modules
menu item in the
.us File
menu allows you to view the list of module files that make up the
current database file.
From this list you can perform the following functions on the module
files:
.begbull $compact
.bull
Add
.bull
Remove
.bull
Disable
.bull
Enable
.endbull
.figure *depth='2.32' *scale=52 *file='brow3' On the Modules dialog, you can add, remove, disable, and enable module files.
.*
.beglevel
.*
.section Adding a Module File
.*
.ix '&br' 'add Module file'
.ix 'Module file' 'add in &br'
.begstep
.step Choose
.us Modules
from the
.us File
menu.
.result
This opens the
.us Modules
dialog for the current database file.
This dialog lists all module files that make up the database file.
Each module file has a check box.
An X in this box indicates that the module file is enabled.
The &br browses only the enabled module files.
.step Click on the
.us Add
button in the
.us Modules
dialog.
.result
This opens the
.us Select Module File(s)
dialog where you choose the module files to add to the current Browser
file.
.step Select the module files
to add to the Browser file and click on
.us OK.
Select multiple module files by holding the Shift key while
you click on the desired files.
.result
Clicking on OK closes the
.us Select Module File(s)
dialog and adds the selected module file to the database file.
Each module file in the module list has a check box.
When added, this check box is marked with an X, indicating that the
module file is enabled.
.step Continue with steps 2 and 3
until you have added all desired module files to the component list.
.step Click on
.us OK
in the
.us Module
dialog.
.result
This closes the
.us Modules
dialog and updates the database file.
.endstep
.*
.section Removing a Module File
.*
.begstep
.step Choose
.us Modules
from the
.us File
menu.
.result
This opens the
.us Modules
dialog for the current database file.
This dialog lists all module files that make up the database file.
Each module file has a check box.
An X in this box indicates that the module file is enabled.
The &br browses only the enabled module files.
.step Click once on the module file
you want to remove from the database file.
.result
This highlights the selected module file.
.step Click on the
.us Remove
button in the
.us Modules
dialog.
.result
This removes the selected module file from the list.
.step Click on
.us OK
in the
.us Modules
dialog.
.result
This closes the
.us Modules
dialog and updates the database file.
.endstep
.*
.section Disabling a Module File
.*
.ix '&br' 'disable module file'
.ix 'Module file' 'disable in &br'
.begstep
.step Choose
.us Modules
from the
.us File
menu.
.result
This opens the
.us Modules
dialog for the current database file.
This dialog lists all module files that make up the database file.
Each module file has a check box.
An X in this box indicates that the module file is enabled.
The &br browses only the enabled module files.
.step Click in the check box
of the module file you want to disable.
Alternatively, use the up and down arrow keys to select the module file
you wish to disable.
Press the space bar to disable the currently selected module file.
.result
This removes the X.
The blank box indicates that the module file is disabled and will not
be browsed.
.step Repeat step 2
until you have disabled all desired module files.
.step Click on
.us OK
on the
.us Modules
dialog.
.result
This closes the
.us Modules
dialog and updates the database file.
.endstep
.np
To disable all of the module files in the
.us Modules
dialog, click on the
.us Disable All
button.
Click on
.us OK
to update the database file and close the
.us Modules
dialog.
.*
.section Enabling a Module File
.*
.begstep
.step Choose
.us Modules
from the
.us File
menu.
.result
This opens the
.us Modules
dialog for the current database file.
This dialog lists all module files that make up the database file.
Each module file has a check box.
An X in this box indicates that the module file is enabled.
The &br browses only the enabled module files.
.step Click in the check box
of the module file you want to enable.
Alternatively, use the up and down arrow keys to select the module file
you wish to enable.