"Fossies" - the Fresh Open Source Software Archive

Member "automake-1.16.3/lib/Automake/Rule.pm" (19 Nov 2020, 24103 Bytes) of package /linux/misc/automake-1.16.3.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Rule.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.16.2_vs_1.16.3.

    1 # Copyright (C) 2003-2020 Free Software Foundation, Inc.
    2 
    3 # This program is free software; you can redistribute it and/or modify
    4 # it under the terms of the GNU General Public License as published by
    5 # the Free Software Foundation; either version 2, or (at your option)
    6 # any later version.
    7 
    8 # This program is distributed in the hope that it will be useful,
    9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
   10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   11 # GNU General Public License for more details.
   12 
   13 # You should have received a copy of the GNU General Public License
   14 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
   15 
   16 package Automake::Rule;
   17 
   18 use 5.006;
   19 use strict;
   20 use warnings FATAL => 'all';
   21 
   22 use Carp;
   23 use Exporter;
   24 
   25 use Automake::Item;
   26 use Automake::RuleDef;
   27 use Automake::ChannelDefs;
   28 use Automake::Channels;
   29 use Automake::Options;
   30 use Automake::Condition qw (TRUE FALSE);
   31 use Automake::DisjConditions;
   32 
   33 our @ISA = qw (Automake::Item Exporter);
   34 our @EXPORT = qw (reset register_suffix_rule next_in_suffix_chain
   35           suffixes rules $KNOWN_EXTENSIONS_PATTERN
   36           depend %dependencies %actions register_action
   37           accept_extensions
   38           reject_rule msg_rule msg_cond_rule err_rule err_cond_rule
   39           rule rrule ruledef rruledef);
   40 
   41 =head1 NAME
   42 
   43 Automake::Rule - support for rules definitions
   44 
   45 =head1 SYNOPSIS
   46 
   47   use Automake::Rule;
   48   use Automake::RuleDef;
   49 
   50 
   51 =head1 DESCRIPTION
   52 
   53 This package provides support for Makefile rule definitions.
   54 
   55 An C<Automake::Rule> is a rule name associated to possibly
   56 many conditional definitions.  These definitions are instances
   57 of C<Automake::RuleDef>.
   58 
   59 Therefore obtaining the value of a rule under a given
   60 condition involves two lookups.  One to look up the rule,
   61 and one to look up the conditional definition:
   62 
   63   my $rule = rule $name;
   64   if ($rule)
   65     {
   66       my $def = $rule->def ($cond);
   67       if ($def)
   68     {
   69       return $def->location;
   70     }
   71       ...
   72     }
   73   ...
   74 
   75 when it is known that the rule and the definition
   76 being looked up exist, the above can be simplified to
   77 
   78   return rule ($name)->def ($cond)->location; # do not write this.
   79 
   80 but is better written
   81 
   82   return rrule ($name)->rdef ($cond)->location;
   83 
   84 or even
   85 
   86   return rruledef ($name, $cond)->location;
   87 
   88 The I<r> variants of the C<rule>, C<def>, and C<ruledef> methods add
   89 an extra test to ensure that the lookup succeeded, and will diagnose
   90 failures as internal errors (with a message which is much more
   91 informative than Perl's warning about calling a method on a
   92 non-object).
   93 
   94 =head2 Global variables
   95 
   96 =over 4
   97 
   98 =cut
   99 
  100 my $_SUFFIX_RULE_PATTERN =
  101   '^(\.[a-zA-Z0-9_(){}$+@\-]+)(\.[a-zA-Z0-9_(){}$+@\-]+)' . "\$";
  102 
  103 my @_suffixes = ();
  104 my @_known_extensions_list = ();
  105 my %_rule_dict = ();
  106 
  107 # See comments in the implementation of the 'next_in_suffix_chain()'
  108 # variable for details.
  109 my %_suffix_rules;
  110 
  111 # Same as $suffix_rules, but records only the default rules
  112 # supplied by the languages Automake supports.
  113 my %_suffix_rules_builtin;
  114 
  115 =item C<%dependencies>
  116 
  117 Holds the dependencies of targets which dependencies are factored.
  118 Typically, C<.PHONY> will appear in plenty of F<*.am> files, but must
  119 be output once.  Arguably all pure dependencies could be subject to
  120 this factoring, but it is not unpleasant to have paragraphs in
  121 Makefile: keeping related stuff altogether.
  122 
  123 =cut
  124 
  125 our %dependencies;
  126 
  127 =item <%actions>
  128 
  129 Holds the factored actions.  Tied to C<%dependencies>, i.e., filled
  130 only when keys exists in C<%dependencies>.
  131 
  132 =cut
  133 
  134 our %actions;
  135 
  136 =item C<$KNOWN_EXTENSIONS_PATTERN>
  137 
  138 Pattern that matches all know input extensions (i.e. extensions used
  139 by the languages supported by Automake).  Using this pattern (instead
  140 of '\..*$') to match extensions allows Automake to support dot-less
  141 extensions.
  142 
  143 New extensions should be registered with C<accept_extensions>.
  144 
  145 =cut
  146 
  147 our $KNOWN_EXTENSIONS_PATTERN = "";
  148 
  149 =back
  150 
  151 =head2 Error reporting functions
  152 
  153 In these functions, C<$rule> can be either a rule name, or
  154 an instance of C<Automake::Rule>.
  155 
  156 =over 4
  157 
  158 =item C<err_rule ($rule, $message, [%options])>
  159 
  160 Uncategorized errors about rules.
  161 
  162 =cut
  163 
  164 sub err_rule ($$;%)
  165 {
  166   msg_rule ('error', @_);
  167 }
  168 
  169 =item C<err_cond_rule ($cond, $rule, $message, [%options])>
  170 
  171 Uncategorized errors about conditional rules.
  172 
  173 =cut
  174 
  175 sub err_cond_rule ($$$;%)
  176 {
  177   msg_cond_rule ('error', @_);
  178 }
  179 
  180 =item C<msg_cond_rule ($channel, $cond, $rule, $message, [%options])>
  181 
  182 Messages about conditional rules.
  183 
  184 =cut
  185 
  186 sub msg_cond_rule ($$$$;%)
  187 {
  188   my ($channel, $cond, $rule, $msg, %opts) = @_;
  189   my $r = ref ($rule) ? $rule : rrule ($rule);
  190   msg $channel, $r->rdef ($cond)->location, $msg, %opts;
  191 }
  192 
  193 =item C<msg_rule ($channel, $targetname, $message, [%options])>
  194 
  195 Messages about rules.
  196 
  197 =cut
  198 
  199 sub msg_rule ($$$;%)
  200 {
  201   my ($channel, $rule, $msg, %opts) = @_;
  202   my $r = ref ($rule) ? $rule : rrule ($rule);
  203   # Don't know which condition is concerned.  Pick any.
  204   my $cond = $r->conditions->one_cond;
  205   msg_cond_rule ($channel, $cond, $r, $msg, %opts);
  206 }
  207 
  208 
  209 =item C<$bool = reject_rule ($rule, $error_msg)>
  210 
  211 Bail out with C<$error_msg> if a rule with name C<$rule> has been
  212 defined.
  213 
  214 Return true iff C<$rule> is defined.
  215 
  216 =cut
  217 
  218 sub reject_rule ($$)
  219 {
  220   my ($rule, $msg) = @_;
  221   if (rule ($rule))
  222     {
  223       err_rule $rule, $msg;
  224       return 1;
  225     }
  226   return 0;
  227 }
  228 
  229 =back
  230 
  231 =head2 Administrative functions
  232 
  233 =over 4
  234 
  235 =item C<accept_extensions (@exts)>
  236 
  237 Update C<$KNOWN_EXTENSIONS_PATTERN> to recognize the extensions
  238 listed in C<@exts>.  Extensions should contain a dot if needed.
  239 
  240 =cut
  241 
  242 sub accept_extensions (@)
  243 {
  244     push @_known_extensions_list, @_;
  245     $KNOWN_EXTENSIONS_PATTERN =
  246     '(?:' . join ('|', map (quotemeta, @_known_extensions_list)) . ')';
  247 }
  248 
  249 =item C<rules>
  250 
  251 Return the list of all L<Automake::Rule> instances.  (I.e., all
  252 rules defined so far.)
  253 
  254 =cut
  255 
  256 sub rules ()
  257 {
  258   return values %_rule_dict;
  259 }
  260 
  261 
  262 =item C<register_action($target, $action)>
  263 
  264 Append the C<$action> to C<$actions{$target}> taking care of special
  265 cases.
  266 
  267 =cut
  268 
  269 sub register_action ($$)
  270 {
  271   my ($target, $action) = @_;
  272   if ($actions{$target})
  273     {
  274       $actions{$target} .= "\n$action" if $action;
  275     }
  276   else
  277     {
  278       $actions{$target} = $action;
  279     }
  280 }
  281 
  282 
  283 =item C<Automake::Rule::reset>
  284 
  285 The I<forget all> function.  Clears all known rules and resets some
  286 other internal data.
  287 
  288 =cut
  289 
  290 sub reset()
  291 {
  292   %_rule_dict = ();
  293   @_suffixes = ();
  294   %_suffix_rules = %_suffix_rules_builtin;
  295 
  296   %dependencies =
  297     (
  298      # Texinfoing.
  299      'dvi'      => [],
  300      'dvi-am'   => [],
  301      'pdf'      => [],
  302      'pdf-am'   => [],
  303      'ps'       => [],
  304      'ps-am'    => [],
  305      'info'     => [],
  306      'info-am'  => [],
  307      'html'     => [],
  308      'html-am'  => [],
  309 
  310      # Installing/uninstalling.
  311      'install-data-am'      => [],
  312      'install-exec-am'      => [],
  313      'uninstall-am'         => [],
  314 
  315      'install-man'      => [],
  316      'uninstall-man'        => [],
  317 
  318      'install-dvi'          => [],
  319      'install-dvi-am'       => [],
  320      'install-html'         => [],
  321      'install-html-am'      => [],
  322      'install-info'         => [],
  323      'install-info-am'      => [],
  324      'install-pdf'          => [],
  325      'install-pdf-am'       => [],
  326      'install-ps'           => [],
  327      'install-ps-am'        => [],
  328 
  329      'installcheck-am'      => [],
  330 
  331      # Cleaning.
  332      'clean-am'             => [],
  333      'mostlyclean-am'       => [],
  334      'maintainer-clean-am'  => [],
  335      'distclean-am'         => [],
  336      'clean'                => [],
  337      'mostlyclean'          => [],
  338      'maintainer-clean'     => [],
  339      'distclean'            => [],
  340 
  341      # Tarballing.
  342      'dist-all'             => [],
  343 
  344      '.PHONY'               => [],
  345      '.PRECIOUS'            => [],
  346      # Recursive install targets (so "make -n install" works for BSD Make).
  347      '.MAKE'            => [],
  348      );
  349   %actions = ();
  350 }
  351 
  352 =item C<next_in_suffix_chain ($ext1, $ext2)>
  353 
  354 Return the target suffix for the next rule to use to reach C<$ext2>
  355 from C<$ext1>, or C<undef> if no such rule exists.
  356 
  357 =cut
  358 
  359 sub next_in_suffix_chain ($$)
  360 {
  361   my ($ext1, $ext2) = @_;
  362   return undef unless (exists $_suffix_rules{$ext1} and
  363                        exists $_suffix_rules{$ext1}{$ext2});
  364   return $_suffix_rules{$ext1}{$ext2}[0];
  365 }
  366 
  367 =item C<register_suffix_rule ($where, $src, $dest)>
  368 
  369 Register a suffix rule defined on C<$where> that transforms
  370 files ending in C<$src> into files ending in C<$dest>.
  371 
  372 =cut
  373 
  374 sub register_suffix_rule ($$$)
  375 {
  376   my ($where, $src, $dest) = @_;
  377   my $suffix_rules = $where->{'position'} ? \%_suffix_rules
  378                                           : \%_suffix_rules_builtin;
  379 
  380   verb "Sources ending in $src become $dest";
  381   push @_suffixes, $src, $dest;
  382 
  383   # When transforming sources to objects, Automake uses the
  384   # %suffix_rules to move from each source extension to
  385   # '.$(OBJEXT)', not to '.o' or '.obj'.  However some people
  386   # define suffix rules for '.o' or '.obj', so internally we will
  387   # consider these extensions equivalent to '.$(OBJEXT)'.  We
  388   # CANNOT rewrite the target (i.e., automagically replace '.o'
  389   # and '.obj' by '.$(OBJEXT)' in the output), or warn the user
  390   # that (s)he'd better use '.$(OBJEXT)', because Automake itself
  391   # output suffix rules for '.o' or '.obj' ...
  392   $dest = '.$(OBJEXT)' if ($dest eq '.o' || $dest eq '.obj');
  393 
  394   # ----------------------------------------------------------------------
  395   # The $suffix_rules variable maps the source extension for all suffix
  396   # rules seen to a hash whose keys are the possible output extensions.
  397   #
  398   # Note that this is transitively closed by construction:
  399   # if we have
  400   #
  401   #       exists $suffix_rules{$ext1}{$ext2}
  402   #    && exists $suffix_rules{$ext2}{$ext3}
  403   #
  404   # then we also have
  405   #
  406   #       exists $suffix_rules{$ext1}{$ext3}
  407   #
  408   # So it's easy to check whether '.foo' can be transformed to
  409   # '.$(OBJEXT)' by checking whether $suffix_rules{'.foo'}{'.$(OBJEXT)'}
  410   # exists.  This will work even if transforming '.foo' to '.$(OBJEXT)'
  411   # involves a chain of several suffix rules.
  412   #
  413   # The value of $suffix_rules{$ext1}{$ext2} is a pair [$next_sfx, $dist]
  414   # where $next_sfx is target suffix for the next rule to use to reach
  415   # $ext2, and $dist the distance to $ext2.
  416   # ----------------------------------------------------------------------
  417 
  418   # Register $dest as a possible destination from $src.
  419   # We might have the create the \hash.
  420   if (exists $suffix_rules->{$src})
  421     {
  422       $suffix_rules->{$src}{$dest} = [ $dest, 1 ];
  423     }
  424   else
  425     {
  426       $suffix_rules->{$src} = { $dest => [ $dest, 1 ] };
  427     }
  428 
  429   # If we know how to transform $dest in something else, then
  430   # we know how to transform $src in that "something else".
  431   if (exists $suffix_rules->{$dest})
  432     {
  433       for my $dest2 (keys %{$suffix_rules->{$dest}})
  434     {
  435       my $dist = $suffix_rules->{$dest}{$dest2}[1] + 1;
  436       # Overwrite an existing $src->$dest2 path only if
  437       # the path via $dest which is shorter.
  438       if (! exists $suffix_rules->{$src}{$dest2}
  439           || $suffix_rules->{$src}{$dest2}[1] > $dist)
  440         {
  441           $suffix_rules->{$src}{$dest2} = [ $dest, $dist ];
  442         }
  443     }
  444     }
  445 
  446   # Similarly, any extension that can be derived into $src
  447   # can be derived into the same extensions as $src can.
  448   my @dest2 = keys %{$suffix_rules->{$src}};
  449   for my $src2 (keys %$suffix_rules)
  450     {
  451       if (exists $suffix_rules->{$src2}{$src})
  452     {
  453       for my $dest2 (@dest2)
  454         {
  455           my $dist = $suffix_rules->{$src}{$dest2} + 1;
  456           # Overwrite an existing $src2->$dest2 path only if
  457           # the path via $src is shorter.
  458           if (! exists $suffix_rules->{$src2}{$dest2}
  459           || $suffix_rules->{$src2}{$dest2}[1] > $dist)
  460         {
  461           $suffix_rules->{$src2}{$dest2} = [ $src, $dist ];
  462         }
  463         }
  464     }
  465     }
  466 }
  467 
  468 =item C<@list = suffixes>
  469 
  470 Return the list of known suffixes.
  471 
  472 =cut
  473 
  474 sub suffixes ()
  475 {
  476   return @_suffixes;
  477 }
  478 
  479 =item C<rule ($rulename)>
  480 
  481 Return the C<Automake::Rule> object for the rule
  482 named C<$rulename> if defined.  Return 0 otherwise.
  483 
  484 =cut
  485 
  486 sub rule ($)
  487 {
  488   my ($name) = @_;
  489   # Strip $(EXEEXT) from $name, so we can diagnose
  490   # a clash if 'ctags$(EXEEXT):' is redefined after 'ctags:'.
  491   $name =~ s,\$\(EXEEXT\)$,,;
  492   return $_rule_dict{$name} || 0;
  493 }
  494 
  495 =item C<ruledef ($rulename, $cond)>
  496 
  497 Return the C<Automake::RuleDef> object for the rule named
  498 C<$rulename> if defined in condition C<$cond>.  Return false
  499 if the condition or the rule does not exist.
  500 
  501 =cut
  502 
  503 sub ruledef ($$)
  504 {
  505   my ($name, $cond) = @_;
  506   my $rule = rule $name;
  507   return $rule && $rule->def ($cond);
  508 }
  509 
  510 =item C<rrule ($rulename)
  511 
  512 Return the C<Automake::Rule> object for the variable named
  513 C<$rulename>.  Abort with an internal error if the variable was not
  514 defined.
  515 
  516 The I<r> in front of C<var> stands for I<required>.  One
  517 should call C<rvar> to assert the rule's existence.
  518 
  519 =cut
  520 
  521 sub rrule ($)
  522 {
  523   my ($name) = @_;
  524   my $r = rule $name;
  525   prog_error ("undefined rule $name\n" . &rules_dump)
  526     unless $r;
  527   return $r;
  528 }
  529 
  530 =item C<rruledef ($varname, $cond)>
  531 
  532 Return the C<Automake::RuleDef> object for the rule named
  533 C<$rulename> if defined in condition C<$cond>.  Abort with an internal
  534 error if the condition or the rule does not exist.
  535 
  536 =cut
  537 
  538 sub rruledef ($$)
  539 {
  540   my ($name, $cond) = @_;
  541   return rrule ($name)->rdef ($cond);
  542 }
  543 
  544 # Create the variable if it does not exist.
  545 # This is used only by other functions in this package.
  546 sub _crule ($)
  547 {
  548   my ($name) = @_;
  549   my $r = rule $name;
  550   return $r if $r;
  551   return _new Automake::Rule $name;
  552 }
  553 
  554 sub _new ($$)
  555 {
  556   my ($class, $name) = @_;
  557 
  558   # Strip $(EXEEXT) from $name, so we can diagnose
  559   # a clash if 'ctags$(EXEEXT):' is redefined after 'ctags:'.
  560   (my $keyname = $name) =~ s,\$\(EXEEXT\)$,,;
  561 
  562   my $self = Automake::Item::new ($class, $name);
  563   $_rule_dict{$keyname} = $self;
  564   return $self;
  565 }
  566 
  567 sub _rule_defn_with_exeext_awareness ($$$)
  568 {
  569   my ($target, $cond, $where) = @_;
  570 
  571   # For now 'foo:' will override 'foo$(EXEEXT):'.  This is temporary,
  572   # though, so we emit a warning.
  573   (my $noexe = $target) =~ s/\$\(EXEEXT\)$//;
  574   my $noexerule = rule $noexe;
  575   my $tdef = $noexerule ? $noexerule->def ($cond) : undef;
  576 
  577   if ($noexe ne $target
  578       && $tdef
  579       && $noexerule->name ne $target)
  580     {
  581       # The no-exeext option enables this feature.
  582       if (! option 'no-exeext')
  583     {
  584       msg ('obsolete', $tdef->location,
  585            "deprecated feature: target '$noexe' overrides "
  586            . "'$noexe\$(EXEEXT)'\n"
  587            . "change your target to read '$noexe\$(EXEEXT)'",
  588            partial => 1);
  589       msg ('obsolete', $where, "target '$target' was defined here");
  590     }
  591     }
  592     return $tdef;
  593 }
  594 
  595 sub _maybe_warn_about_duplicated_target ($$$$$$)
  596 {
  597   my ($target, $tdef, $source, $owner, $cond, $where) = @_;
  598 
  599   my $oldowner  = $tdef->owner;
  600   # Ok, it's the name target, but the name maybe different because
  601   # 'foo$(EXEEXT)' and 'foo' have the same key in our table.
  602   my $oldname = $tdef->name;
  603 
  604   # Don't mention true conditions in diagnostics.
  605   my $condmsg =
  606     $cond == TRUE ? '' : (" in condition '" . $cond->human . "'");
  607 
  608   if ($owner == RULE_USER)
  609     {
  610       if ($oldowner == RULE_USER)
  611         {
  612           # Ignore '%'-style pattern rules.  We'd need the
  613           # dependencies to detect duplicates, and they are
  614           # already diagnosed as unportable by -Wportability.
  615           if ($target !~ /^[^%]*%[^%]*$/)
  616             {
  617               ## FIXME: Presently we can't diagnose duplicate user rules
  618               ## because we don't distinguish rules with commands
  619               ## from rules that only add dependencies.  E.g.,
  620               ##   .PHONY: foo
  621               ##   .PHONY: bar
  622               ## is legitimate.  This is checked in the 'phony.sh' test.
  623 
  624               # msg ('syntax', $where,
  625               #      "redefinition of '$target'$condmsg ...", partial => 1);
  626               # msg_cond_rule ('syntax', $cond, $target,
  627               #                "... '$target' previously defined here");
  628             }
  629         }
  630       else
  631         {
  632           # Since we parse the user Makefile.am before reading
  633           # the Automake fragments, this condition should never happen.
  634           prog_error ("user target '$target'$condmsg seen after Automake's"
  635                       . " definition\nfrom " . $tdef->source);
  636         }
  637     }
  638   else # $owner == RULE_AUTOMAKE
  639     {
  640       if ($oldowner == RULE_USER)
  641         {
  642           # -am targets listed in %dependencies support a -local
  643           # variant.  If the user tries to override TARGET or
  644           # TARGET-am for which there exists a -local variant,
  645           # just tell the user to use it.
  646           my $hint = 0;
  647           my $noam = $target;
  648           $noam =~ s/-am$//;
  649           if (exists $dependencies{"$noam-am"})
  650             {
  651               $hint = "consider using $noam-local instead of $target";
  652             }
  653 
  654           msg_cond_rule ('override', $cond, $target,
  655                          "user target '$target' defined here"
  656                          . "$condmsg ...", partial => 1);
  657           msg ('override', $where,
  658                "... overrides Automake target '$oldname' defined here",
  659                partial => $hint);
  660           msg_cond_rule ('override', $cond, $target, $hint)
  661             if $hint;
  662         }
  663       else # $oldowner == RULE_AUTOMAKE
  664         {
  665           # Automake should ignore redefinitions of its own
  666           # rules if they came from the same file.  This makes
  667           # it easier to process a Makefile fragment several times.
  668           # However it's an error if the target is defined in many
  669           # files.  E.g., the user might be using bin_PROGRAMS = ctags
  670           # which clashes with our 'ctags' rule.
  671           # (It would be more accurate if we had a way to compare
  672           # the *content* of both rules.  Then $targets_source would
  673           # be useless.)
  674           my $oldsource = $tdef->source;
  675           if (not ($source eq $oldsource && $target eq $oldname))
  676             {
  677                msg ('syntax',
  678                     $where, "redefinition of '$target'$condmsg ...",
  679                     partial => 1);
  680                msg_cond_rule ('syntax', $cond, $target,
  681                               "... '$oldname' previously defined here");
  682             }
  683         }
  684     }
  685 }
  686 
  687 # Return the list of conditionals in which the rule was defined.  In case
  688 # an ambiguous conditional definition is detected, return the empty list.
  689 sub _conditionals_for_rule ($$$$)
  690 {
  691   my ($rule, $owner, $cond, $where) = @_;
  692   my $target = $rule->name;
  693   my @conds;
  694   my ($message, $ambig_cond) = $rule->conditions->ambiguous_p ($target, $cond);
  695 
  696   return $cond if !$message; # No ambiguity.
  697 
  698   if ($owner == RULE_USER)
  699     {
  700       # For user rules, just diagnose the ambiguity.
  701       msg 'syntax', $where, "$message ...", partial => 1;
  702       msg_cond_rule ('syntax', $ambig_cond, $target,
  703                      "... '$target' previously defined here");
  704       return ();
  705     }
  706 
  707   # FIXME: for Automake rules, we can't diagnose ambiguities yet.
  708   # The point is that Automake doesn't propagate conditions
  709   # everywhere.  For instance &handle_PROGRAMS doesn't care if
  710   # bin_PROGRAMS was defined conditionally or not.
  711   # On the following input
  712   #   if COND1
  713   #   foo:
  714   #           ...
  715   #   else
  716   #   bin_PROGRAMS = foo
  717   #   endif
  718   # &handle_PROGRAMS will attempt to define a 'foo:' rule
  719   # in condition TRUE (which conflicts with COND1).  Fixing
  720   # this in &handle_PROGRAMS and siblings seems hard: you'd
  721   # have to explain &file_contents what to do with a
  722   # condition.  So for now we do our best *here*.  If 'foo:'
  723   # was already defined in condition COND1 and we want to define
  724   # it in condition TRUE, then define it only in condition !COND1.
  725   # (See cond14.sh and cond15.sh for some test cases.)
  726   @conds = $rule->not_always_defined_in_cond ($cond)->conds;
  727 
  728   # No conditions left to define the rule.
  729   # Warn, because our workaround is meaningless in this case.
  730   if (scalar @conds == 0)
  731     {
  732       msg 'syntax', $where, "$message ...", partial => 1;
  733       msg_cond_rule ('syntax', $ambig_cond, $target,
  734                      "... '$target' previously defined here");
  735       return ();
  736     }
  737   return @conds;
  738 }
  739 
  740 =item C<@conds = define ($rulename, $source, $owner, $cond, $where)>
  741 
  742 Define a new rule.  C<$rulename> is the list of targets.  C<$source>
  743 is the filename the rule comes from.  C<$owner> is the owner of the
  744 rule (C<RULE_AUTOMAKE> or C<RULE_USER>).  C<$cond> is the
  745 C<Automake::Condition> under which the rule is defined.  C<$where> is
  746 the C<Automake::Location> where the rule is defined.
  747 
  748 Returns a (possibly empty) list of C<Automake::Condition>s where the
  749 rule's definition should be output.
  750 
  751 =cut
  752 
  753 sub define ($$$$$)
  754 {
  755   my ($target, $source, $owner, $cond, $where) = @_;
  756 
  757   prog_error "$where is not a reference"
  758     unless ref $where;
  759   prog_error "$cond is not a reference"
  760     unless ref $cond;
  761 
  762   # Don't even think about defining a rule in condition FALSE.
  763   return () if $cond == FALSE;
  764 
  765   my $tdef = _rule_defn_with_exeext_awareness ($target, $cond, $where);
  766 
  767   # A GNU make-style pattern rule has a single "%" in the target name.
  768   msg ('portability', $where,
  769        "'%'-style pattern rules are a GNU make extension")
  770     if $target =~ /^[^%]*%[^%]*$/;
  771 
  772   # See whether this is a duplicated target declaration.
  773   if ($tdef)
  774     {
  775       # Diagnose invalid target redefinitions, if any.  Note that some
  776       # target redefinitions are valid (e.g., for multiple-targets
  777       # pattern rules).
  778       _maybe_warn_about_duplicated_target ($target, $tdef, $source,
  779                                            $owner, $cond, $where);
  780       # Return so we don't redefine the rule in our tables, don't check
  781       # for ambiguous condition, etc.  The rule will be output anyway
  782       # because '&read_am_file' ignores the return code.
  783       return ();
  784     }
  785 
  786   my $rule = _crule $target;
  787 
  788   # Conditions for which the rule should be defined.  Due to some
  789   # complications in the automake internals, this aspect is not as
  790   # obvious as it might be, and in come cases this list must contain
  791   # other entries in addition to '$cond'.  See the comments in
  792   # '_conditionals_for_rule' for a rationale.
  793   my @conds = _conditionals_for_rule ($rule, $owner, $cond, $where);
  794 
  795   # Stop if we had ambiguous conditional definitions.
  796   return unless @conds;
  797 
  798   # Finally define this rule.
  799   for my $c (@conds)
  800     {
  801       my $def = new Automake::RuleDef ($target, '', $where->clone,
  802                        $owner, $source);
  803       $rule->set ($c, $def);
  804     }
  805 
  806   # We honor inference rules with multiple targets because many
  807   # makes support this and people use it.  However this is disallowed
  808   # by POSIX.  We'll print a warning later.
  809   my $target_count = 0;
  810   my $inference_rule_count = 0;
  811 
  812   for my $t (split (' ', $target))
  813     {
  814       ++$target_count;
  815       # Check if the rule is a suffix rule: either it's a rule for
  816       # two known extensions...
  817       if ($t =~ /^($KNOWN_EXTENSIONS_PATTERN)($KNOWN_EXTENSIONS_PATTERN)$/
  818       # ...or it's a rule with unknown extensions (i.e., the rule
  819       # looks like '.foo.bar:' but '.foo' or '.bar' are not
  820       # declared in SUFFIXES and are not known language
  821       # extensions).  Automake will complete SUFFIXES from
  822       # @suffixes automatically (see handle_footer).
  823       || ($t =~ /$_SUFFIX_RULE_PATTERN/o && accept_extensions($1)))
  824     {
  825       ++$inference_rule_count;
  826       register_suffix_rule ($where, $1, $2);
  827     }
  828     }
  829 
  830   # POSIX allows multiple targets before the colon, but disallows
  831   # definitions of multiple inference rules.  It's also
  832   # disallowed to mix plain targets with inference rules.
  833   msg ('portability', $where,
  834        "inference rules can have only one target before the colon (POSIX)")
  835     if $inference_rule_count > 0 && $target_count > 1;
  836 
  837   return @conds;
  838 }
  839 
  840 =item C<depend ($target, @deps)>
  841 
  842 Adds C<@deps> to the dependencies of target C<$target>.  This should
  843 be used only with factored targets (those appearing in
  844 C<%dependees>).
  845 
  846 =cut
  847 
  848 sub depend ($@)
  849 {
  850   my ($category, @dependees) = @_;
  851   push (@{$dependencies{$category}}, @dependees);
  852 }
  853 
  854 =back
  855 
  856 =head1 SEE ALSO
  857 
  858 L<Automake::RuleDef>, L<Automake::Condition>,
  859 L<Automake::DisjConditions>, L<Automake::Location>.
  860 
  861 =cut
  862 
  863 1;