cpopts.gml

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

.id WinMain
and
.id wWinMain
are significant
:optref refid='SWbc'..
.ix 'macros' '__SW_BW'
The macro
.kwm __SW_BW
will be predefined if "bw" is selected.
.if '&target' eq 'QNX' .do begin
This option does not apply to QNX.
.do end
.do end
.*


.if &e'&$SWof eq 1 .do begin
:OPT refid='SWof' name='of'.
.ix 'options' 'of'
This option selects the generation of traceable stack frames for those
functions that contain calls or require stack frame setup.
.np
&286only.
To use &company's "Dynamic Overlay Manager" (DOS only), you must
compile all modules using one of the "of" or "of+" options ("of" is
sufficient).
.np
For near functions, the following function prologue sequence is
generated.
.millust begin
&286only.
    push BP
    mov  BP,SP

&386only.
    push EBP
    mov  EBP,ESP
.millust end
.pc
For far functions, the following function prologue sequence is
generated.
.millust begin
&286only.
    inc  BP
    push BP
    mov  BP,SP

&386only.
    inc  EBP
    push EBP
    mov  EBP,ESP
.millust end
.pc
The BP/EBP value on the stack will be even or odd depending on the
code model.
.np
For 16-bit DOS systems, the Dynamic Overlay Manager uses this
information to determine if the return address on the stack is a short
address (16-bit offset) or long address (32-bit segment:offset).
.np
Do not use this option for 16-bit Windows applications.
.ix '_export functions'
It will alter the code sequence generated for "_export" functions.
.exam begin 1
&prompt.:SF font=1.compiler_name:eSF. toaster &sw.of
.exam end
.np
.ix 'macros' '__SW_OF'
The macro
.kwm __SW_OF
will be predefined if "of" is selected.
.do end
.*
.if &e'&$SWofpls eq 1 .do begin
:OPT refid='SWofpls' name='of+'.
.ix 'options' 'of+'
This option selects the generation of traceable stack frames for all
functions regardless of whether they contain calls or require stack
frame setup.
This option is intended for developers of embedded systems (ROM-based
applications).
.np
To use &company's "Dynamic Overlay Manager" (16-bit DOS only), you
must compile all modules using one of the "of" or "of+" options ("of"
is sufficient).
.np
For near functions, the following function prologue sequence is
generated.
.millust begin
&286only.
    push BP
    mov  BP,SP

&386only.
    push EBP
    mov  EBP,ESP
.millust end
.pc
For far functions, the following function prologue sequence is
generated.
.millust begin
&286only.
    inc  BP
    push BP
    mov  BP,SP

&386only.
    inc  EBP
    push EBP
    mov  EBP,ESP
