wmake.gml

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

.exam end
.np
There are a number of interesting points to consider:
.autonote
.note
By default, Make will only check that the target file exists after the
command ("DOREPORT" in this example) is executed.
It does not check that the target's time-stamp shows it to be younger.
If the target file does not exist after the command has been executed,
an error is reported.
.note
There is no guarantee that the command you have specified does update
the target file.
In other words, simply because you have stated a dependency does not
mean that one exists.
.note
Furthermore, it is not implied that other targets in our list will not
be updated.
In the case of our example, you can assume that we have designed the
"doreport" command to update both targets.
.endnote
.*
.section Multiple Rules
.*
.np
A makefile may consist of any number of rules.
Note that the following:
.millust begin
target1 target2 : dependent1 dependent2 dependent3
        command list
.millust end
.pc
is equivalent to:
.millust begin
target1 : dependent1 dependent2 dependent3
        command list

target2 : dependent1 dependent2 dependent3
        command list
.millust end
.pc
Also, the rules may depend on the targets of other rules.
.millust begin
#
# rule 1: this rule uses rule 2
#
balance.lst summary.lst : ledger.dat sales.dat purchase.dat
        doreport

#
# rule 2: used by rules 1 and 3
#
sales.dat : canada.dat england.dat usa.dat
        dosales

#
# rule 3: this rule uses rule 2
#
year.lst : ledger.dat sales.dat purchase.dat
        doyearly
.millust end
.pc
.ix '&makcmdup' '":" behaviour'
.ix 'colon (:)' 'behaviour in &makcmdup'
The dependents are checked to see if they are the targets of any other
rules in the makefile in which case they are updated.
This process of updating dependents that are targets in other rules
continues until a rule is reached that has only simple dependents that
are not targets of rules.
At this point, if the target does not exist or if any of the
dependents is younger than the target then the command list associated
with the rule is executed.
.hint
The term "updating", in this context, refers to the process of
checking the time-stamps of dependents and running the specified
command list whenever they are out-of-date.
Whenever a dependent is the target of some other rule, the dependent
must be brought up-to-date first.
Stated another way, if "A" depends on "B" and "B" depends on "C" and
"C" is younger than "B" then we must update "B" before we update "A".
.ehint
.pc
&maksname will check to ensure that the target exists after its
associated command list is executed.
The target existence checking may be disabled in two ways:
.autopoint
.point
use the command line option "c"
.point
.ix '&makcmdup directives' '.NOCHECK'
.ix 'NOCHECK' '&makcmdup directive'
use the
.id &sysper.NOCHECK
directive.
.endpoint
.np
The rule checking returns to the previous rule that had the target as
a dependent.
Upon returning to the rule, the command list is executed if the target
does not exist or if any of the updated dependents are now younger
than the target.
If you were to type:
.millust begin
&makcmd
.millust end
.pc
here are the steps that would occur with the previous makefile:
.millust begin
update(balance.lst) (rule 1)

  update(ledger.dat)            (not a target)
  update(sales.dat)             (found rule 2)

    update(canada.dat)          (not a target)
    update(england.dat)         (not a target)
    update(usa.dat)             (not a target)
    IF sales.dat does not exist                      OR
       any of (canada.dat,england.dat,usa.dat)
         is younger than sales.dat
    THEN execute "dosales"

  update(purchase.dat)          (not a target)
  IF balance.lst does not exist                      OR
     any of (ledger.dat,sales.dat,purchase.dat)
       is younger than (balance.lst)
  THEN execute "doreport"
