=head1 NAME

Maker - Yet Another Make-like Program

=head1 DESCRIPTION

Why yet another make?  I never found a make program that I thought was
easy and flexible enough.  Here are the key points:

=over 4

=item o Powerful Rules

Rules have two phases of execution.  Once when they are added to
the rule tree and once when they are executed.  The complete power of
perl is available at both times.  Rules do not need to be written only
in terms of arcane pattern matching.  This makes for more organic,
intelligent behavior.

=item o Minimal Inferencing

It's dumb to think of what you want then work backward to a
pre-inferred solution just to satisfy an inference engine that
re-solves your rules to get you what you started with.  Be-files state
exactly what to do in a direct procedural fashion.  If you want to
write Prolog, you can, but I don't want to know about it.

=item o Object-Oriented

Due to the adherence to object-oriented organization, multiple
targets can easily be built in the same be-file in a natural and
obvious manner.

=back

I have little hope of seeing this module gain widespread use.
/bin/make is far too entrenched, even if an alternative is superior in
all respects.  Furthermore, as more people start using Perl, makefiles
will become a headache of the past.

=head1 TECHNICAL DISCUSSION

Package.pm contains the framework that should be common across all
types of makefiles.  Rules.pm contains general and specific rules for
various general and specific transformation on source files.  As an
author or maintainer, you mostly need to understand Rules.pm.

In general, you need to create a new instance of Maker::Rules for each
target that you want to build.  The object keeps track of source
files, libraries, and special compile flags.  There are a bunch of
general utility methods that are worth mentioning.

=over 4

=item o x('cmd', 'arg1', ...)

Executes the given command.  Fails if status != 0.

=item o z('cmd', 'arg1', ...)

Executes the given command and returns exit status.

=item o clean('file')

Add the given file to the list of files to be removed upon 'be clean'.

=item o spotless('file')

Add the given file to the list of files to be removed upon 'be spotless'.

=item o src('file1', ...)

Adds the given files to Maker::Rules list of sources.

=item o get_src('type')

Returns all the source files match the given type.

=item o exe('exe', 'path')

Sets the path of the given exe.

=item o flags('exe', 'flags', ...)

Add the given flags to the given exe.

=back

Now, take a look at the follow rule snapped from Maker::Rules:

    sub pod2man {
        my ($o, $pod, $section) = @_;
        my $stem = $pod;
        $stem =~ s/\.[^.]+$//;			#1
        $o->clean("$stem.$section");		#2
        new Maker::Unit("$stem.$section", sub { #3
    	    if (newer("$stem.$section", $pod)) {
    	        $o->x("pod2man $pod > $stem.$section");
    	    }
        });
    }

1. The name of the target is derived from the name of the pod file.

2. The final result is added to the clean list.

3. A Maker::Unit is returned that encapsulates how to actually do the 
requested operation.

Instances of Maker::Unit are combined into sequences (Maker::Seq) or
parallel execution phases (Maker::Phase).  Maker::Seq and Maker::Phase
are pretty simple.  You may add Maker::Units to them upon creation or
with the method 'a' ('a' for add).

That's about it.  See the source for more examples.

=head1 TODO

=over 4

=item o

A front-end needs to be designed to make be-files very short and
simple.  I tend to think of the be-files as a target language for a
front-end preprocessor.  At least there should be a script to get
people up and compiling quick.

=item o

Makefile.PL translator

=item o

Better process management

=item o

Generate dependencies with makedepend and grok them.

=item o

RCS/SCCS/ClearCase support.

=item o

Parallel builds on multiple hosts.  (Already set up, should be easy.)

=item o

The documentation.

=back

=head1 AUTHOR

Joshua Pritikin, pritikin@mindspring.com

=head1 SEE ALSO

MakeMaker, /bin/make, gmake, nmake, imake, build, cook, plan9 make,
clearmake, ParallelMake, etc..

=cut

