build
Builds the current system model or a system component.
Format
build [build_unit_specifier]
[-comment {text| "<" pathname}]
[-query | -query_all | -q | -qa]
[-noequivalences]
[-force | -force_all]
[-bct_only]
[-list]
[-von]
Description
The build command builds either the current system or one of its system
components, where build_unit_specifier is a name that uniquely identifies a
system component. If no build unit specifier is given, the configuration
manager builds the entire system.
The configuration manager gets the specifications for the target system from the
current system model and the current configuration thread. If you issue the
build command without options, the configuration manager simply reports the
number of components that require building, and proceeds to build them,
displaying the date and time of each build as it occurs.
build takes a number of options, most of which give you greater control over the
build. The following paragraphs describe the build options.
-comment text
Use the -comment option if you want to enter comments about the build in the
database. Your comments become part of the information displayed by the show
builds command. Note that the -comment option is the only way to enter comments
about the build operation. If you omit the -comment option, the DSEE facility
does not open an edit pad and prompt you for comments.
-query, -query_all
The -query and -query_all options (which can be abbreviated as -q and -q_a)
enable you to tell the configuration manager which of the buildable units that
it intends to build don't need to be rebuilt. In effect, these options allow
you to "short-circuit" certain builds. When you issue the build command with
one of these two options, the configuration manager displays a number of edit
panes, seeded with comments, questions, and related material. You edit each of
these panes to tailor the subsequent build to your needs.
While the edit panes contain instructions for editing, they cannot provide
complete background on the process of short-circuiting a build. The following
discussion gives you these details.
The DSEE facility provides two methods for you to short-circuit builds that
would normally be performed because the configuration manager can't find
matching BCTs in the pools for the desired BCTs (derived from your current
configuration thread). Both methods ultimately serve to identify existing
builds that should be substituted for one or more of those that the
configuration manager would have built. Using either method, you may declare
that the substituted builds
o Are equivalent to (that is, entirely interchangeable with) those that
the configuration manager 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.
The first way that you can short-circuit the build of a component is through
substitute version specification: 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 uses the versions called for by the current
configuration thread for the remaining dependencies. The configuration manager
then looks up the new desired BCT in the pools.
The second way that you can short-circuit the build of a component is through
substitute build specification: directly specifying an existing build that
should be used instead of the one that the configuration manager would have
built. You may identify by name the build that you want used, 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).
To short-circuit builds, issue the build command with either the -query or
-query_all option. These options cause the configuration manager to prompt the
user for equivalence and override information. The -query option causes the
DSEE facility to display an edit pane seeded with the names of all non-Aggregate
components 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 DSEE
facility 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 of the components
listed in a -query or -query_all edit pane, delete the component's name. In
subsequent edit panes, the configuration manager then asks you to provide
information that it can use to substitute existing builds for builds of the
components whose names you deleted. The configuration manager also asks you
whether a particular substitution is permanent (an equivalence) or temporary (an
override).
In the next pane the configuration manager shows you, it asks you to indicate
substitute element versions to use instead of those versions requested by your
configuration thread. Enter your substitution requests in the edit pane using
the configuration thread language. (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 components 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. Delete
main.pas from the set of components to build (listed in the first edit pane) and
place the following line in the second edit pane:
-for x.ins.pas []
This causes the configuration manager to look for a main.pas built with the
latest version of x.ins.pas in the library.
Note that your substitute version specifications may not enable the
configuration manager to find suitable substitute builds for all of the
components you said should not be built. This is especially true if files that
are not stored as DSEE elements change, because the configuration thread
language does not allow you to request versions for objects that are not DSEE
elements.
You specify whether you want an equivalence or an override in the same edit pane
in which you make substitute version specifications. The configuration manager
seeds the edit pane with the following text:
-equivalence
#-override
If you want an equivalence, you don't need to do anything. If you want an
override, delete the -equivalence line (or precede it with a pound sign, which
will make the configuration manager treat it like a comment) and remove the
pound sign from in front of the -override specification.
When you finish specifying all substitute versions, the DSEE facility displays a
third edit pane in which you identify 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 your previous build in the current
working context be used. The syntax for this edit pane is shown here:
-for wildcard_build_unit_specifier full_build_name
| -for wildcard_build_unit_specifier -previous
Wildcard_build_unit_specifier identifies one or more buildable components for
which you want the configuration manager to substitute the derived objects of
the prior build. 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
If a component needs to be built in more than one context, and you specify a
parent component's build as the substitute, then the configuration manager
chooses the substitute build from the corresponding context within the parent.
You can declare equivalences and overrides to older builds that reside in your
reserved pool. For example, if you declare an equivalence for ast.pas by
entering the following line in pane three of the equivalencing panes:
-for ast.pas ast.pas!4-Dec-1985.13:24:29 -versions
if the build ast.pas!4-Dec-1985.13:24:29 used a reserved copy of the element
ast.pas (which is now ast.pas.bak or perhaps even deleted), your current build
of the component ast.pas will be equivalent to the build of ast.pas in your
reserved pool.
When you've edited a copy of an element reserved in your working directory since
your last build of the root component, but you prefer that your next build of
the component use the derived object from the earlier build, you can easily
declare the equivalence to the last build with a line in pane two like this one:
-for ast.pas ! -versions
Naturally, when another user's replace operation caused one of your system's
components to be rebuilt, you would declare an equivalence only if you were
confident that the changes he or she made were irrelevant to the component(s)
you were building. (You could find out by talking to that user, or by doing a
show history against the element and checking the user's comments.)
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.
Elaborating on the previous example, suppose that you reserve the include file
x.ins.pas and make changes to it that do not affect main.pas, so you want to
declare an equivalence. You decide to do so using substitute build
specification, because your previous build of main.pas used the old version of
the include file. However, someone else replaces main.pas before you build.
You then issue a build command with a -query option. You direct the
configuration manager to reuse the previous build of main.pas, and you declare
it to be equivalent to the build of main.pas that the configuration manager
would have performed. Notice that, because the current configuration thread
calls for the most recent version of main.pas, you have inadvertently declared
the new version of main.pas to be equivalent to the old one. You intended to
confine your declarations to the new version of x.ins.pas, but the new version
of main.pas slipped into the declaration.
To summarize, you should normally use substitute build specification only for
overrides. A substitute build specification is most useful when you need to
temporarily 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
making adjustments to your current configuration thread. (Type help
thread_syntax for more information about configuration threads.)
-noequivalences
The -noequivalences option directs the configuration manager to ignore
equivalence relationships and, therefore, to rebuild objects even though
equivalent objects exist. Use this option to override equivalences declared by
other users, or equivalences you declared during a previous build.
The -noequivalences option does not affect noncritical dependencies. If you
want to force the configuration manager to rebuild despite a noncritical
dependency, use either the -force or -force_all option (described below).
-force and -force_all
The -force option forcibly rebuilds a system component even if an acceptable
derived object for the component exists. If the build command line does not
specify a system component (that is, you're building the entire current system),
-force forcibly rebuilds the highest-level object in the current system.
The -force_all option forcibly rebuilds the system or component and all of its
subcomponents. This option is useful if you want to rebuild everything from
scratch using a new version of a compiler that you've defined as a noncritical
dependency. Note that only -force and -force_all affect noncritical
dependencies; -noequivalences does not affect noncritical dependencies. For
example, if a system model declares include file element globals.ins.pas to be a
noncritical dependency, by default the configuration manager will not rebuild
the component solely to account for a change to globals.ins.pas. However,
building with -force_all will force the configuration manager to rebuild using
the version of global.ins.pas requested in the configuration thread.
When you use -force or -force_all, the configuration manager rebuilds using the
version specifications in the current configuration thread. In addition, the
configuration manager deletes from the current pools (including your reserved
pool) any existing objects that would normally satisfy the desired BCTs. When
you use -force, the configuration manager deletes any existing derived objects
that would normally satisfy the desired BCT of the system component you are
building. When you use -force_all, the configuration manager deletes these
derived objects as well as those of the subcomponents of the system component
being built.
The configuration manager also deletes any objects that use the deleted objects
as subcomponents. In other words, if a system model component has a result
dependency on a component being built with either the -force or -force_all
option, the configuration manager deletes all builds of the dependent component
that use the derived objects being deleted because of -force or -force_all.
This is useful when you have a derived object that you do not want to use for
some reason, even though all critical (regular) dependencies are satisfied (if,
for example, the object was built by a bad compiler, and you listed the compiler
as a noncritical dependency).
Note that forcing a build does not delete derived objects from other users'
reserved pools. However, the configuration manager does not promote a derived
object from a reserved pool to a regular (shared) pool if one or more of the
derived object's subcomponents have been forcibly deleted from the regular pool.
The options -force and -force_all cannot be abbreviated.
-bct_only
The -bct_only option directs the configuration manager to produce a BCT for the
system or component without executing any translation rules, and therefore,
without producing any derived objects. You can compare the BCT against existing
BCTs (with the compare builds command) to see which system components the
configuration manager would have to build to satisfy your desired BCT.
-list
The -list option causes the configuration manager to display a list of the
components that need to be built whenever two or more components require
building. The following example demonstrates this function:
DSEE> build -list
The current thread needs to be validated . . .
The thread has been validated.
No working directory copies of reserved elements were requested.
The following 4 builds are required:
test_model
p
bar.pas
foo.pas
Building "bar.pas" . . .
-von
The -von option causes the configuration manager to display an expanded version
of each component's translation rule before building the component. This option
is analogous to the AEGIS Shell's verbose mode.
Concurrent Building
The build command's display and output differ when you build using a number of
different nodes. (You establish a list of nodes on which to build using the set
builder command.) During concurrent builds, the configuration manager creates a
separate window, where it displays information about the the current status of
the build: the number of builds to perform, the number successfully completed,
the number unsuccessfully completed, and the number of builds in progress. The
manager also displays the identifier of each build server executing a
translation rule.
During serial building, translator output is displayed in the DSEE transcript
pad as the translation rule is executed. When you have concurrent builds
occurring on several nodes, however, the DSEE facility cannot simultaneously
display all the translation rules being executed. Therefore, the DSEE facility
saves the output each translation produces until the build is complete, and then
writes the output to the transcript pad all at once.