.millust end
.pc
The third rule in the makefile will not be included in this update
sequence of steps.
Recall that the default target that is "updated" is the first target
in the first rule encountered in the makefile.
This is the default action taken by &maksname when no target is
specified on the command line.
If you were to type:
.millust begin
&makcmd year.lst
.millust end
.pc
then the file "YEAR.LST" would be updated.
As &maksname reads the rules in "MAKEFILE", it discovers that updating
"YEAR.LST" involves updating "SALES.DAT".
The update sequence is similar to the previous example.
.*
.section Command Lists
.*
A command list is a sequence of one or more commands.
Each command is preceded by one or more spaces or tabs.
Command lists may also be used to construct inline files "on the fly".
Macros substitute in command lists and in inline files.
An inline file is introduced by "<<" in a command in a command list.
Data to insert into that file is placed (left-justified) in the command list.
The data is terminated by "<<" in the first column.
It is not possible to place a line which starts "<<" in an inline file.
More than one inline file may be created in a command.
Data for each is placed in order of reference in the command.
.pc
In building the Open Watcom system, it is sometimes necessary to do some text
substitution with a program called vi. This needs a file of instructions.
The following simplifies an example used to build Open Watcom
so that inline files may be shown.
Without inline files, this is done as:
.millust begin
$(dllname).imp : $(dllname).lbc ../../trimlbc.vi
    cp $(dllname).lbc $(dllname).imp
    $(vi) -s ../../trimlbc.vi $(dllname).imp

where trimlbc.vi consists of
set magic
set magicstring = ()
atomic
%s/\.dll'/'/
%s/^(\+\+')(.*)('\.'.*')\.[0-9]+$/\1\2\3..'\2'/
x
.millust end
A doubled "$" to produce a single dollar is notable when an inline file is used:
.millust begin
$(dllname).imp : $(dllname).lbc
    cp $(dllname).lbc $(dllname).imp
    $(vi) -s << $(dllname).imp
set magic
set magicstring = ()
atomic
%s/\.dll'/'/
%s/^(\+\+')(.*)('\.'.*')\.[0-9]+$$/\1\2\3..'\2'/
x
<<
.millust end
A filename may follow a "<<" on a command line to cause a file with that
name to be created. (Otherwise, '&makcmdup' chooses a name.)
"keep" or "nokeep" may follow a terminating "<<" to show what to do
with the file after usage. The default is "nokeep" which zaps it.
.*
.section Final Commands (.AFTER)
.*
.ix '&makcmdup directives' '.AFTER'
.ix 'AFTER' '&makcmdup directive'
The
.id &sysper.AFTER
directive specifies commands for &maksname to run after it has done all other commands.
See the section entitled
:HDREF refid='cld'.
for a full description of its use.
.*
.section Ignoring Dependent Timestamps (.ALWAYS)
.*
.ix '&makcmdup directives' '.ALWAYS'
.ix 'ALWAYS' '&makcmdup directive'
The
.id &sysper.ALWAYS
directive indicates to &maksname that the target should always be updated
regardless of the timestamps of its dependents.
.millust begin
#
# .always directive
#

foo : bar .always
    wtouch $@