.millust end
.pc
The BP/EBP value on the stack will be even or odd depending on the
code model.
.np
For 16-bit DOS systems, the Dynamic Overlay Manager uses this
information to determine if the return address on the stack is a short
address (16-bit offset) or long address (32-bit segment:offset).
.np
Do not use this option for 16-bit Windows applications.
.ix '_export functions'
It will alter the code sequence generated for "_export" functions.
.exam begin 1
&prompt.:SF font=1.compiler_name:eSF. toaster &sw.of+
.exam end
.do end
.*
.if &e'&$SWsg eq 1 .do begin
:OPT refid='SWsg' name='sg'.
.ix 'stack growing'
.ix 'options' 'sg'
This option is useful for 32-bit OS/2 and Win32 multi-threaded
applications.
It requests the code generator to emit a run-time call at the start of
any function that has more than 4K bytes of automatic variables
(variables located on the stack).
.np
.ix 'guard page'
.ix 'primary thread'
.ix 'threads' 'growing the stack'
.ix 'guard page'
Under 32-bit OS/2, the stack is grown automatically in 4K pages for
any threads,
other than the primary thread, using the stack "guard page" mechanism.
The stack consists of in-use committed pages topped off with a special
guard page.
A memory reference into the 4K guard page causes the operating system
to grow the stack by one 4K page and to add a new 4K guard page.
This works fine when there is less than 4K of automatic variables in a
function.
When there is more than 4K of automatic data, the stack must be grown
in an orderly fashion, 4K bytes at a time, until the stack has grown
sufficiently to accommodate all the automatic variable storage
requirements.
Hence the requirement for a stack-growing run-time routine.
.ix '__GRO' 'stack growing'
The stack-growing run-time routine is called
.id __GRO.
.np
The "stack=" linker option specifies how much stack is available and
committed for the primary thread when an executable starts.
The stack size parameter to
.mono _beginthread()
specifies how much stack is available for a child thread.
The child thread starts with just 4k of stack committed.
The stack will not grow to be bigger than the size specified by the
stack size parameter.
.np
Under 32-bit Windows (Win32), the stack is grown automatically in 4K
pages for all threads using a similar stack "guard page" mechanism.
The stack consists of in-use committed pages topped off with a special
guard page.
The techniques for growing the stack in an orderly fashion are the
same as that described above for OS/2.
.np
The "stack=" linker option specifies how much stack is available for
the primary thread when an executable starts.
The "commit stack=" linker directive specifies how much of that stack
is committed when the executable starts.
If no "commit stack=" directive is used, it defaults to the same value
as the stack size.
The stack size parameter to
.mono _beginthread()
specifies how much stack is committed for a child thread.
If the size is set to zero, the size of the primary thread stack is
used for the child thread stack.
When the child thread executes, the stack space is not otherwise
restricted.
.np
.ix 'macros' '__SW_SG'
The macro
.kwm __SW_SG
will be predefined if "sg" is selected.
.do end
.*
.if &e'&$SWst eq 1 .do begin
:OPT refid='SWst' name='st'.
.ix 'stack touching'
.ix 'options' 'st'
This option causes the code generator to ensure that the first reference
to the stack in a function is to the stack "bottom" using the SS register.
If the memory for this part of the stack is not mapped to the task, a
memory fault will occur involving the SS register.
This permits an operating system
to allocate additional stack space to the faulting task.
.np
Suppose that a function requires 100 bytes of stack space.
The code generator usually emits an instruction sequence to reduce the
stack pointer by the required number of bytes of stack space, thereby
establishing a new stack bottom.
When the "st" option is specified, the code generator will ensure
that the first reference to the stack is to a memory location
with the lowest address.
If a memory fault occurs, the operating system can determine that it
was a stack reference (since the SS register is involved) and also
how much additional stack space is required.
.np
See the description of the "sg" option for a more general solution to
the stack allocation problem.
.ix 'macros' '__SW_ST'
The macro
.kwm __SW_ST
will be predefined if "st" is selected.
.do end
.*
.if &e'&$SWzw eq 1 .do begin
:OPT refid='SWzw' name='zw'.
.ix 'options' 'zw'
&286only.
This option causes the compiler to generate the prologue/epilogue code
sequences required for Microsoft Windows applications.
.ix '_export functions'
.ix 'pascal functions'
The following "fat" prologue/epilogue sequence is generated for any
functions declared to be "far _export" or "far pascal".
.millust begin
far pascal func(...)
far _export func(...)
far _export pascal func(...)

    push DS
    pop  AX
    nop
    inc  BP
    push BP
    mov  BP,SP
    push DS
    mov  DS,AX
    .
    .
    .
    pop DS
    pop BP
    dec BP
    retf n
.millust end
.np
.ix 'macros' '__WINDOWS__'
.ix '__WINDOWS__'
The macro
.kwm __WINDOWS__
will be predefined if "zw" is selected.
.np
&386only.
This option causes the compiler to generate any special code sequences
required for 32-bit Microsoft Windows applications.
.ix 'macros' '__WINDOWS__'
.ix 'macros' '__WINDOWS_386__'
The macro
.kwm __WINDOWS__
and
.kwm __WINDOWS_386__
will be predefined if "zw" is selected.
.if '&target' eq 'QNX' .do begin
.np
This option does not apply to QNX.
.do end
.do end
.*
.if &e'&$SWzW86 eq 1 .do begin
:OPT refid='SWzW86' name='zW (optimized)'.&optdag.
.ix 'options' 'zW'
&286only.
This option is similar to "zw" but causes the compiler to generate
more efficient prologue/epilogue code sequences in some cases.
This option may be used for Microsoft Windows applications code other
than user callback functions.
.ix '_export functions'
Any functions declared as "far _export" will be compiled with the
"fat" prologue/epilogue code sequence described under the "zw"
option.
.millust begin
far _export func(...)
far _export pascal func(...)
.millust end
.np
The following "skinny" prologue/epilogue sequence is generated for
functions that are not declared to be "far _export".
.ix 'pascal functions'
.millust begin
far pascal func(...)
far func(...)

    inc  BP
    push BP
    mov  BP,SP
    .
    .
    .
    pop BP
    dec BP
    retf n
.millust end
.np
.ix 'macros' '__WINDOWS__'
The macro
.kwm __WINDOWS__
will be predefined if "zW" is selected.
.if '&target' eq 'QNX' .do begin
.np
This option does not apply to QNX.
.do end
.do end
.*
.if &e'&$SWzWs eq 1 .do begin
:OPT refid='SWzWs' name='zWs'.&optdag
.ix 'options' 'zWs'
&286only.
This option is similar to "zW" but causes the compiler to generate
"smart callbacks".
This option may be used for Microsoft Windows user callback functions
in executables only.
It is not permitted for DLLs.
Normally, a callback function cannot be called directly.
You must use MakeProcInstance to obtain a function pointer with which
to call the callback function.
.np
If you specify "zWs" then you do not need to use MakeProcInstance in
order to call your own callback functions.
.ix '_export functions'
Any functions declared as "far _export" will be compiled with the
"smart" prologue code sequence described here.
.np
The following example shows the usual prologue code sequence that is
generated when the "zWs" option is NOT used.
.exam begin 14
:SF font=1.compiler_name:eSF. winapp &sw.mc &sw.bt=windows &sw.d1

