MakeDoCommandsDoc.tioga
Eric Nickell, September 30, 1986 6:42:11 pm PDT
Mike Spreitzer, February 9, 1987 2:56:57 pm PST
Last tweaked by Mike Spreitzer on March 19, 1992 10:49 am PST
Eduardo Pelegri-Llopart March 22, 1989 9:01:18 am PST
MakeDoCommands
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
MakeDoCommands
Mike Spreitzer
© Copyright 1985 Xerox Corporation. All rights reserved.
Abstract: MakeDo automatically determines dependencies between files, and can issue whatever commands are necessary to bring derived files up to date. MakeDoCommands implements a command-tool interface to MakeDo.
Created by: Mike Spreitzer
Maintained by: Mike Spreitzer <Spreitzer.pa>
Keywords: Make, Dependency, Consistency, Derive, File, DF File, Command, Command Tool Interface, Compile, Bind, Order, Sequence
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

For Internal Xerox Use Only
0. Introduction
MakeDo is a package for determining dependency relations between Cedar objects (usually files), and executing actions to bring these objects up-to-date. It is less ambitious than the System Modeling project, in that it has a lower-level understanding (e.g., source and binary files, instead of Cedar modules), and in that it derives the dependencies itself in a standard way from the environment, rather than reading a model.
The package MakeDo sports only a programmer's interface; the package MakeDoCommands implements a command-tool interface.
1. Theory
See MakeDoDoc.Tioga.
2. The Aux Box
See MakeDoDoc.Tioga.
3. User Profile Entries
See MakeDoDoc.Tioga.
4. Command Tool Commands
name MakeDo:
syntax
MakeDo arg*
arg:
object |
-df DF file name |
-dr DF file name |
-rg DF file name |
-og DF file name |
-om DF file name |
-is DF file name |
-omis DF file name |
-ogis DF file name |
-rgomis DF file name |
-rgomns DF file name |
-nm object |
-ns object |
-p number number number number
object:
file name |
(className:ROPE objectName:ROPE)
description
MakeDo executes whatever commands are necessary to produce up-to-date versions of given objects. For instance, it will run the compiler and binder, on the right files, in the right order. You have the option of delimiting what MakeDo is allowed to cause to be changed. Exercising this option gives you added safety and error reporting.
Each argument to MakeDo is a bare object, or something with a switch. Bare objects are taken to be goals. Here is what the switches mean:
-df DF file name: (standard DF processing) Currently equivalent to -rgomis; use of -df provides better insulation from changes.
-dr DF file name: Same as -df; for backward compatibility.
-rg DF file name: (roots are goals) Take the files in the DF file marked as verify-roots (i.e., preceded by a "+") to be goals.
-og DF file name: (owned are goals) Take all the owned files (i.e., ones that might be stored if you did an SModel) to be goals.
-om DF file name: (owned are modifiable) Add to the delimited set of what MakeDo may change all of the files owned by the DF.
-is DF file name: (imported are supports) Take all the imported files (i.e., ones that BringOver would fetch but SModel wouldn't store) to be supports.
-omis DF file name: Do both of -om and -is.
-ogis DF file name: Do both of -og and -is.
-rgomis DF file name: (roots are goals, owned are modifiable, imported are supports) Take the files in the DF marked as verify-roots to be goals. Add to the delimited set of what MakeDo may change all files owned by the DF. Add to the set of supports all the files imported by the DF.
-rgomns DF file name: (roots are goals, owned are modifiable, none are supports) Like -rgomis, but doesn't specify support.
-nm object: (named object is modifiable) Add it to the delimited set of what MakeDo may change.
-ns object: (named object is support) Add it to the set of supports.
-p number number number number: Reset parameters that control auxiliary process forking; the first number is the process limit, the second is the estimated MDS cost of a new process, the third is the estimated MDS cost of an old process, and the last is the minimum MDS to maintain.
If any objects are specified to be modifiable (i.e., some of the switches -df, -dr, -rgomis, -om, or -nm is used), the set of things MakeDo may cause to be changed is delimited to what was explicitly asked for (plus, of course, the goals). Otherwise, what MakeDo may change is undelimited --- it may change anything.
Similarly, if any supports are given (i.e., some of the switches -df, -dr, -rgomis, -is, or -ns is used), MakeDo checks that all the files needed to build the goals are among the supports. This check ignores hidden dependencies --- see MakeVerify for a command that doesn't.
examples
Suppose you have a package. It has a public interface (Foo), a private interface (FooPrivate, which references Foo), two implementation modules (FooImplA and FooImplB, both of which reference FooPrivate), and a configuration (FooPackage, which references FooImplA and FooImplB). After any sequence of compiling, binding, and editing, the command

% MakeDo FooPackage.BCD (the ".BCD" is optional, so far)
will do whatever compiles and binds are necessary to produce an up-to-date version of FooPackage.BCD. For instance, if everything was up-to-date, then you edited FooImplA, then issued the MakeDo command, MakeDo would compile FooImplA and then (if the compile was successful) bind FooPackage. If you were working in subdirectory Foo, with a FooPackage.BCD.Switches that contained
/c~s
it might look like this:

% RCompile FooImplA
Compiling: FooImplA/-g . . . . . . no errors.
End of compilation
% Bind /c~s FooPackage
Binding: FooPackage
. . . . 0 errors
End of binding
If you have a Foo.DF that follows all the usual conventions, a good way to invoke MakeDo is

% MakeDo -rgom Foo.DF
*** Gross Hack ***
There is an interim, unprincipled way to control the optimization level of compilations directed by MakeDo. It is controlled by the switches below, which are further options for an arg. THIS IS UNPRINCIPLED! HOW UNPRINCIPLED IS IT?? IT IS SO UNPRINCIPLED, these switches do not affect the determination of what needs to be recompiled, and affect only those compilations done during the MakeDo invocation in which they are given --- and I won't even THINK about concurrent invocations of MakeDo with different values for these switches.
-OL: Compile at the "lower" level of optimization.
-ON: Compile at the "normal" level of optimization.
For SunOS:
for files in the `sun4' directory, `-O2' is the `normal' level of optimization and `-g' is the `lower' level;
for files in the `sun4-o3' directory, `-O3' is the `normal' level of optimization and `-O2' is the `lower' level.
warnings
Beware!
stop/undo
Click the STOP! button in the command tool.
name MakePrediction:
syntax
MakePrediction arg*
arg: <same as before>
description
Gives an estimate of what commands the MakeDo command would execute.
stop/undo
Click the STOP! button in the commander.
name MakeCommandList:
syntax
MakeCommandList arg*
arg: <same as before>
description
Lists all the commands to make the goals, in order.
stop/undo
Click the STOP! button in the commander.
name MakeVerify:
syntax
MakeVerify arg*
arg:
package name |
-t |
-u
description
Similar to VerifyDF, only better, because it uses all the knowledge of MakeDo. It even understands the compiler's idiotic "hidden imports". And you can invoke it before SModelling.
The -t switch means "tough", which is the opposite of "touchy", which is the default behavior. Touchy means the MakeVerify command considers itself a failure if it finds anything wrong; tough means the command never fails.
The -u switch resets all the flags to their default values.
When given a list of package names, MakeVerify will treat the collection as a unit, except that it will not complain about files that are imported by one package if they are "owned" by packages appearing before in the list [See MakeDoAndPCedar.tioga for a rationale].
stop/undo
Click the STOP! button in the commander.
name MakeExcuses:
syntax
MakeExcuses object*
description
Explains what MakeDo thinks about the given objects.
examples
Suppose your package has a module named MakeDoPrivate; you might do something like this:

% MakeExcuses MakeDoPrivate.BCD
[]<>Users>Spreitzer.pa>MD>MakeDoPrivate.BCD
 Created September 7, 1985 15:28:17.
 Is Current
 Not troubled.
 Needed by {
  RCompile MakeDoNodeProps
  RCompile MakeDoFinders
  RCompile MakeDoBasicImpl
  RCompile MakeDoAuxImpl};
 determines {}.
 Certainly modifiable.
 Currently consistent with inputs.
RCompile MakeDoPrivate
 According to {
 ? []<>Users>Spreitzer.pa>MD>MakeDoPrivate.BCD.Switches
  []<>Users>Spreitzer.pa>MD>MakeDoPrivate.Mesa}
 Makes {
  []<>Users>Spreitzer.pa>MD>MakeDoPrivate.BCD}
 From {
  []<>Users>Spreitzer.pa>MD>BasicTime.BCD
  []<>Users>Spreitzer.pa>MD>CedarProcess.BCD
  []<>Users>Spreitzer.pa>MD>Commander.BCD
*  []<>Users>Spreitzer.pa>MD>IO.BCD
  []<>Users>Spreitzer.pa>MD>List.BCD
!  []<>Users>Spreitzer.pa>MD>MakeDo.BCD
  []<>Users>Spreitzer.pa>MD>RedBlackTree.BCD
 ?? []<>Users>Spreitzer.pa>MD>Rope.BCD
  []<>Users>Spreitzer.pa>MD>TimeStamp.BCD
  []<>Users>Spreitzer.pa>MD>MakeDoPrivate.Mesa}.
 Derived from current determiners.
 Not tried with current inputs.
Those funny punctuation marks give additional information about the objects referenced. When an object is preceded by an asterisk (*), it means that object is not known to be current. In the example above, this is the case for IO.BCD. When an object is preceded by an exclamation mark (!), it is broken; this is the case for MakeDo.BCD in the example above. When an object is preceded by a question mark (?), it doesn't exist; see MakeDoPrivate.BCD.Switches above for an example. When an object is preceded by a double question mark (??), MakeDo does not know the create date of that object; this should never happen, but it is illustrated in the example above for Rope.BCD.
warnings
Beware the Ides of March!
stop/undo
Click the STOP! button in the commander.
name MakeSuspicion:
syntax
MakeSuspicion arg*
arg:
-change object --suspect the named file of change
-current object --forget whether named file is current
-producer object --suspect that the next execution of the file's producer will be different from the last
object --all of the above
-allChange --suspect every object of change
-allCurrent --suspect every object of not being current and every action of behaving differently than last time
-all --all of the above
description
This command is for flushing parts of MakeDo's cache of computed knowledge. It should rarely be necessary.
examples

% MakeSuspicion -all
stop/undo
Don't!
name MakeEmpty:
syntax
MakeEmpty
description
Deletes the entire dependency graph. For when MakeDo is thoroughly messed up.
examples

% MakeEmpty
stop/undo
Don't!
name MakeProducer:
syntax
MakeProducer object*
description
Retries figuring out how to make named leaves.
examples

% MakeProducer FooPackage.BCD
stop/undo
Don't!
name RederiveSummonerLoad:
syntax
RederiveSummonerLoad object*
description
Builds .summonerLoad files based on .summonerInstall files.
examples

% RederiveSummonerLoad TSetter
stop/undo
Don't!
5. Convenience Aliases
The commands MakeDo0, MakePrediction0, MakeVerify0, MakeDo4, MakePrediction4, and MakeVerify4 are convenience aliases to manipulate slices of the DF suites. Each command is equivalent to applying the corresponding alias (described below) to each of arguments given to the command.
MakeDo0
alias MakeDo0(package) MakeDo -rgom package-Source.df -rgom package-PrincOps.df
MakePrediction0
alias MakePrediction0(package) MakePrediction -rgom package-Source.df -rgom package-PrincOps.df
MakeVerify0
alias MakeVerify0(package) MakeVerify package-Source.df package-PrincOps.df
MakeDo4
alias MakeDo4(package) MakeDo -rgom package-Source.df -rgom package-PCR.df -rgom package-Sun4.df
MakePrediction4
alias MakePrediction4(package) MakePrediction -rgom package-Source.df -rgom package-PCR.df -rgom package-Sun4.df
MakeVerify0
alias MakeVerify4(package) MakeVerify package-Source.df package-PCR.df package-Sun4.df