This file gives a brief description of the new host attribute support in
customs and pmake.  This is a reimplementation of a very similar one
found in the customs version hacked by jclark@src.honeywell.com.

INTRODUCTION

The basic idea is to generalize the notion of `host architecture' as
embodied in the -arch flag to customs, and allow a hosts type and resources
to be described by arbitrary `attributes.'  Host attributes can be
arbitrary strings, typically descriptive of some resource, such as

    diskful
    32meg
    <the host's name>

Applicable attributes are specified at run-time when the customs daemon
is started on a host.  It communicates them to the customs master agent,
which can then use them to chose hosts for exportation.

Both the export command (to export a single command) and pmake allow
the specification of any conjunction of attributes to restrict the host
selection.


SETTING ATTRIBUTES

Attributes are just strings, specified as arguments to the -attr option
to customs. E.g.,

    # customs -attr diskful -attr 32meg -attr `hostname` ALL


DISPLAYING ATTRIBUTES

The reginfo command has been modified to display attributes in its
output.  E.g.

    % reginfo -showattr
    HOST          ARCH   ATTRIBUTES
    host             4   host diskful 32meg
    ...

Any combination of attributes may be specified to list the corresponding subset
of hosts:

    % reginfo -attr diskful -attr 32meg

An -attr string may contain a ``!'' in first position to denote negation.
A negated attribute is is satisfied if the host in question does NOT have
the attribute set. (The negation sign has to be quoted in the Cshell.)
Also, the pseudo-attribute ``OR'' can be given so describe a disjunction:

    % reginfo -attr diskful -attr OR -attr 32meg

Combinations of attributes between ``OR'' are interpreted as conjunctions,
i.e., the entire expression is in disjunctive normal form (but notice the
awkward -attr flag before each literal or OR operator).

USING ATTRIBUTES

With export, just specify any number of attributes as flags:

    % export -attr 32meg -attr \!sun3 command

If no other host matching the attributes is available, and the local host
doesn't match itself, the command will not be executed *at all*.

With pmake, required attributes are specified on a per-target basis, as
pseudo-sources:

    # this one drives the optimizer nuts
    bigfile.o: .EXPORT=32meg .EXPORT=diskful
	
Sources to the .EXPORT special target are taken as globally required
attributes, e.g.:

    .EXPORT:	diskful OR fast

(Disjunctions work counter-intuitively in that the attribute specs from 
the target and any global ones are simply concatenated, and OR's is
interpreted in the resulting list as a delimiter or disjuncts.)

Some special pseudo-attributes are handled directly by pmake:
``SAME'' restricts exportation to machines with the same architecture code.
``USELOCAL'' tells pmake to check the local host before attempting
exportation, similar to a negative -L option. ``EXCLUSIVE'' requests
exclusive use (no other imported jobs) on the host machine.  Note that

    .EXPORT:	SAME

appears in the system makefile for convenience.  This may be disabled with

    .EXPORT:

Again, the command(s) for the target will not just be silently executed
locally if no suitable host (including the local one) can be found.
Instead, the job is deferred and exportation attempted again later
(checks are every ten seconds), until a host is found or pmake terminates
due to an error.

The deferment feature lets you use pmake as a scheduler for batch jobs,
dispatching commands as resources become available.

Finally, .EXPORT or .EXPORT= can be combined with the .RESTART directive
to manage long-running jobs that could be evicted and restarted while
running exported.  See tests/count.mk for a sample makefile, and
tests/count for a simple shell scripts that demonstrates the signal
handling and state saving required.

[$Id: ATTRIBUTES,v 1.8 1995/02/11 19:14:47 stolcke Exp $]
