For simple builds (builds that are not parallel or distributed), run the rafmake command as follows:
rafmake [ -f makefile ] [ options ] ... [ targets ] ...
where The following list provides examples by operating system.
% rafmake -u -f project.mk
% rafmake -v -f project.mk a.out
Y:\> rafmake INCL_DIR=C:\src\include
The rafmake command supports parallel builds, which separate builds into independent components that can be built at the same time to reduce the overall build time.
The syntax to run parallel builds is as follows:
rafmake -J num [ -f makefile ] [ options ] ... [ targets ] ...
whereRunning parallel builds provides efficient resource utilization, especially with multicore processors. The performance gain from parallel builds depends on the type of the build. For example, in the case of a CPU-intensive build, the optimum number of concurrent build jobs would be the same as the number of processors (or cores). If you specify more than that, you might not realize a significant performance gain. For an IO-intensive build, however, increasing the number of parallel jobs reduces build time. Try a few builds with different numbers to determine the optimal number of concurrent build jobs for your resources.
The following list provides examples of parallel builds by operating system.
% rafmake -J 3 -f project.mk
Y:\> rafmake -J 5 INCL_DIR=C:\src\include software.exe
Parallel builds can use resources only on one computer. Distributing a build takes parallel builds a step further by distributing the build load across multiple computers.
To distribute a build, your environment must meet the following requirements:
For all the computers on which the build is to be distributed, the same source code must be accessible by the same path. Typically, having the source code on NFS-mounted shares (and mounting them on the same path on all computers) ensures that the same source directory is available on all build computers in the same path.
When a user starts a distributed build from a host computer, the rafmake command internally starts the build engine (rafbe) on all the computers where the build is to be distributed. The build engine is started using either the ssh or rsh command, which is configured when installing Build Catalyst. The /opt/rational/buildforge/buildcatalyst/etc/rafbe_starter file is a symbolic link to the remote shell that the user chose during installation. The user who starts the build must be able to log in without a password to all the computers that are using the chosen remote shell. By logging in without a password, the build engine can be started silently on the various computers. Consult the rsh or ssh command manual to set up a login that requires no password.
A build hosts file typically contains several lines with the host names or IP addresses of many computers. These computers are where the builds are to be distributed. The file also contains lines that describe other options, such as -idle num. This type of line specifies how idle a computer must be for builds to be scheduled on the computers that are listed below it. Idleness is assumed to be 50 if it is not explicitly mentioned. Here is an example build hosts file:
### Contents of build hosts file
host1.mydomain.com
-idle 25
host2.mydomain.com
host2.mydomain.com
192.168.0.200
-idle 75
host3.mydomain.com
### End of build hosts file
In this example, the build is distributed to four computers: host1, host2, host3, and 192.168.0.200. The idleness for the host1.mydomain.com computer is assumed to be 50, because it is not explicitly mentioned. For the host2 and 192.168.0.200 computers, the idleness is specified as 25. This means that if one of those computers is less than 75% loaded or busy (or at least 25% idle), builds are scheduled on that computer. If the computers are less than 25% idle, builds are not scheduled on those computers. Also, the example lists the host2 computer twice. As a result, two parallel build threads can be started on the host2 computer. Depending on computer configurations, you can tweak your build hosts file to use resources optimally for builds.
After you create the build hosts file, you can start the distributed build by using the following command syntax:
rafmake -J num -B build_hosts_file [ -f makefile ]
[ options ] ... [ targets ] ...
The num value for the -J option specifies the total number of build threads for all computers.
Without the -B option, the rafmake command would perform a parallel build instead of a distributed build. When you specify the -B option and a valid build hosts file, the build engine schedules the distributed builds on the different computers that are specified in the build hosts file.