NAME

        cook - load balancing rsh

SYNOPSIS

        cook [ option...  ] architecture command [ argument...  ]
        cook -Help

DESCRIPTION

        The cook program is a wrapper around rsh(1) which does simple load balancing.  It obtains
        its load information by running the rup(1) command, and selects the most suitable host
        hased on the architecture you specify, and the least load of all hosts of that
        architecture.

        The first command line argument is the architecture name which is used to get the list of
        possible hosts.  From that list the rup(1) command is run to determine the host with the
        lowest load, which is in turn used as the first argument of the eventual rsh(1) command.

COOKBOOKS

        In order to make use of this program, somewhere in your cookbook, you need to add a line
        which reads
                parallel_rsh = "cook";
        If the host chosen is the same as the caller (build host) then this program just exec the
        command skipping the rsh.  So it costs nothing to use this in a one machine network!

        For each recipe you want distributed to a remote host, you need to add a host-binding
        attribute to.  Typical usage is where you have a muti-architecture build.
                %1/%0%.o: %0%.c
                    host-binding %1 {
                    cc -o [target] -c [resolve %0%.c]; }
        In the recipe given here, each architecture has its object files placed into a separate
        architecture-specific directory tree.  The architecture name (%1) is used in the host-
        binding, so that the compiles may be load-balanced to all machines of that architecture.

        If you need a command to run on a specific host (say, because that's where a specific
        application license resides), then simply use the host name in the host-binding
        attribute, rather than an architecture name.

DEFINING THE CLASSES

        The /host_lists.pl file is expected to exist, and to contain variable definitions used to
        determine if hosts are members of particular architectures.

        The /host_lists.pl file defines a perl HOL "hash of lists" The hash is %ArchNames and it
        maps names of architectures as user want to see them, to list references as the actual
        lists are stored.

        The names of each architecture could be any form you wish but the convention is to use
        the GNUish names such as "sparc-sun-solaris2.8".

        For each architecture, define one or more lists of machines according to what function
        each machine set may do.  This can be as simple or as elaborate as required.  The form of
        the list variable name can be any valid perl identifier but may as well be like the
        architecture name with dash changed to underbar and dot removed, and the type added.  For
        example one might define solaris hosts as:
                @sparc_sun_solaris28_hosts = (
                   "mickey", "minny", "scrooge" );
        And linux hosts as:
                @i386_linux22_hosts = (
                   "goofy", "scrooge" );

        If there is a need to define different sets of machines for different types of jobs then
        add a suffix to the names in the  host-binding directive on each of the recipes, and
        lists here with the same suffix.

        The hash to map argument names to lists is defined like:
                %ArchNames = (
                  "sparc-solaris2.8",     => @sparc_solaris28_hosts,
                  "i586-unknown-linux22", => @i386_linux22_hosts, );

        Of course if users have differing opinions as to what the architecture names should look
        like, you can define "alias" mappings as well.
                  "sun4-SunOS-5.8",       => @sparc_solaris28_hosts,
        Or maybe the level is of no importance, then define
                  "sparc-solaris",        => @sparc_solaris28_hosts,
                  "sparc-solaris2.7",     => @sparc_solaris28_hosts,
        Also, this list isn't allowed to be empty.

        And finally, curtesy of Perl, the last line of the file must read
                1; for obscure and magical reasons.

SYSLOG LOGGING

        Typical commands seen during a build would look like
                sh -c 'cd /aegis/dd/gumby2.2.C079 && \ sh -ce /aegis/dd/gumby2.2.C079/.6.1; \
                echo $? > /aegis/dd/gumby2.2.C079/.6.2'
        So we can extract the project/ change from the command quite easily and logging it via
        syslog would be a trivial addition.

OPTIONS

        This command is not usually given any options.

        -h      Help - show usage info

        -vP     Verbose - report choice

        -Tn     Trace value for testing

FILES

        /exclude.hosts
                This file is used to list those host which must not be used by this script.
                Simply list excuded hosts, one hostname per line.  If the file is absent, all
                hosts reported by rup(1) may be used.

        /host_lists.pl
                This file defines the classes of hosts for each architecture.

AUTHOR

        Jerry Pendergraft <jerry@endocardial.com>