DECLARING EQUIVALENCES
This file describes the DSEE equivalencing facility, which allows you to "short-
circuit" a build. This is useful, for example, when you make a change to an
include file referenced by a number of system components--but your change
affects only one or two of those components. Rather than having to rebuild all
of the dependent components, you can reuse existing equivalent builds for the
unaffected components.
This help file contains the following sections:
o Introduction -- describes equivalences versus overrides and
substitute version specifications versus
substitute build specifications
o How to Short-Circuit a Build -- tells you how to initiate the declaration
of equivalences, describes what each of the three panes
that the configuration manager presents to you are for,
and explains the equivalence declaration procedure
o General Notes -- provides information on why substitute version
specifications are preferable to substitute build
specifications
Introduction
============
The configuration manager provides you with a facility to short-circuit builds
that the configuration manager would otherwise perform because it can't find
matching BCTs in the pools for the desired BCTs it derived from your current
configuration thread. Using this facility, you identify existing builds that
you want the configuration manager to substitute for builds that it would have
performed.
You declare that the substituted builds:
o are equivalent to (that is, entirely interchangeable with) those
that would have built
o represent temporary "overrides" of the current configuration thread.
Overrides are personal and short-lived. They apply only to the current
build command. Equivalences, on the other hand, are visible to all users of
the system, and, like actual builds, are long-lived. You should exercise
caution when declaring equivalences, because your declarations will
affect other users.
There are two methods to identify the existing builds that you want the
configuration manager to use
instead of rebuilding certain components:
o substitute version specification
-------
o substitute build specification
-----
Substitute version specification involves identifying substitute versions for
some of the component's dependencies. The configuration manager derives a
new desired BCT for the component. The new desired BCT uses the substitute
versions for the indicated dependencies and the versions called for by the
current configuration thread for the remaining dependencies. The configuration
manager then looks the new desired BCT up in the pools.
Substitute build specification involves directly specifying an existing build
that should be used instead of the one that the configuration manager would
have built. You may identify the build that you want the configuration manager
to use by name, or you can tell the configuration manager to use the previous
build. In the latter case the configuration manager will reuse the build it
used for the component in previous build command(s).
How to Short-Circuit a Build
============================
Initiating an Equivalence Declaration
-------------------------------------
To short-circuit builds, issue the build command with either the -query or
-query_all option. These options cause the configuration manager to prompt you
for equivalence and override information. The configuration manager
presents you with edit panes in which you supply the necessary data.
Pane One
--------
The first pane that the configuration manager displays contains names of
buildable components. The -query option causes the configuration manager to
display an edit pane seeded with the names of all components that are not
Aggregates that need to be rebuilt and are likely candidates for substitution.
(Aggregates are not shown because any substitutions you make for an
Aggregate's subcomponents are likely to cause the configuration manager to find
a suitable substitute for the Aggregate among those that are already in the
derived object pools.) If you issue the build command with the -query_all
option, the configuration manager displays an edit pane seeded with the names
of all the components that need to be rebuilt.
If you do not want the configuration manager to build one or more of the
components listed in Pane One, delete the components' names.
Pane Two
--------
In Pane Two, you specify
o whether the short-circuit is an equivalence or an override, and
o what substitute version specifications, if any, you want to make
By default, the configuration manager assumes you want to declare an equivalence
rather than an override. This is apparent in the first two lines of Pane Two:
the first line contains the keyword -equivalence, and the second the keyword
-override, but the second line is commented out with a pound sign (#). To
declare an override rather than an equivalence, remove the pound sign from the
beginning of the second line and either comment out or delete the first line.
Use the configuration thread language to identify which substitute versions you
want the configuration manager to use. (Type help thread syntax for information
on the configuration thread language.)
For example, assume that your current configuration thread calls for the
reserved copies of elements that you have reserved in your working directory,
and the most recent versions of all other elements. If you reserve x.ins.pas,
modify it, and then issue a build command, the configuration manager would
normally build all compnents that depend on x.ins.pas. However, if your changes
to x.ins.pas do not affect component main.pas, you can provide a substitute
version of x.ins.pas for main.pas by deleting main.pas from the list of
components to build in Pane One, and then adding the following line to Pane Two:
-for x.ins.pas []
This causes the configuration manager to create a new desired BCT for the
buildable component main.pas that is identical to the one generated with the
current configuration thread, except that it calls for the latest library
version of x.ins.pas. The configuration manager uses the new desired BCT
to search of the binary pool for an existing BCT that satisfies it.
Pane Three
----------
In Pane Three, you name substitute builds whose derived objects should be
used in place of those your build requires. Identify builds by giving their
full build names or by requesting that the previous build be used. (For
information on full build names, type help full_build_name.) The syntax for
Pane Three is shown below.
-for wildcard_build_unit_specifier { full_build_name | -previous }
Wildcard_build_unit_specifier identifies one or more buildable components for
which you want the configuration manager to substitute the derived objects used
in the prior build. (Type help build_unit_specifier for more information.) If
the wildcard build unit specifier identifies only one buildable component, the
full build name may identify a build of that component or one of its parent
components. If the wildcard build unit specifier identifies several components,
the full build name must identify the build of a component that is a parent of
the wildcarded components.
You must enter one rule per line. The configuration manager evaluates these
build substitution rules in order.
Here are some examples of build substitution rules.
-for lex.pas ftn_compiler!30-Mar-1985.13:11:05
-for syntax.pas -PREVIOUS
-for code_?*.pas back_end!18-Apr-1985.19:27:53
It's worthwhile to note what the last example will cause the configuration
manager to do. If, for instance, you had two subcomponents of backend named
code_gen.pas and code_opt.pas, the configuration manager would reuse the
builds of these two components that it used in the build
back_end!18-Apr-1985.19:27:53 .
The Equivalence Declaration Procedure
-------------------------------------
As we mention above, you initiate an equivalence declaration by adding the
-query or -query_all option to the build command. The configuration manager
then displays Pane One seeded with the appropriate component names.
Once you have deleted all the component names that you don't want the
configuration manager to rebuild from Pane One, type <CTRL>Y. The
configuration manager closes Pane One and displays Pane Two.
After you have listed all the substitute version specifications you wish to
make, close Pane Two with <CTRL>Y. The configuration manager then compares
the information you've provided in Pane Two with the components you eliminated
from Pane One. If the configuration manager can find existing BCTs to match
all the new desired BCTs it generates in response to the information you've
provided in Pane Two, your equivalence session is complete, and the configura-
tion manager proceeds to execute your build command. If, however, the
configuration manager is unable to find existing BCTs for one or more of the
components whose names you eliminated from Pane One, the configuration manager
redisplays Pane One, listing those components as items it intends to build.
Delete the component names from Pane One again if you still want to declare an
equivalence or override for them. The configuration manager then displays Pane
Two once more, and you can specify different substitute version specifications
for these unresolved components.
The configuration manager continues to go back and forth between Panes One and
Two until one of four things happens:
o you type <CTRL>N (in which case the configuration manager aborts your
build)
o you type <CTRL>Y in Pane One without having deleted anything (in which
case the configuration manager proceeds to perform the build with the
current set of equivalences)
o the configuration manager finds existing BCTs to match all the new
desired BCTs it created as a result of your substitute version
specifications (in which case you exit the equivalence declaration
procedure)
o you delete the contents of Pane Two entirely (in which case the
configuration manager displays Pane Three)
If you delete all of Pane Two's contents, the configuration manager displays
Pane Three. Again, you cycle between Panes One and Three until you type
<CTRL>N or the configuration manager finds substitute builds to use for the
remaining unresolved components whose names you deleted from Pane One.
You exit from the equivalence declaration procedure when you have specified
either a substitute version or substitute build specification for each of the
components whose names you eliminated from Pane One.
General Notes
=============
Substitute version specification is the preferred method for declaring
equivalences. You list the changes that do not affect certain components, and
then leave it to the configuration manager to find existing builds that satisfy
the current configuration thread except with respect to just those changes.
With substitute build specification, on the other hand, you directly
substitute existing builds for those called for by the current configuration
thread, even though you may not be fully aware of the exact differences
between them. Therefore, it can be dangerous to declare equivalences (as
opposed to overrides) in this way.
Substitute build specification should normally be used only for overrides.
It is most useful when you have a transient need to short-circuit
certain builds (such as builds of components that you are not working on and
will not need to exercise in order to debug your changes). Remember that
overrides apply only to the current build command. If you have a long-term
need to short-circuit a set of builds, you should consider using a
configuration thread that isolates you more rather than declaring equivalences.