.millust end
.pc
foo is updated each time &maksname is run.
.*
.section Automatic Dependency Detection (.AUTODEPEND)
.*
.np
.ix '&makcmdup directives' '.AUTODEPEND'
.ix 'AUTODEPEND' '&makcmdup directive'
Explicit listing of dependencies in a makefile can often be tedious in
the development and maintenance phases of a project.
The &cmpname compiler will insert dependency information into the
object file as it processes source files so that a complete snapshot
of the files necessary to build the object file are recorded.
Since all files do not have dependency information contained within
them in a standard form, it is necessary to indicate to &maksname when
dependencies are present.
.np
To illustrate the use of the
.id &sysper.AUTODEPEND
directive, we will show its use in an implicit rule and in an explicit
rule.
.millust begin
#
# .AUTODEPEND example
#
&sysper.&langsuff..obj: .AUTODEPEND
        &compcmd $[* $(compile_options)

test&exe : a.obj b.obj c.obj test.res
        &lnkcmd FILE a.obj, b.obj, c.obj
        &wrccmd /q /bt=windows test.res test&exe

test.res : test.rc test.ico .AUTODEPEND
        &wrccmd /ad /q /bt=windows /r $[@ $^@
.millust end
.np
In the above example, &maksname will use the contents of the object
file to determine whether the object file has to be built during
processing.  The &wrcname can also insert dependency
information into a resource file that can be used by &maksname..
.*
.section Initial Commands (.BEFORE)
.*
.ix '&makcmdup directives' '.BEFORE'
.ix 'BEFORE' '&makcmdup directive'
The
.id &sysper.BEFORE
directive specifies commands for &maksname to run before it does any other command.
See the section entitled
:HDREF refid='cld'.
for a full description of its use.
.*
.section Disable Implicit Rules (.BLOCK)
.*
.ix '&makcmdup directives' '.BLOCK'
.ix 'BLOCK' '&makcmdup directive'
The
.id &sysper.BLOCK
directive and the "b" command line option are alternative controls to
cause implicit rules to be ignored.
See the section entitled
:HDREF refid='clo'.
for a full description of its use.
.*
.section Ignoring Errors (.CONTINUE)
.*
.ix '&makcmdup directives' '.CONTINUE'
.ix 'CONTINUE' '&makcmdup directive'
The
.id &sysper.CONTINUE
directive and the "b" command line option are alternative controls to
cause failing commands to be ignored.
See the section entitled
:HDREF refid='clo'.
for a full description of its use.
.millust begin
#
# .continue example
#

&sysper.continue

all: bad good
    @%null

bad:
    false

good:
    touch $@
.millust end
.pc
Although the command list for bad fails, that for good is done.
Without the directive, good is not built.
.*
.section Default Command List (.DEFAULT)
.*
.ix '&makcmdup directives' '.DEFAULT'
.ix 'DEFAULT' '&makcmdup directive'
The
.id &sysper.DEFAULT
directive provides a default command list for those targets which lack one.
See the section entitled
:HDREF refid='cld'.
for a full description of its use.
.millust begin
#
# .default example
#

&sysper.default
    @echo Using default rule to update target "$@"
    @echo because of dependent(s) "$<"
    wtouch $@

all: foo

foo:
    wtouch foo
.millust end
.pc
"all" has no command list. The one supplied to the default directive
is executed instead.
.*
.section Erasing Targets After Error (.ERASE)
.*
.np
.ix '&makcmdup directives' '.ERASE'
.ix 'ERASE' '&makcmdup directive'
.ix '&makcmdup' 'return codes'
.ix 'return codes'
Most operating system utilities and programs have special return codes
that indicate error conditions.
&makname will check the return code for every command executed.
If the return code is non-zero, &maksname will stop processing the
current rule and optionally delete the current target being updated.
By default, &maksname will prompt for deletion of the current target.
The
.id &sysper.ERASE
directive indicates to &maksname that the target should be deleted if
an error occurs during the execution of the associated command list.
No prompt is issued in this case.
Here is an example of the
.id &sysper.ERASE
directive:
.millust begin
#
# .ERASE example
#
&sysper.ERASE
balance.lst : ledger.dat sales.dat purchase.dat
        doreport
.millust end
.pc
If the program "DOREPORT" executes and its return code is non-zero
then &maksname will attempt to delete "BALANCE.LST".
.*
.section Error Action (.ERROR)
.*
.ix '&makcmdup directives' '.ERROR'
.ix 'ERROR' '&makcmdup directive'
The
.id &sysper.ERROR
directive supplies a command list for error conditions.
See the section entitled
:HDREF refid='cld'.
for a full description of its use.
.millust begin
#
# .error example
#

&sysper.error:
        @echo it is good that "$@" is known

all : .symbolic
        false
.millust end
.*
.section Ignoring Target Timestamp (.EXISTSONLY)
.*
.ix '&makcmdup directives' '.EXISTSONLY'
.ix 'EXISTSONLY' '&makcmdup directive'
The
.id &sysper.EXISTSONLY
directive indicates to &maksname that the target should not be updated if it
already exists, regardless of its timestamp.
.millust begin
#
# .existsonly directive
#

foo: .existsonly
        wtouch $@
.millust end
.pc
If absent, this file creates foo; if present, this file does nothing.
.*
.section Specifying Explicitly Updated Targets (.EXPLICIT)
.*
.ix '&makcmdup directives' '.EXPLICIT'
.ix 'EXPLICIT' '&makcmdup directive'
The
.id &sysper.EXPLICIT
directive may me used to specify a target that needs to be explicitly
updated. Normally, the first target in a makefule will be implicitly updated
if no target is specified on &maksname command line. The
.id &sysper.EXPLICIT
directive prevents this, and is useful for instance when creating files
designed to be included for other make files.
.millust begin
#
# .EXPLICIT example
#
target : .symbolic .explicit