lib/Automake/Rule.pm

   1 # Copyright (C) 2003-2024 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   # Don't coalesce the several pattern rules from footer.am into a single one.
 699   return $cond if $target eq "%:" && $where->get =~ /\/am\/footer\.am$/;
 700
 701   if ($owner == RULE_USER)
 702     {
 703       # For user rules, just diagnose the ambiguity.
 704       msg 'syntax', $where, "$message ...", partial => 1;
 705       msg_cond_rule ('syntax', $ambig_cond, $target,
 706                      "... '$target' previously defined here");
 707       return ();
 708     }
 709
 710   # FIXME: for Automake rules, we can't diagnose ambiguities yet.
 711   # The point is that Automake doesn't propagate conditions
 712   # everywhere.  For instance &handle_PROGRAMS doesn't care if
 713   # bin_PROGRAMS was defined conditionally or not.
 714   # On the following input
 715   #   if COND1
 716   #   foo:
 717   #           ...
 718   #   else
 719   #   bin_PROGRAMS = foo
 720   #   endif
 721   # &handle_PROGRAMS will attempt to define a 'foo:' rule
 722   # in condition TRUE (which conflicts with COND1).  Fixing
 723   # this in &handle_PROGRAMS and siblings seems hard: you'd
 724   # have to explain &file_contents what to do with a
 725   # condition.  So for now we do our best *here*.  If 'foo:'
 726   # was already defined in condition COND1 and we want to define
 727   # it in condition TRUE, then define it only in condition !COND1.
 728   # (See cond14.sh and cond15.sh for some test cases.)
 729   @conds = $rule->not_always_defined_in_cond ($cond)->conds;
 730
 731   # No conditions left to define the rule.
 732   # Warn, because our workaround is meaningless in this case.
 733   if (scalar @conds == 0)
 734     {
 735       msg 'syntax', $where, "$message ...", partial => 1;
 736       msg_cond_rule ('syntax', $ambig_cond, $target,
 737                      "... '$target' previously defined here");
 738       return ();
 739     }
 740   return @conds;
 741 }
 742
 743 =item C<@conds = define ($rulename, $source, $owner, $cond, $where)>
 744
 745 Define a new rule.  C<$rulename> is the list of targets.  C<$source>
 746 is the filename the rule comes from.  C<$owner> is the owner of the
 747 rule (C<RULE_AUTOMAKE> or C<RULE_USER>).  C<$cond> is the
 748 C<Automake::Condition> under which the rule is defined.  C<$where> is
 749 the C<Automake::Location> where the rule is defined.
 750
 751 Returns a (possibly empty) list of C<Automake::Condition>s where the
 752 rule's definition should be output.
 753
 754 =cut
 755
 756 sub define ($$$$$)
 757 {
 758   my ($target, $source, $owner, $cond, $where) = @_;
 759
 760   prog_error "$where is not a reference"
 761     unless ref $where;
 762   prog_error "$cond is not a reference"
 763     unless ref $cond;
 764
 765   # Don't even think about defining a rule in condition FALSE.
 766   return () if $cond == FALSE;
 767
 768   my $tdef = _rule_defn_with_exeext_awareness ($target, $cond, $where);
 769
 770   # The pattern rules in footer.am look like duplicates, but really aren't.
 771   if ($source !~ /\/am\/footer\.am$/)
 772     {
 773       # A GNU make-style pattern rule has a single "%" in the target name.
 774       msg ('portability', $where,
 775            "'%'-style pattern rules are a GNU make extension")
 776         if $target =~ /^[^%]*%[^%]*$/;
 777
 778       # See whether this is a duplicated target declaration.
 779       if ($tdef)
 780         {
 781           # Diagnose invalid target redefinitions, if any.  Note that some
 782           # target redefinitions are valid (e.g., for multiple-targets
 783           # pattern rules).
 784           _maybe_warn_about_duplicated_target ($target, $tdef, $source,
 785                                                $owner, $cond, $where);
 786           # Return so we don't redefine the rule in our tables, don't check
 787           # for ambiguous condition, etc.  The rule will be output anyway
 788           # because '&read_am_file' ignores the return code.
 789           return ();
 790         }
 791     }
 792
 793   my $rule = _crule $target;
 794
 795   # Conditions for which the rule should be defined.  Due to some
 796   # complications in the automake internals, this aspect is not as
 797   # obvious as it might be, and in come cases this list must contain
 798   # other entries in addition to '$cond'.  See the comments in
 799   # '_conditionals_for_rule' for a rationale.
 800   my @conds = _conditionals_for_rule ($rule, $owner, $cond, $where);
 801
 802   # Stop if we had ambiguous conditional definitions.
 803   return unless @conds;
 804
 805   # Finally define this rule.
 806   for my $c (@conds)
 807     {
 808       my $def = new Automake::RuleDef ($target, '', $where->clone,
 809                                        $owner, $source);
 810       $rule->set ($c, $def);
 811     }
 812
 813   # We honor inference rules with multiple targets because many
 814   # makes support this and people use it.  However this is disallowed
 815   # by POSIX.  We'll print a warning later.
 816   my $target_count = 0;
 817   my $inference_rule_count = 0;
 818
 819   for my $t (split (' ', $target))
 820     {
 821       ++$target_count;
 822       # Check if the rule is a suffix rule: either it's a rule for
 823       # two known extensions...
 824       if ($t =~ /^($KNOWN_EXTENSIONS_PATTERN)($KNOWN_EXTENSIONS_PATTERN)$/
 825           # ...or it's a rule with unknown extensions (i.e., the rule
 826           # looks like '.foo.bar:' but '.foo' or '.bar' are not
 827           # declared in SUFFIXES and are not known language
 828           # extensions).  Automake will complete SUFFIXES from
 829           # @suffixes automatically (see handle_footer).
 830           || ($t =~ /$_SUFFIX_RULE_PATTERN/o && accept_extensions($1)))
 831         {
 832           ++$inference_rule_count;
 833           register_suffix_rule ($where, $1, $2);
 834         }
 835     }
 836
 837   # POSIX allows multiple targets before the colon, but disallows
 838   # definitions of multiple inference rules.  It's also
 839   # disallowed to mix plain targets with inference rules.
 840   msg ('portability', $where,
 841        "inference rules can have only one target before the colon (POSIX)")
 842     if $inference_rule_count > 0 && $target_count > 1;
 843
 844   return @conds;
 845 }
 846
 847 =item C<depend ($target, @deps)>
 848
 849 Adds C<@deps> to the dependencies of target C<$target>.  This should
 850 be used only with factored targets (those appearing in
 851 C<%dependees>).
 852
 853 =cut
 854
 855 sub depend ($@)
 856 {
 857   my ($category, @dependees) = @_;
 858   push (@{$dependencies{$category}}, @dependees);
 859 }
 860
 861 =back
 862
 863 =head1 SEE ALSO
 864
 865 L<Automake::RuleDef>, L<Automake::Condition>,
 866 L<Automake::DisjConditions>, L<Automake::Location>.
 867
 868 =cut
 869
 870 1;