womp.gml

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

.chap The Object Module Processor
.*
.section Converting &company Object Files To Other Formats
.*
.np
.ix 'debugging information'
.ix '&company object files'
.ix 'Microsoft object files'
.ix 'Phar Lap Easy OMF-386 object files'
.ix 'object files' '&company'
.ix 'object files' 'Microsoft'
.ix 'object files' 'Phar Lap Easy OMF-386'
When one of the "d1" or "d2" compiler options is used, a &company
compiler will include debugging information in object files.
This debugging information can be utilized by the &lnkname and the
&dbgname..
Unfortunately, since there is no standard for the representation of
debugging information in executable applications, &company's debugging
information cannot be processed by other linkers or debuggers.
A utility program is provided that may be used to convert the
debugging information present in object files created by a &company
compiler to various formats acceptable by other linkers and debuggers.
.ix '&company debugging information'
.ix 'Microsoft CodeView debugging information'
.ix 'MetaWare debugging information'
.ix 'Turbo debugging information'
.ix 'debugging information' '&company'
.ix 'debugging information' 'Microsoft CodeView'
.ix 'debugging information' 'MetaWare'
.ix 'debugging information' 'Turbo'
.ix 'WOMP'
This utility program is called "WOMP"
(&company Object Module Processor).
.np
The format of the WOMP command line is:
.ix 'WOMP' 'command line format'
.ix 'command line format' 'WOMP'
.mbigbox
WOMP [options]* file [options|file]*
.embigbox
.pc
The square brackets [ ] denote items which are optional.
.begpoint
.mnote options
is a list of valid WOMP options, each preceded by a slash ("/") or a
dash ("&minus.").
Options may be specified in any order.
Options are described below.
.mnote file
is a file specification which can include wild cards in the file name
and extension parts.
A file specification takes the form:
.begpoint
.mnote d:
is an optional drive specification such as "A:", "B:", etc.
If not specified, the default drive is assumed.
.mnote path
is an optional path specification such as "\PROGRAMS\EXE\".
If not specified, the current directory is assumed.
.mnote file
is the file name of the object or library file.
The file name may contain an "*" wild card.
.mnote ext
is the file extension of the object or library file.
The file extension may contain an "*" wild card.
.endpoint
.np
The output object or library file will have the same name as the input
object or library file.
The object or library file extension will default to the input object
or library file extension.
.endpoint
.np
Temporary files are used by WOMP to contain the intermediate object
or library file during processing.
The temporary files used follow the naming convention "_Wn.TMP" where
.id n
is a decimal number starting at zero (maximum is 65535).
.*
.section WOMP Options Summary
.*
.np
Options must precede the file(s) you wish them to affect.
The options marked "*" are the default ones.
.*
.begnote $break $compact
.*
:opt name='&sw.o'.=spec
Output filename/directory specification
:opt name='&sw.fm'.
*Generate Microsoft 16- and 32-bit object files
:opt name='&sw.fm2'.
*Generate Microsoft object files for OS/2 2.0.
:opt name='&sw.fp'.
Generate Phar Lap Easy OMF-386 32-bit object files
:opt name='&sw.f-'.
Do not generate an object file (useful with /dx)
:opt name='&sw.dm'.
*Generate Microsoft CodeView debugging information
:opt name='&sw.dp'.
Generate Phar Lap/MetaWare debugging information
:opt name='&sw.dt'.
Generate Turbo debugging information
:opt name='&sw.dx'.
Generate human-readable text to console
:opt name='&sw.d-'.
Do not generate any debugging information
:opt name='&sw.pw'.
*Parse &company debugging information
:opt name='&sw.p7'.
Parse &company C 7.0 debugging information
:opt name='&sw.p-'.
Do not attempt to parse any debugging information
:opt name='&sw.q'.
Operate quietly
:opt name='&sw.b'.
Leave temporary files and output batch file commands
.endnote
.np
The following options apply to .WMP files.
.*
.begnote $break $compact
.*
:opt name='@'.file
Read file[.WMP] for options
:opt name='#'.
Ignore from # to end of line (comment)
.endnote
.*
.cp 10
.section Description of WOMP Options
.*
.begnote $break
.*
:opt name='&sw.o'.=spec
Output filename/directory specification
.np
The output directory, filename, and/or default extension may be
specified.
If this option is not specified, then WOMP will overwrite the original
object file.
.exam begin
C>rem specify a new file name
C>womp /o=new myobj
C>rem specify a new extension
C>womp /o=.mbj myobj
C>rem specify a default directory and extension
C>womp /o=\tmp\.mbj myobj
.exam end
.np
A '#' may be used in place of '=' (for use with the operating system
shell's "SET" command and BAT files).
:opt name='&sw.fm'.
Generate Microsoft 16- and 32-bit object files
.np
The default action is to convert 16- and 32-bit &company object file
formats to Microsoft 16- and 32-bit object file formats.
If the input object file is a 16-bit file, then the output is
guaranteed to be a 16-bit object file.
.np
The "dx" option may be used in conjunction with this option.
:opt name='&sw.fm2'.
Generate Microsoft 16- and 32-bit object files for OS/2 2.0
.np
Optionally, WOMP can convert 16- and 32-bit &company object file
formats to OS/2 2.0 16- and 32-bit object file formats.
If the input object file is a 16-bit file, then the output is
guaranteed to be a 16-bit object file.
.np
The "dx" option may be used in conjunction with this option.
:opt name='&sw.fp'.
Generate Phar Lap Easy OMF-386 32-bit object files
.np
Optionally, WOMP can convert 16- and 32-bit &company object file
formats to Phar Lap Easy OMF-386 32-bit object file formats.
If the input object file is a 16-bit file, WOMP does its best to
convert it to a Phar Lap object file.
This results in USE16 segments, possibly with improper access rights.
See Phar Lap documentation for more information.
.np
The "dx" option may be used in conjunction with this option.
:opt name='&sw.f-'.
Do not generate an object file (useful with &sw.dx)
.np
The object file is not converted to any other format.
:opt name='&sw.dm'.
Generate Microsoft CodeView debugging information
.np
The default action is to convert &company debugging information
to Microsoft CodeView debugging information.
:opt name='&sw.dp'.
Generate Phar Lap/MetaWare debugging information
.np
Optionally, WOMP can convert &company debugging information to
Phar Lap/MetaWare debugging information.
This debugging format is a small variation on Microsoft format.
Some programs that accept output from a MetaWare compiler will require
a Phar Lap object file (specify &sw.fp).
:opt name='&sw.dt'.
Generate Turbo debugging information
.np
Optionally, WOMP can convert &company debugging information to Borland's
Turbo debugging information.
:opt name='&sw.dx'.
Generate human-readable text to console
.np
Optionally, WOMP can display &company debugging information in a
human-readable representation (see subsequent section for example).
:opt name='&sw.d-'.
Do not generate any debugging information
.np
The symbolic debugging information in the object file is omitted from
the output object file.
If the input file contained symbolic debugging information it will be
lost.
Line numbering information will remain.
:opt name='&sw.pw'.
Parse &company debugging information
.np
By default, WOMP will process the debugging information in an object
file created by &company C 8.0 or later.
:opt name='&sw.p7'.
Parse &company C 7.0 debugging information
.np
Optionally, WOMP can process the debugging information in an object
file created by &company C 7.0.
:opt name='&sw.p-'.
Do not attempt to parse any debugging information
.np
If this option is specified, then no attempt is made to interpret the
object file's contents.
However, WOMP's object file rearrangements still occur.
For example, to convert a &company 32-bit object file from Phar Lap
format into a Microsoft 32-bit object file, one could issue the
command:
.exam begin
WOMP &sw.d- &sw.p- file.obj
.exam end
.pc
If the &sw.d- is not specified, then artifacts of another debugging
generator could result (e.g., the Microsoft generator would output
some extra COMENT records).
:opt name='&sw.q'.
Operate quietly
.np
No informational messages are displayed.
:opt name='&sw.b'.
Leave temporary files and output batch file commands
.np
The "b" option is useful when the size of a library is too large
for &libcmdup to handle when it is executed by WOMP.
The "b" option will leave temporary files and output
the appropriate batch file commands to accomplish the
necessary file manipulations.
.exam begin
C>WOMP &sw.b large.lib >doit.bat
C>doit
.exam end
.endnote
.np
The following options apply to .WMP files.
.*
.begnote $break
.*
:opt name='@'.file
Read file[.WMP] for options
.np
WOMP will attempt to access the environment variable "file"; if that
does not exist it will open the file named "file".
The default file extension used is ".WMP".
The contents of the file/environment variable will be inserted at the
point of the @file command.
:opt name='#'.
Ignore from # to end of line (comment)
.np
This can be used for comments in ".WMP" files.
WOMP ignores all text following a "#" up to the end of the line.
.endnote
.*
.section WOMP Environment Variable
.*
.np
The
.ev WOMP
environment variable can be used to specify commonly used WOMP
options.
These options are processed before options specified on the command
line.
.ix '&setcmdup' 'WOMP environment variable'
.exam begin
&prompt.&setcmd &setdelim.WOMP=&sw.fp &sw.dp&setdelim
.exam end
.pc
The above example defines the default WOMP options to be "fp" and
"dp".
.np
.ix 'environment string' '= substitute'
.ix 'environment string' '#'
Whenever you wish to specify an option that requires the use of an
"=" character, you can use the "#" character in its place.
This is required by the syntax of the "&setcmdup" command.
.np
Once the
.ev WOMP
environment variable has been defined, those options listed become the
default each time the
.kw WOMP
command is used.
The WOMP command line can be used to override any options specified in
the environment string.
.hint
.if '&target' eq 'QNX' .do begin
.ix 'user initialization file'
If you use the same compiler options all the time, you may find it
handy to place the "&setcmd WOMP" command in your user
initialization file.
.do end
.el .do begin
.ix 'system initialization file' 'AUTOEXEC.BAT'
.ix 'AUTOEXEC.BAT' 'system initialization file'
If you are running DOS and you use the same WOMP options all the time,
you may find it handy to place the "&setcmdup WOMP" command in your
DOS system initialization file,
.fi AUTOEXEC.BAT.
.np
.ix 'system initialization' 'Windows NT'
.ix 'Windows NT' 'system initialization'
If you are running Windows NT, use the "System" icon in the
.bd Control Panel
to define environment variables.
.np
.ix 'system initialization file' 'CONFIG.SYS'
.ix 'CONFIG.SYS' 'system initialization file'
If you are running OS/2 and you use the same WOMP options all the
time, you may find it handy to place the "&setcmdup WOMP" command
in your OS/2 system initialization file,
.fi CONFIG.SYS.
.do end
.ehint
.*
.section Input Object File Processing
.*
.np
WOMP can process most object files generated by MS/DOS compilers and
assemblers.
Specifically, WOMP handles:
.begbull
.bull
Microsoft's variant on Intel 16-bit object files.
.bull
Microsoft style 32-bit object files (Xenix object format).
.bull
Phar Lap Easy OMF-386 object files.
.endbull
.np
There is no need to tell WOMP the style of an input object file since
the formats are distinguishable from one another.
.*
.section Output Object File Processing
.*
.np
To properly do some of the debugging conversions, WOMP must rearrange
some records within the object file.
WOMP places all PUBDEFs before the first LEDATA/LIDATA record.
Additionally, all EXTDEFs and COMDEFs are placed before the first
PUBDEF.
These changes are benign for the most part.
However, some compilers write COMENT records that are supposed to
refer to the next EXTDEF/COMDEF/PUBDEF.
In this case the COMENT records will be out of place, and the object
file may not be useable.
.*
.section Using WOMP with &company Compilers
.*
.np
Specify "&sw.d2" on the compiler command line (after any optimization
options) to generate &company symbolic information.
Then use WOMP on the resulting object file.
.np
The default external naming convention for &company C functions is
"name_" where "name" is the name of a function.
Some debuggers (e.g., CodeView) will expect "_name" and will not
recognize a command referencing the symbol "name".
To work around this problem you must use "name_" whenever referring to
a function (e.g., "go main_")
.np
The default external naming convention for &company FORTRAN functions is
.bd ALL UPPERCASE.
So, you can use "go FMAIN" to begin a FORTRAN program.
.np
&company parameter passing is described in the "User's Guide".
There is no support for registerized parameters in Microsoft/MetaWare
debugging information.
Debuggers working with a &company program might get confused as to the
location of parameters and display random values.
This should not occur after the function prolog has been executed
(i.e., the variables should be available on the first line of code in
any function).
In particular, CodeView's "Calls" menu will not show valid parameters.
.*
.section Using Microsoft CodeView with WOMP
.*
.np
Note that CodeView supports debugging of 16-bit applications only.
It does not support 32-bit applications.
.np
Unfortunately, CodeView does not understand the entire Microsoft
Debugging format.
The most noticeable area is typedefs.
WOMP makes an attempt to resolve any problems CodeView will have with
typedefs.
The result is that types will be displayed in their most basic form
while in CodeView (all typedefs are stripped).
.np
The Microsoft Debugging format does not have a "pointer to void" type
in it.
Pointers to void are treated as pointers to char for debugging
purposes.
.np
Some FORTRAN types (notably CHARACTER *(*) SAM, and REAL A(1:M))
cannot be converted to Microsoft format because of code generation
differences.
A warning will be issued in this case.
.*
.section Using the Borland Turbo Debugger with WOMP
.*
.np
Note that the Turbo Debugger supports debugging of 16-bit applications
only.
It does not support 32-bit applications.