wbr.gml

来自「开放源码的编译器open watcom 1.6.0版的源代码」· GML 代码 · 共 1,349 行 · 第 1/4 页

.* Pictures follow this informal code for naming:
.*
.*  BR<name>
.*  ^
.*  |
.*  |
.*  +---- 2 letter constant meaning Browser
.*
:set symbol='wbrname'   value='Open Watcom Browser'
:set symbol='brname'    value='browser'
:set symbol='wbrcmd'    value='wbr'
:set symbol='wbrcmdup'  value='WBR'
:set symbol='wbrwarnd'  value='-w'
:set symbol='wbrfile'   value='.WBR file'
:set symbol='mbrfile'   value='.MBR file'
.*
:set symbol='vmakenm' value='Open Watcom Visual Make'
.*
:set symbol='compname'  value='Open Watcom C/C++ Compiler'
:set symbol='compcmd'   value='wcc'
:set symbol='compcmdup' value='WCC'
:set symbol='genbrflag' value='-B??'
.*
:set symbol='edname'    value='Open Watcom Editor'
:set symbol='edcmd' value='vi'
:set symbol='edcmdup'   value='VI'
.*
.chap The &wbrname
.*
.section Introduction
.*
.np
In the course of developing software, a programmer will typically define and
use thousands of symbols representing variables, functions, and types. spread
amongst many source files.  Given this situation, the &wbrname has two
overlapping purposes:
.*
.begbull
.bull
To speed up a developer's navigation through symbol definitions and usage.
.bull
To assist a developer in understanding the structure of the software.
.endbull
.*
.np
The &brname cooperates with the &edname, the &compname, and the &vmakenm to
achieve these goals.  For example, a programmer editing a file can highlight a
word in the text, and the &brname will create a detail window describing that
symbol. The detail window can be used as a starting point to find out more
about the symbol, or the browser can direct the editor to load and position a
file to the point at which the symbol is defined and/or referenced.
Alternatively, the developer can work with the &brname directly; various
filters and pattern matching tools can be used to build queries for finding
symbols and creating reports on an application-wide basis.
.*
.np
To further assist the developer, the &brname can display class hierarchies,
function call trees, and nested structure types.  Hypertext style symbol
information simplifies the investigation relationships between symbols; any
time the browser displays the name of a user defined symbol, that name can be
used as the starting point for another query. Fast access to project
information can be set up easily, since any information that the &brname
displays can be kept on-screen or minimized for reference.
.*
.section General Concepts
.*
.np
&wbrname is a source code browser.  This means that all of its information is
generated by the compiler as it processes source code.  Although this
information has much in common with debugging information, it is structured
to support navigation through source files, without the presence of an
executable program. While this static view provides much useful
information, dynamic information that would be available to a debugger is
beyond this product's scope.  Information not available includes:
.*
.begbull
.bull
the current execution point of a running program, and the path that was
taken to get there.
.bull
the values of variables
.endbull
.*
Information that is available includes:
.*
.begbull
.bull
all variables, types, macros, functions, labels defined or declared in an application.
.bull
the source file location of the definition and declaration of those symbols.
.bull
the type of any function or variable.
.bull
all calls of any function (except where the call is through a function pointer).
.bull
all variables that are of a given type (including function parameters).
.bull
all symbols visible in a given scope.
.bull
all structures that contain a given type.
.bull
all functions that use a given variable, macro, or function.
.bull
all goto points for a given label.
.bull
all catches (exception handlers) that have been defined for a given type (or for it's base types).
(not implemented)
.bull
all throws (exception raisers) that may throw an exception of a given type.
(not implemented)
.bull
all data members, member functions, friends, base classes and derived
classes of a given class/struct/union
.bull
the recursive decomposition of any derived type into its component types
.bull
the possible values that have been defined for an enumeration type.
.bull
the definition of a given macro.
.bull
the relationship between class and function templates and their instantiations.
(not implemented)
.endbull
.*
.np
The database of symbol information to support these facilities is generated
by the &compname as it compiles the source and headers into object files.
These module browse files can be loaded and unloaded  from a browse session.
This allows for browsing symbols that are not currently part of the project
(such as an external class library), and for the disabling of modules in the
project that are not currently of interest.
.*
.np
The collection of module browse files for a given browse session may be saved
in a '.wbr' (Watcom BRowse) project file.  This file contains a
references to each of the pertinent '.mbr' (Module BRowse) files.  Project
browse files may be used to create different sub-views of the project, each
composed of a different set of modules.
.*
.section Operating System Considerations
.*
.np
Release 1.0 of &wbrname is supported only under Microsoft Windows version 3.1 or
later. However, any &compname can produce the appropriate format of
data for browsing by the Windows hosted browser.  Future versions are planned
for all environments that these compilers support.
.*
.*
.section &brname Command Line Format
.*
.np
:I1.&brname command line:I2.format
The formal &brname command line syntax is shown below.
:I1.&wbrcmdup command line:I2.invoking &wbrcmdup
:I1.command line format:I2.&wbrcmdup
.mbigbox
&wbrcmdup [options] [file]
.embigbox
.begpoint
.point options
is a list of valid &brname options, each preceded by a slash
("/") or a dash ("&minus."). Options may be specified in any order.
Currently, only one option has been defined:
.*
.begpoint $break $compact
:opt name='&wbrwarnd'.=<duplicate_warning>
enable warning messages regarding duplicate definitions of global symbols.
This comes into affect when loading symbols from a &mbrfile, and definitions
are encounter for symbols that already have definitions.  The new definitions
are discarded regardless of the state of this flag.
.*
.endpoint
.*
.*
.point file
is the path and name of the '.wbr' project browse file.
.endpoint
.*
.section Getting Started
.*
.np
&wbrname release 1.0 must be initiated from within Microsoft Windows 3.x.
.*
.np
Startup can be be done in two ways, resulting in two different operating
modes.  One alternative is to start and configure the browser directly.  The
other alternative is to rely upon &vmakenm to start and configure the &brname for
the current project target.
.*
.np
In either mode, &brname will present itself in the upper left of the screen as
shown in
:figref refid='brstart'..
See section(File/Modules) for a
description of loading manually generated modules into the browser session.

:fig id='brstart' frame=box place=inline.
:graphic depth='0.5i'
    file='brstart.eps'
:figcap.&brname Startup Screen
:efig.
.*
.*
.beglevel
.section Standalone Mode
.*
.np
In this mode, the developer must use the &compname directly to build browse
files for modules of interest, and must use browser menus to explicitly load
them into the browser's list of modules.
.*
.np
In order to browse a piece of source code, it must first be compiled by the
&compname, using the &genbrflag (generate browse info) flag:
.*
.millust begin
&compcmdup &genbrflag [<browse_file>] [<other flags>] <source_file>
.millust end
.*
.np
This will result in the compiler generating a &mbrfile containing all of
the symbols encountered in the source file and in its included files.  It
will have the name of the <browse_file> argument, if supplied;
otherwise, it will have the same base name as the target object file, with an
".mbr" suffix.
.*
.np
Any number of modules may compiled this way for future browsing. However, be
aware that the browser acts like a linker, in that it will discard any
conflicting or redundant definitions of global symbols. Normally this is not
an issue, since the modules of an application must meet this condition
anyway.  It may be a problem if &mbrfiles are generated from some external
source that contains conflicting global symbol names.  In this case, only the
first version of the symbol definition loaded into the browser will be kept
(see section(Command Line Format)).
.*
.np
Once the desired '.mbr' files have been generated, they must be loaded into an
active browse session.
.*
.np
&brname may be started up with no command line arguments (see section(Command
Line Format)). For convenient access within windowed environments, &brname
should be set up as a window manager icon. (Refer to the documentation for
your window system, Eg: Microsoft Window Manager.).
.*
.np
Once the browser is running, the compiler-generated &mbrfile.s must be loaded
into the browse session, using the 'edit project' dialog, accessed from the
file/modules menu item (see section(File/Modules) for more details).
.*
.np
.bi Note:
In standalone mode, &brname will attempt to start up the &edname to display
source file definitions of symbols. In order for this to succeed, the &edname
must be in the current search path.
.*
.section Slave Mode
.*
.np
In this mode, &vmakenm automatically compiles modules with the proper flag for
generating &mbrfile.s as it attempts to build a target (see chapter
(&vmakenm.(?))). When a browse query originates from &vmakenm or from one of
it's slave editor sessions, &vmakenm will start &brname (if it is not
already running as a slave) and load it with the list of the &mbrfile.s for
the current target, then finally passing on the query.
.*
.np
For further details on the use of &vmakenm and its relationship the with
the compiler, editor and browser, see chapter (&vmakenm.(?))

