lib/Automake/Rule.pm

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