File Coverage

=head1 NAME

Automake::Rule - support for rules definitions

=head1 SYNOPSIS

  use Automake::Rule;
  use Automake::RuleDef;


=head1 DESCRIPTION

This package provides support for Makefile rule definitions.

An C<Automake::Rule> is a rule name associated to possibly
many conditional definitions.  These definitions are instances
of C<Automake::RuleDef>.

Therefore obtaining the value of a rule under a given
condition involves two lookups.  One to look up the rule,
and one to look up the conditional definition:

  my $rule = rule $name;
  if ($rule)
    {
      my $def = $rule->def ($cond);
      if ($def)
	{
	  return $def->location;
	}
      ...
    }
  ...

when it is known that the rule and the definition
being looked up exist, the above can be simplified to

  return rule ($name)->def ($cond)->location; # do not write this.

but is better written

  return rrule ($name)->rdef ($cond)->location;

or even

  return rruledef ($name, $cond)->location;

The I<r> variants of the C<rule>, C<def>, and C<ruledef> methods add
an extra test to ensure that the lookup succeeded, and will diagnose
failures as internal errors (with a message which is much more
informative than Perl's warning about calling a method on a
non-object).

=head2 Global variables

=over 4

=cut

=item C<%dependencies>

Holds the dependencies of targets which dependencies are factored.
Typically, C<.PHONY> will appear in plenty of F<*.am> files, but must
be output once.  Arguably all pure dependencies could be subject to
this factoring, but it is not unpleasant to have paragraphs in
Makefile: keeping related stuff altogether.

=cut

=item <%actions>

Holds the factored actions.  Tied to C<%dependencies>, i.e., filled
only when keys exists in C<%dependencies>.

=cut

=item <$suffix_rules>

This maps the source extension for all suffix rule seen to
a C<hash> whose keys are the possible output extensions.

Note that this is transitively closed by construction:
if we have
      exists $suffix_rules{$ext1}{$ext2}
   && exists $suffix_rules{$ext2}{$ext3}
then we also have
      exists $suffix_rules{$ext1}{$ext3}

So it's easy to check whether C<.foo> can be transformed to
C<.$(OBJEXT)> by checking whether
C<$suffix_rules{'.foo'}{'.$(OBJEXT)'}> exists.  This will work even if
transforming C<.foo> to C<.$(OBJEXT)> involves a chain of several
suffix rules.

The value of C<$suffix_rules{$ext1}{$ext2}> is a pair
C<[ $next_sfx, $dist ]> where C<$next_sfx> is target suffix
for the next rule to use to reach C<$ext2>, and C<$dist> the
distance to C<$ext2'>.

The content of this variable should be updated via the
C<register_suffix_rule> function.

=cut

=item C<$KNOWN_EXTENSIONS_PATTERN>

Pattern that matches all know input extensions (i.e. extensions used
by the languages supported by Automake).  Using this pattern (instead
of `\..*$') to match extensions allows Automake to support dot-less
extensions.

New extensions should be registered with C<accept_extensions>.

=cut

=head2 Error reporting functions

In these functions, C<$rule> can be either a rule name, or
an instance of C<Automake::Rule>.

=over 4

=item C<err_rule ($rule, $message, [%options])>

Uncategorized errors about rules.

=cut

=item C<err_cond_rule ($cond, $rule, $message, [%options])>

Uncategorized errors about conditional rules.

=cut

=item C<msg_cond_rule ($channel, $cond, $rule, $message, [%options])>

Messages about conditional rules.

=cut

=item C<msg_rule ($channel, $targetname, $message, [%options])>

Messages about rules.

=cut

=item C<$bool = reject_rule ($rule, $error_msg)>

Bail out with C<$error_msg> if a rule with name C<$rule> has been
defined.

Return true iff C<$rule> is defined.

=cut

=head2 Administrative functions

=over 4

=item C<accept_extensions (@exts)>

Update C<$KNOWN_EXTENSIONS_PATTERN> to recognize the extensions
listed C<@exts>.  Extensions should contain a dot if needed.

=cut

=item C<rules>

Return the list of all L<Automake::Rule> instances.  (I.e., all
rules defined so far.)

=cut

=item C<register_action($target, $action)>

Append the C<$action> to C<$actions{$target}> taking care of special
cases.

=cut

=item C<Automake::Rule::reset>

The I<forget all> function.  Clears all know rules and reset some
other internal data.

=cut

=item C<register_suffix_rule ($where, $src, $dest)>

Register a suffix rules defined on C<$where> that transform
files ending in C<$src> into files ending in C<$dest>.

This upgrades the C<$suffix_rules> variables.

=cut

=item C<$count = suffix_rules_count>

Return the number of suffix rules added while processing the current
F<Makefile> (excluding predefined suffix rules).

=cut

=item C<@list = suffixes>

Return the list of known suffixes.

=cut

=item C<rule ($rulename)>

Return the C<Automake::Rule> object for the rule
named C<$rulename> if defined.  Return 0 otherwise.

=cut

=item C<ruledef ($rulename, $cond)>

Return the C<Automake::RuleDef> object for the rule named
C<$rulename> if defined in condition C<$cond>.  Return false
if the condition or the rule does not exist.

=cut

=item C<rrule ($rulename)

Return the C<Automake::Rule> object for the variable named
C<$rulename>.  Abort with an internal error if the variable was not
defined.

The I<r> in front of C<var> stands for I<required>.  One
should call C<rvar> to assert the rule's existence.

=cut

=item C<rruledef ($varname, $cond)>

Return the C<Automake::RuleDef> object for the rule named
C<$rulename> if defined in condition C<$cond>.  Abort with an internal
error if the condition or the rule does not exist.

=cut

=item C<@conds = define ($rulename, $source, $owner, $cond, $where)>

Define a new rule.  C<$rulename> is the list of targets.  C<$source>
is the filename the rule comes from.  C<$owner> is the owner of the
rule (C<RULE_AUTOMAKE> or C<RULE_USER>).  C<$cond> is the
C<Automake::Condition> under which the rule is defined.  C<$where> is
the C<Automake::Location> where the rule is defined.

Returns a (possibly empty) list of C<Automake::Condition>s where the
rule's definition should be output.

=cut

=item C<depend ($target, @deps)>

Adds C<@deps> to the dependencies of target C<$target>.  This should
be used only with factored targets (those appearing in
C<%dependees>).

=cut

=head1 SEE ALSO

L<Automake::RuleDef>, L<Automake::Condition>,
L<Automake::DisjConditions>, L<Automake::Location>.

=cut