.*
.np
When &brname is first started up by &vmakenm, it will be minimized.  Although
the results of &edname queries will be displayed in independent windows, the
&wbrname icon must first be restored if access to the menu bar is desired.
.*
.endlevel
.*
.section General Interaction
.*
.np
&brname follows the conventions of the Common User Access(?) specification for
user interactions.  However, it has a few unusual features that tend to
recur within its user interface.  These features are generally intended to
facilitate arbitrary browse paths and quick reference, while co-existing
with an integrated development environment.
.*
.beglevel
.section Popup Children Windows
.*
.np
The most obvious of these features is that all of the &brname windows are free
floating windows, not contained within a parent window. This allows arbitrary
details of project symbol data to be displayed where convenient, or to be
minimized for fast access.
.*
.np
The main window and its menu bar will always be present (though it may be
minimized).  All other windows generated in the course of a browse session
may be sized, minimized, maximized, and moved independently of the main
window, with the following considerations:
.*
.begbull
.bull
all &brname windows will always appear in front of the main window.
.bull
all &brname windows (apart from the main window) are peers of each other, and
may appear in front or behind of each other, depending on order of creation
and current focus.
.bull
if the main window is minimized, all windows created while it was displayed
will also be minimized.  If any of these windows are already minimized, its
icon will disappear until the main window icon is restored.
.bull
editor queries may result in the creation of &brname windows while the main
window is already minimized.
.endbull
.*
.section PushPin Windows
.*
.np
Many of the &brname windows are pushpin windows.  These may be recognized by the
pushpin button visible on the left end of the window's title bar.  The
purpose of the push pin is to provide some degree of window-to-window
coordination, to avoid the disorganization that might otherwise occur with
many independent windows.
.*
.np
A pushpin window is either 'pinned' to another window, or it is unattached.
This is indicated by the icon on the pushpin button;  see
:figref refid='pushicon'..
.*
.np
If a window is pinned to another window, it may be considered 'owned' by
 that other window.  In this state:
.begbull
.bull