short FAR PASCAL __export Function1( short var1,
                                     long varlong,
                                     short var2 )
{
 0000  1e            FUNCTION1       push    ds
 0001  58                            pop     ax
 0002  90                            nop
 0003  45                            inc     bp
 0004  55                            push    bp
 0005  89 e5                         mov     bp,sp
 0007  1e                            push    ds
 0008  8e d8                         mov     ds,ax
.exam end
.np
The following example shows the "smart" prologue code sequence that is
generated when the "zWs" option is used.
The assumption here is that the SS register contains the address of
DGROUP.
.exam begin 12
:SF font=1.compiler_name:eSF. winapp &sw.mc &sw.bt=windows &sw.d1 &sw.zWs

short FAR PASCAL __export Function1( short var1,
                                     long varlong,
                                     short var2 )
{
 0000  8c d0         FUNCTION1       mov     ax,ss
 0002  45                            inc     bp
 0003  55                            push    bp
 0004  89 e5                         mov     bp,sp
 0006  1e                            push    ds
 0007  8e d8                         mov     ds,ax
.exam end
.do end
.*
:eOPTLIST.
.*
.section Debugging/Profiling
.*
.np
This group of options deals with all the forms of debugging
information that can be included in an object file.
Support for profiling of Pentium code is also described.
.*
:OPTLIST.
.*
.if &e'&$SWd0 eq 1 .do begin
:OPT refid='SWd0' name='d0'.
.ix 'options' 'd0'
(C++ only)
No debugging information is included in the object file.
.do end
.*
.if &e'&$SWd1 eq 1 .do begin
:OPT refid='SWd1' name='d1'.
.ix 'options' 'd1'
Line number debugging information is included in the object file.
This option provides additional information to the &dbgname (at the
expense of larger object files and executable files).
Line numbers are handy when debugging your application with the
&dbgname at the source code level.
Code speed is not affected by this option.
To avoid recompiling, the &stripname can be used to remove debugging
information from the executable image.
.do end
.*
.if &e'&$SWd1pls eq 1 .do begin
:OPT refid='SWd1pls' name='d1+'.
.ix 'options' 'd1+'
(C only)
Line number debugging information plus typing information for global
symbols and local structs and arrays is included in the object file.
Although global symbol information can be made available to the
&dbgname through a &lnkname option, typing information for global
symbols and local structs and arrays must be requested when the source
file is compiled.
This option provides additional information to the &dbgname (at the
expense of larger object files and executable files).
Code speed is not affected by this option.
To avoid recompiling, the &stripname can be used to remove debugging
information from the executable image.
.do end
.*
.if &e'&$SWd2 eq 1 .do begin
:OPT refid='SWd2' name='d2'.
.ix 'options' 'd2'
In addition to line number information, local symbol and data
type information is included in the object file.
Although global symbol information can be made available to the
&dbgname through a &lnkname option, local symbol and typing
information must be requested when the source file is compiled.
This option provides additional information to the &dbgname (at the
expense of larger object files and executable files).
.np
By default, the compiler will select the "od" level of optimization if
"d2" is specified (see the description of the "od" option).
Starting with version 11.0, the compiler now expands functions in-line
where appropriate.
This means that symbolic information for the in-lined function will
not be available.
.np
The use of this option will make the debugging chore somewhat easier
at the expense of code speed and size.
To create production code, you should recompile without this option.
.do end
.*
.if &e'&$SWd2i eq 1 .do begin
:OPT refid='SWd2i' name='d2i'.
.ix 'options' 'd2i'
(C++ only)
This option is identical to "d2" but does not permit in-lining of
functions.
Functions are emitted as external out-of-line functions.
This option can result in larger object and/or executable files than
with "d2" (we are discussing both "code" and "file" size here).
.do end
.*
.if &e'&$SWd2s eq 1 .do begin
:OPT refid='SWd2s' name='d2s'.
.ix 'options' 'd2s'
(C++ only)
This option is identical to "d2" but does not permit in-lining of
functions.
Functions are emitted as static out-of-line functions.
This option can result in larger object and/or executable files than
with "d2" or "d2i" (we are discussing both "code" and "file" size
here).
Link times are faster than "d2i" (fewer segment relocations) but
executables are slightly larger.
.do end
.*
.if &e'&$SWd2t eq 1 .do begin
:OPT refid='SWd2t' name='d2t'.
.ix 'options' 'd2t'
(C++ only)
This option is identical to "d2" but does not include type name
debugging information.
This option can result in smaller object and/or executable files (we
are discussing "file" size here).
.do end
.*
.if &e'&$SWd3 eq 1 .do begin
:OPT refid='SWd3' name='d3'.
.ix 'options' 'd3'
This option is identical to "d2" but also includes symbolic debugging
information for unreferenced type names.
Note that this can result in very large object and/or executable files
when header files like
.fi WINDOWS.H
or