This chapter describes the process of setting up and running builds that use several hosts in the local area network. Included are descriptions of both the “client-side” and the “server-side” control mechanisms.
ClearCase can perform distributed builds, in which multiple hosts around the local area network execute the build scripts associated with makefile targets. This feature can provide a significant performance improvement — instead of using a single processor to perform the work, one build script at a time, you can have 5, 10, or 20 processors work in parallel. With large software systems, this performance improvement can make a critical difference — for example, enabling the entire application to be built each night.
You start a distributed build in much the same way as a single-host build: by entering a clearmake command. A command-line option or environment variable setting causes the build to “go distributed”.
A distributed build is controlled by specifications on all the hosts involved:
Client-side controls — The host where you enter the clearmake command is the “build client” or “build controller”. On this host, you specify such information as the set of hosts to be used for building and the number of build scripts to be executed concurrently.
Server-side controls — Each “build server” host used in a distributed build can have an access-control file. A build client must meet the access-control requirements in order to use the host as a build server.
To dispatch a build script, clearmake uses the standard UNIX “remote shell” facility to start an Audited Build Executor (abe) process, set to the current view, on a build host. A build script runs under abe control much as if it were being executed by clearmake — the typical result is the creation of a set of derived objects and an associated configuration record. abe collects terminal output produced by the build script, and sends it back to the build controller, where it appears in your clearmake window.
Figure 13-1 illustrates the ClearCase distributed build architecture. The following section presents a simple step-by-step procedure for setting up both the client and server sides of a distributed build.
No special setup is required for the client host itself where you enter the clearmake command. Rather, you must set up one or more build hosts files in your home directory. Each such file must have a name that begins with “.bldhost”. Choose a file name suffix for each build hosts file that describes its intended use. For example:
| .bldhost.sun5 | list of hosts used to build SunOS 5 binaries | |
| .bldhost.day | list of hosts used to perform distributed builds during the work day | |
| .bldhost.night | list of hosts used to perform overnight distributed builds |
Depending on your build environment, you may or may not need multiple build hosts files. In a heterogeneous network, for example, architecture-specific builds may or may not need to be performed on hosts of that architecture. (You may have cross-compilers, which eliminates this restriction.)
When you start a distributed build, clearmake selects a particular build hosts file using an environment variable — even if you have only one such file. See “Starting a Distributed Build”.
You might set up two build hosts files, for daytime and nighttime use, as follows:
Create a build hosts file for daytime use — For daytime builds, you might use the list of hosts that your system administrator has provided in /usr/local/lib, along with your own host. To minimize the disruption to other work, you might specify that each host is to be used only if it is not heavily loaded: at least 75% idle.
% cat > $HOME/.bldhost.day -idle 75 neptune # include /usr/local/lib/day_builds <ctrl-d>
Create a build hosts file for overnight use — For overnight builds, you might use another list of hosts provided by the system administrator.
% cat > $HOME/.bldhost.night # include /usr/local/lib/night_builds <ctrl-d>
Since this file does not include a -idle specification, clearmake will default to using a host only if it at least 50% idle.
For details on build hosts files, see the bldhosts manual page.
Each build server host can have a bldserver.control file, which controls its usage for distributed builds. This file can impose such restrictions as limiting who can use the host for distributed builds, and specifying when it can be used for this purpose. If a build server host has no such file, it will accept all distributed build requests. The bldserver.control manual page describes the details of this mechanism.
Here's how you might set up a build server host that is used both for your group's daytime builds and its overnight builds:
Create a bldserver.control file — Each line of the bldserver.control file defines a situation in which it will accept distributed build requests.
% cat > /usr/adm/atria/config/bldserver.control -time 08:30,19:30 -idle 60 (1) -time 19:30,05:30 (2) -user bldmeister (3) <ctrl-d>
Line 1 specifies that during the interval between 8:30am and 7:30pm, this host will honor a distributed request when it is at least 60% idle. Line 2 specifies that during the interval between 7:30pm and 5:30am, this host will honor any distributed request, no matter how busy it is. Line 3 specifies that a distributed build request from a clearmake invoked by user bldmeister will always be honored.
Protect the bldserver.control file — Make sure that your access-control settings can't be deleted or altered:
% chmod 444 /usr/adm/atria/config/bldserver.control
Note that the idleness threshold can be specified with -idle settings on both the client and server sides. If there is a conflict, the overall principle is that the build server host is the “master of its own fate”. Examples:
A clearmake process is searching for hosts that are at least 50% idle (the default). A build server that would appear to qualify because it is 70% idle will not be used if its bldserver.control file includes an -idle 75 specification.
A bldserver.control file on a build server host permits access, because – idle 60 is specified on a host that is currently 75% idle. But clearmake does not dispatch a build script to this host, because the build hosts file specifies an even higher threshold, - idle 80.
To start a distributed build, you must set an environment variable, then invoke clearmake with the appropriate option:
Set the clearcase_bld_conc variable — The value of this variable determines the name of the build hosts file in your home directory:
clearcase_bld_conc value Name of build hosts file
sun5 .bldhost.sun5
SUN5 .bldhost.SUN5
day .bldhost.day
night .bldhost.night
Invoke clearmake with distributed building enabled — You can use a command-line options or an environment variable to enable distributed building. You can start a build that uses up to five hosts concurrently in either of these ways:
% clearmake -J 5 my_target (command-line option) % setenv CLEARCASE_BLD_CONC 7 (environment variable) % clearmake my_target
In some distributed build environments, you may find it convenient to have your shell startup script set clearcase_bld_conc automatically. For example, your group may be supporting an application on several architectures. Building the application for a particular architecture should be as simple as ...
... logging in to a host of that architecture
... setting a view and go to the appropriate directory
... entering a clearmake - J command to start a distributed build
You can implement such a scheme as follows:
Use architecture-specific build hosts files — Each build hosts file should have a suffix that names a target architecture: .bldhosts.hpux9, .bldhosts.sunos5, and so on. Typically, each of these files would list hosts of just one architecture — for example, all SunOS 5 hosts in .bldhosts.sunos5.
Set clearcase_bld_conc according to the local host's architecture — Include a routine in your shell startup file that determines the hardware/software architecture of the local host, and sets clearcase_bld_conc to one of the suffix strings: hpux9, sunos5, and so on. Here is a code fragment from C shell startup script:
set ARCHSTRING = "`uname -s ; uname -r`" switch ("$ARCHSTRING") case "SunOS 5*": setenv CLEARCASE_BLD_CONC sunos5 breaksw case "HP-UX 9*": setenv CLEARCASE_BLD_CONC hpux9 breaksw ...