"Fossies" - the Fresh Open Source Software Archive

Member "automake-1.16.3/lib/Automake/Variable.pm" (19 Nov 2020, 45957 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 "Variable.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::Variable;
   17 
   18 use 5.006;
   19 use strict;
   20 use warnings FATAL => 'all';
   21 
   22 use Carp;
   23 use Exporter;
   24 
   25 use Automake::Channels;
   26 use Automake::ChannelDefs;
   27 use Automake::Configure_ac;
   28 use Automake::Item;
   29 use Automake::VarDef;
   30 use Automake::Condition qw (TRUE FALSE);
   31 use Automake::DisjConditions;
   32 use Automake::General 'uniq';
   33 use Automake::Wrap 'makefile_wrap';
   34 
   35 our @ISA = qw (Automake::Item Exporter);
   36 our @EXPORT = qw (err_var msg_var msg_cond_var reject_var
   37           var rvar vardef rvardef
   38           variables
   39           scan_variable_expansions check_variable_expansions
   40           variable_delete
   41           variables_dump
   42           set_seen
   43           require_variables
   44           variable_value
   45           output_variables
   46           transform_variable_recursively);
   47 
   48 =head1 NAME
   49 
   50 Automake::Variable - support for variable definitions
   51 
   52 =head1 SYNOPSIS
   53 
   54   use Automake::Variable;
   55   use Automake::VarDef;
   56 
   57   # Defining a variable.
   58   Automake::Variable::define($varname, $owner, $type,
   59                              $cond, $value, $comment,
   60                              $where, $pretty)
   61 
   62   # Looking up a variable.
   63   my $var = var $varname;
   64   if ($var)
   65     {
   66       ...
   67     }
   68 
   69   # Looking up a variable that is assumed to exist.
   70   my $var = rvar $varname;
   71 
   72   # The list of conditions where $var has been defined.
   73   # ($var->conditions is an Automake::DisjConditions,
   74   # $var->conditions->conds is a list of Automake::Condition.)
   75   my @conds = $var->conditions->conds
   76 
   77   # Access to the definition in Condition $cond.
   78   # $def is an Automake::VarDef.
   79   my $def = $var->def ($cond);
   80   if ($def)
   81     {
   82       ...
   83     }
   84 
   85   # When the conditional definition is assumed to exist, use
   86   my $def = $var->rdef ($cond);
   87 
   88 
   89 =head1 DESCRIPTION
   90 
   91 This package provides support for Makefile variable definitions.
   92 
   93 An C<Automake::Variable> is a variable name associated to possibly
   94 many conditional definitions.  These definitions are instances
   95 of C<Automake::VarDef>.
   96 
   97 Therefore obtaining the value of a variable under a given
   98 condition involves two lookups.  One to look up the variable,
   99 and one to look up the conditional definition:
  100 
  101   my $var = var $name;
  102   if ($var)
  103     {
  104       my $def = $var->def ($cond);
  105       if ($def)
  106         {
  107           return $def->value;
  108         }
  109       ...
  110     }
  111   ...
  112 
  113 When it is known that the variable and the definition
  114 being looked up exist, the above can be simplified to
  115 
  116   return var ($name)->def ($cond)->value; # Do not write this.
  117 
  118 but is better written
  119 
  120   return rvar ($name)->rdef ($cond)->value;
  121 
  122 or even
  123 
  124   return rvardef ($name, $cond)->value;
  125 
  126 The I<r> variants of the C<var>, C<def>, and C<vardef> methods add an
  127 extra test to ensure that the lookup succeeded, and will diagnose
  128 failures as internal errors (with a message which is much more
  129 informative than Perl's warning about calling a method on a
  130 non-object).
  131 
  132 =cut
  133 
  134 my $_VARIABLE_CHARACTERS = '[.A-Za-z0-9_@]+';
  135 my $_VARIABLE_PATTERN = '^' . $_VARIABLE_CHARACTERS . "\$";
  136 my $_VARIABLE_RECURSIVE_PATTERN =
  137     '^([.A-Za-z0-9_@]|\$[({]' . $_VARIABLE_CHARACTERS . '[})]?)+' . "\$";
  138 
  139 # The order in which variables should be output.  (May contain
  140 # duplicates -- only the first occurrence matters.)
  141 my @_var_order;
  142 
  143 # This keeps track of all variables defined by &_gen_varname.
  144 # $_gen_varname{$base} is a hash for all variables defined with
  145 # prefix '$base'.  Values stored in this hash are the variable names.
  146 # Keys have the form "(COND1)VAL1(COND2)VAL2..." where VAL1 and VAL2
  147 # are the values of the variable for condition COND1 and COND2.
  148 my %_gen_varname = ();
  149 # $_gen_varname_n{$base} is the number of variables generated by
  150 # _gen_varname() for $base.  This is not the same as keys
  151 # %{$_gen_varname{$base}} because %_gen_varname may also contain
  152 # variables not generated by _gen_varname.
  153 my %_gen_varname_n = ();
  154 
  155 # Declare the macros that define known variables, so we can
  156 # hint the user if she try to use one of these variables.
  157 
  158 # Macros accessible via aclocal.
  159 my %_am_macro_for_var =
  160   (
  161    CCAS => 'AM_PROG_AS',
  162    CCASFLAGS => 'AM_PROG_AS',
  163    EMACS => 'AM_PATH_LISPDIR',
  164    GCJ => 'AM_PROG_GCJ',
  165    LEX => 'AM_PROG_LEX',
  166    LIBTOOL => 'LT_INIT',
  167    lispdir => 'AM_PATH_LISPDIR',
  168    pkgpyexecdir => 'AM_PATH_PYTHON',
  169    pkgpythondir => 'AM_PATH_PYTHON',
  170    pyexecdir => 'AM_PATH_PYTHON',
  171    PYTHON => 'AM_PATH_PYTHON',
  172    pythondir => 'AM_PATH_PYTHON',
  173    );
  174 
  175 # Macros shipped with Autoconf.
  176 my %_ac_macro_for_var =
  177   (
  178    ALLOCA => 'AC_FUNC_ALLOCA',
  179    CC => 'AC_PROG_CC',
  180    CFLAGS => 'AC_PROG_CC',
  181    CXX => 'AC_PROG_CXX',
  182    CXXFLAGS => 'AC_PROG_CXX',
  183    F77 => 'AC_PROG_F77',
  184    FFLAGS => 'AC_PROG_F77',
  185    FC => 'AC_PROG_FC',
  186    FCFLAGS => 'AC_PROG_FC',
  187    OBJC => 'AC_PROG_OBJC',
  188    OBJCFLAGS => 'AC_PROG_OBJC',
  189    OBJCXX => 'AC_PROG_OBJCXX',
  190    OBJCXXFLAGS => 'AC_PROG_OBJCXX',
  191    RANLIB => 'AC_PROG_RANLIB',
  192    UPC => 'AM_PROG_UPC',
  193    UPCFLAGS => 'AM_PROG_UPC',
  194    YACC => 'AC_PROG_YACC',
  195    );
  196 
  197 # The name of the configure.ac file.
  198 my $configure_ac;
  199 
  200 # Variables that can be overridden without complaint from -Woverride
  201 my %_silent_variable_override =
  202   (AM_DISTCHECK_DVI_TARGET => 1,
  203    AM_MAKEINFOHTMLFLAGS => 1,
  204    AR => 1,
  205    ARFLAGS => 1,
  206    DEJATOOL => 1,
  207    JAVAC => 1,
  208    JAVAROOT => 1);
  209 
  210 # Count of helper variables used to implement conditional '+='.
  211 my $_appendvar;
  212 
  213 # Each call to C<Automake::Variable::traverse_recursively> gets an
  214 # unique label. This is used to detect recursively defined variables.
  215 my $_traversal = 0;
  216 
  217 
  218 =head2 Error reporting functions
  219 
  220 In these functions, C<$var> can be either a variable name, or
  221 an instance of C<Automake::Variable>.
  222 
  223 =over 4
  224 
  225 =item C<err_var ($var, $message, [%options])>
  226 
  227 Uncategorized errors about variables.
  228 
  229 =cut
  230 
  231 sub err_var ($$;%)
  232 {
  233   msg_var ('error', @_);
  234 }
  235 
  236 =item C<msg_cond_var ($channel, $cond, $var, $message, [%options])>
  237 
  238 Messages about conditional variable.
  239 
  240 =cut
  241 
  242 sub msg_cond_var ($$$$;%)
  243 {
  244   my ($channel, $cond, $var, $msg, %opts) = @_;
  245   my $v = ref ($var) ? $var : rvar ($var);
  246   msg $channel, $v->rdef ($cond)->location, $msg, %opts;
  247 }
  248 
  249 =item C<msg_var ($channel, $var, $message, [%options])>
  250 
  251 Messages about variables.
  252 
  253 =cut
  254 
  255 sub msg_var ($$$;%)
  256 {
  257   my ($channel, $var, $msg, %opts) = @_;
  258   my $v = ref ($var) ? $var : rvar ($var);
  259   # Don't know which condition is concerned.  Pick any.
  260   my $cond = $v->conditions->one_cond;
  261   msg_cond_var $channel, $cond, $v, $msg, %opts;
  262 }
  263 
  264 =item C<$bool = reject_var ($varname, $error_msg)>
  265 
  266 Bail out with C<$error_msg> if a variable with name C<$varname> has
  267 been defined.
  268 
  269 Return true iff C<$varname> is defined.
  270 
  271 =cut
  272 
  273 sub reject_var ($$)
  274 {
  275   my ($var, $msg) = @_;
  276   my $v = var ($var);
  277   if ($v)
  278     {
  279       err_var $v, $msg;
  280       return 1;
  281     }
  282   return 0;
  283 }
  284 
  285 =back
  286 
  287 =head2 Administrative functions
  288 
  289 =over 4
  290 
  291 =item C<Automake::Variable::hook ($varname, $fun)>
  292 
  293 Declare a function to be called whenever a variable
  294 named C<$varname> is defined or redefined.
  295 
  296 C<$fun> should take two arguments: C<$type> and C<$value>.
  297 When type is C<''> or <':'>, C<$value> is the value being
  298 assigned to C<$varname>.  When C<$type> is C<'+'>, C<$value>
  299 is the value being appended to  C<$varname>.
  300 
  301 =cut
  302 
  303 our %_hooks;
  304 sub hook ($$)
  305 {
  306   my ($var, $fun) = @_;
  307   $_hooks{$var} = $fun;
  308 }
  309 
  310 =item C<variables ([$suffix])>
  311 
  312 Returns the list of all L<Automake::Variable> instances.  (I.e., all
  313 variables defined so far.)  If C<$suffix> is supplied, return only
  314 the L<Automake::Variable> instances that ends with C<_$suffix>.
  315 
  316 =cut
  317 
  318 our (%_variable_dict, %_primary_dict);
  319 sub variables (;$)
  320 {
  321   my ($suffix) = @_;
  322   my @vars = ();
  323   if ($suffix)
  324     {
  325       if (exists $_primary_dict{$suffix})
  326     {
  327       @vars = values %{$_primary_dict{$suffix}};
  328     }
  329     }
  330   else
  331     {
  332       @vars = values %_variable_dict;
  333     }
  334   # The behaviour of the 'sort' built-in is undefined in scalar
  335   # context, hence we need an ad-hoc handling for such context.
  336   return wantarray ? sort { $a->name cmp $b->name } @vars : scalar @vars;
  337 }
  338 
  339 =item C<Automake::Variable::reset>
  340 
  341 The I<forget all> function.  Clears all know variables and reset some
  342 other internal data.
  343 
  344 =cut
  345 
  346 sub reset ()
  347 {
  348   %_variable_dict = ();
  349   %_primary_dict = ();
  350   $_appendvar = 0;
  351   @_var_order = ();
  352   %_gen_varname = ();
  353   %_gen_varname_n = ();
  354   $_traversal = 0;
  355 }
  356 
  357 =item C<var ($varname)>
  358 
  359 Return the C<Automake::Variable> object for the variable
  360 named C<$varname> if defined.  Return 0 otherwise.
  361 
  362 =cut
  363 
  364 sub var ($)
  365 {
  366   my ($name) = @_;
  367   return $_variable_dict{$name} if exists $_variable_dict{$name};
  368   return 0;
  369 }
  370 
  371 =item C<vardef ($varname, $cond)>
  372 
  373 Return the C<Automake::VarDef> object for the variable named
  374 C<$varname> if defined in condition C<$cond>.  Return false
  375 if the condition or the variable does not exist.
  376 
  377 =cut
  378 
  379 sub vardef ($$)
  380 {
  381   my ($name, $cond) = @_;
  382   my $var = var $name;
  383   return $var && $var->def ($cond);
  384 }
  385 
  386 # Create the variable if it does not exist.
  387 # This is used only by other functions in this package.
  388 sub _cvar ($)
  389 {
  390   my ($name) = @_;
  391   my $v = var $name;
  392   return $v if $v;
  393   return _new Automake::Variable $name;
  394 }
  395 
  396 =item C<rvar ($varname)>
  397 
  398 Return the C<Automake::Variable> object for the variable named
  399 C<$varname>.  Abort with an internal error if the variable was not
  400 defined.
  401 
  402 The I<r> in front of C<var> stands for I<required>.  One
  403 should call C<rvar> to assert the variable's existence.
  404 
  405 =cut
  406 
  407 sub rvar ($)
  408 {
  409   my ($name) = @_;
  410   my $v = var $name;
  411   prog_error ("undefined variable $name\n" . &variables_dump)
  412     unless $v;
  413   return $v;
  414 }
  415 
  416 =item C<rvardef ($varname, $cond)>
  417 
  418 Return the C<Automake::VarDef> object for the variable named
  419 C<$varname> if defined in condition C<$cond>.  Abort with an internal
  420 error if the condition or the variable does not exist.
  421 
  422 =cut
  423 
  424 sub rvardef ($$)
  425 {
  426   my ($name, $cond) = @_;
  427   return rvar ($name)->rdef ($cond);
  428 }
  429 
  430 =back
  431 
  432 =head2 Methods
  433 
  434 C<Automake::Variable> is a subclass of C<Automake::Item>.  See
  435 that package for inherited methods.
  436 
  437 Here are the methods specific to the C<Automake::Variable> instances.
  438 Use the C<define> function, described latter, to create such objects.
  439 
  440 =over 4
  441 
  442 =cut
  443 
  444 # Create Automake::Variable objects.  This is used
  445 # only in this file.  Other users should use
  446 # the "define" function.
  447 sub _new ($$)
  448 {
  449   my ($class, $name) = @_;
  450   my $self = Automake::Item::new ($class, $name);
  451   $self->{'scanned'} = 0;
  452   $self->{'last-append'} = []; # helper variable for last conditional append.
  453   $_variable_dict{$name} = $self;
  454   if ($name =~ /_([[:alnum:]]+)$/)
  455     {
  456       $_primary_dict{$1}{$name} = $self;
  457     }
  458   return $self;
  459 }
  460 
  461 # _check_ambiguous_condition ($SELF, $COND, $WHERE)
  462 # -------------------------------------------------
  463 # Check for an ambiguous conditional.  This is called when a variable
  464 # is being defined conditionally.  If we already know about a
  465 # definition that is true under the same conditions, then we have an
  466 # ambiguity.
  467 sub _check_ambiguous_condition ($$$)
  468 {
  469   my ($self, $cond, $where) = @_;
  470   my $var = $self->name;
  471   my ($message, $ambig_cond) = $self->conditions->ambiguous_p ($var, $cond);
  472 
  473   # We allow silent variables to be overridden silently,
  474   # by either silent or non-silent variables.
  475   my $def = $self->def ($ambig_cond);
  476   if ($message && $def->pretty != VAR_SILENT)
  477     {
  478       msg 'syntax', $where, "$message ...", partial => 1;
  479       msg_var ('syntax', $var, "... '$var' previously defined here");
  480       verb ($self->dump);
  481     }
  482 }
  483 
  484 =item C<$bool = $var-E<gt>check_defined_unconditionally ([$parent, $parent_cond])>
  485 
  486 Warn if the variable is conditionally defined.  C<$parent> is the name
  487 of the parent variable, and C<$parent_cond> the condition of the parent
  488 definition.  These two variables are used to display diagnostics.
  489 
  490 =cut
  491 
  492 sub check_defined_unconditionally ($;$$)
  493 {
  494   my ($self, $parent, $parent_cond) = @_;
  495 
  496   if (!$self->conditions->true)
  497     {
  498       if ($parent)
  499     {
  500       msg_cond_var ('unsupported', $parent_cond, $parent,
  501             "automake does not support conditional definition of "
  502             . $self->name . " in $parent");
  503     }
  504       else
  505     {
  506       msg_var ('unsupported', $self,
  507            "automake does not support " . $self->name
  508            . " being defined conditionally");
  509     }
  510     }
  511 }
  512 
  513 =item C<$str = $var-E<gt>output ([@conds])>
  514 
  515 Format all the definitions of C<$var> if C<@cond> is not specified,
  516 else only that corresponding to C<@cond>.
  517 
  518 =cut
  519 
  520 sub output ($@)
  521 {
  522   my ($self, @conds) = @_;
  523 
  524   @conds = $self->conditions->conds
  525     unless @conds;
  526 
  527   my $res = '';
  528   my $name = $self->name;
  529 
  530   foreach my $cond (@conds)
  531     {
  532       my $def = $self->def ($cond);
  533       prog_error ("unknown condition '" . $cond->human . "' for '"
  534           . $self->name . "'")
  535     unless $def;
  536 
  537       next
  538     if $def->pretty == VAR_SILENT;
  539 
  540       $res .= $def->comment;
  541 
  542       my $val = $def->raw_value;
  543       my $equals = $def->type eq ':' ? ':=' : '=';
  544       my $str = $cond->subst_string;
  545 
  546 
  547       if ($def->pretty == VAR_ASIS)
  548     {
  549       my $output_var = "$name $equals $val";
  550       $output_var =~ s/^/$str/meg;
  551       $res .= "$output_var\n";
  552     }
  553       elsif ($def->pretty == VAR_PRETTY)
  554     {
  555       # Suppress escaped new lines.  &makefile_wrap will
  556       # add them back, maybe at other places.
  557       $val =~ s/\\$//mg;
  558       my $wrap = makefile_wrap ("$str$name $equals", "$str\t",
  559                     split (' ', $val));
  560 
  561       # If the last line of the definition is made only of
  562       # @substitutions@, append an empty variable to make sure it
  563       # cannot be substituted as a blank line (that would confuse
  564       # HP-UX Make).
  565       $wrap = makefile_wrap ("$str$name $equals", "$str\t",
  566                  split (' ', $val), '$(am__empty)')
  567         if $wrap =~ /\n(\s*@\w+@)+\s*$/;
  568 
  569       $res .= $wrap;
  570     }
  571       else # ($def->pretty == VAR_SORTED)
  572     {
  573       # Suppress escaped new lines.  &makefile_wrap will
  574       # add them back, maybe at other places.
  575       $val =~ s/\\$//mg;
  576       $res .= makefile_wrap ("$str$name $equals", "$str\t",
  577                  sort (split (' ' , $val)));
  578     }
  579     }
  580   return $res;
  581 }
  582 
  583 =item C<@values = $var-E<gt>value_as_list ($cond, [$parent, $parent_cond])>
  584 
  585 Get the value of C<$var> as a list, given a specified condition,
  586 without recursing through any subvariables.
  587 
  588 C<$cond> is the condition of interest.  C<$var> does not need
  589 to be defined for condition C<$cond> exactly, but it needs
  590 to be defined for at most one condition implied by C<$cond>.
  591 
  592 C<$parent> and C<$parent_cond> designate the name and the condition
  593 of the parent variable, i.e., the variable in which C<$var> is
  594 being expanded.  These are used in diagnostics.
  595 
  596 For example, if C<A> is defined as "C<foo $(B) bar>" in condition
  597 C<TRUE>, calling C<rvar ('A')->value_as_list (TRUE)> will return
  598 C<("foo", "$(B)", "bar")>.
  599 
  600 =cut
  601 
  602 sub value_as_list ($$;$$)
  603 {
  604   my ($self, $cond, $parent, $parent_cond) = @_;
  605   my @result;
  606 
  607   # Get value for given condition
  608   my $onceflag;
  609   foreach my $vcond ($self->conditions->conds)
  610     {
  611       if ($vcond->true_when ($cond))
  612     {
  613       # If there is more than one definitions of $var matching
  614       # $cond then we are in trouble: tell the user we need a
  615       # paddle.  Continue by merging results from all conditions,
  616       # although it doesn't make much sense.
  617       $self->check_defined_unconditionally ($parent, $parent_cond)
  618         if $onceflag;
  619       $onceflag = 1;
  620 
  621       my $val = $self->rdef ($vcond)->value;
  622       push @result, split (' ', $val);
  623     }
  624     }
  625   return @result;
  626 }
  627 
  628 =item C<@values = $var-E<gt>value_as_list_recursive ([%options])>
  629 
  630 Return the contents of C<$var> as a list, split on whitespace.  This
  631 will recursively follow C<$(...)> and C<${...}> inclusions.  It
  632 preserves C<@...@> substitutions.
  633 
  634 C<%options> is a list of option for C<Variable::traverse_recursively>
  635 (see this method).  The most useful is C<cond_filter>:
  636 
  637   $var->value_as_list_recursive (cond_filter => $cond)
  638 
  639 will return the contents of C<$var> and any subvariable in all
  640 conditions implied by C<$cond>.
  641 
  642 C<%options> can also carry options specific to C<value_as_list_recursive>.
  643 Presently, the only such option is C<location =E<gt> 1> which instructs
  644 C<value_as_list_recursive> to return a list of C<[$location, @values]> pairs.
  645 
  646 =cut
  647 
  648 sub value_as_list_recursive ($;%)
  649 {
  650   my ($var, %options) = @_;
  651 
  652   return $var->traverse_recursively
  653     (# Construct [$location, $value] pairs if requested.
  654      sub {
  655        my ($var, $val, $cond, $full_cond) = @_;
  656        return [$var->rdef ($cond)->location, $val] if $options{'location'};
  657        return $val;
  658      },
  659      # Collect results.
  660      sub {
  661        my ($var, $parent_cond, @allresults) = @_;
  662        return map { my ($cond, @vals) = @$_; @vals } @allresults;
  663      },
  664      %options);
  665 }
  666 
  667 
  668 =item C<$bool = $var-E<gt>has_conditional_contents>
  669 
  670 Return 1 if C<$var> or one of its subvariable was conditionally
  671 defined.  Return 0 otherwise.
  672 
  673 =cut
  674 
  675 sub has_conditional_contents ($)
  676 {
  677   my ($self) = @_;
  678 
  679   # Traverse the variable recursively until we
  680   # find a variable defined conditionally.
  681   # Use 'die' to abort the traversal, and pass it '$full_cond'
  682   # to we can find easily whether the 'eval' block aborted
  683   # because we found a condition, or for some other error.
  684   eval
  685     {
  686       $self->traverse_recursively
  687     (sub
  688      {
  689        my ($subvar, $val, $cond, $full_cond) = @_;
  690        die $full_cond if ! $full_cond->true;
  691        return ();
  692      },
  693      sub { return (); });
  694     };
  695   if ($@)
  696     {
  697       return 1 if ref ($@) && $@->isa ("Automake::Condition");
  698       # Propagate other errors.
  699       die;
  700     }
  701   return 0;
  702 }
  703 
  704 
  705 =item C<$string = $var-E<gt>dump>
  706 
  707 Return a string describing all we know about C<$var>.
  708 For debugging.
  709 
  710 =cut
  711 
  712 sub dump ($)
  713 {
  714   my ($self) = @_;
  715 
  716   my $text = $self->name . ": \n  {\n";
  717   foreach my $vcond ($self->conditions->conds)
  718     {
  719       $text .= "    " . $vcond->human . " => " . $self->rdef ($vcond)->dump;
  720     }
  721   $text .= "  }\n";
  722   return $text;
  723 }
  724 
  725 
  726 =back
  727 
  728 =head2 Utility functions
  729 
  730 =over 4
  731 
  732 =item C<@list = scan_variable_expansions ($text)>
  733 
  734 Return the list of variable names expanded in C<$text>.  Note that
  735 unlike some other functions, C<$text> is not split on spaces before we
  736 check for subvariables.
  737 
  738 =cut
  739 
  740 sub scan_variable_expansions ($)
  741 {
  742   my ($text) = @_;
  743   my @result = ();
  744 
  745   # Strip comments.
  746   $text =~ s/#.*$//;
  747 
  748   # Record each use of ${stuff} or $(stuff) that does not follow a $.
  749   while ($text =~ /(?<!\$)\$(?:\{([^\}]*)\}|\(([^\)]*)\))/g)
  750     {
  751       my $var = $1 || $2;
  752       # The occurrence may look like $(string1[:subst1=[subst2]]) but
  753       # we want only 'string1'.
  754       $var =~ s/:[^:=]*=[^=]*$//;
  755       push @result, $var;
  756     }
  757 
  758   return @result;
  759 }
  760 
  761 =item C<check_variable_expansions ($text, $where)>
  762 
  763 Check variable expansions in C<$text> and warn about any name that
  764 does not conform to POSIX.  C<$where> is the location of C<$text>
  765 for the error message.
  766 
  767 =cut
  768 
  769 sub check_variable_expansions ($$)
  770 {
  771   my ($text, $where) = @_;
  772   # Catch expansion of variables whose name does not conform to POSIX.
  773   foreach my $var (scan_variable_expansions ($text))
  774     {
  775       if ($var !~ /$_VARIABLE_PATTERN/o)
  776     {
  777       # If the variable name contains a space, it's likely
  778       # to be a GNU make extension (such as $(addsuffix ...)).
  779       # Mention this in the diagnostic.
  780       my $gnuext = "";
  781       $gnuext = "\n(probably a GNU make extension)" if $var =~ / /;
  782       # Accept recursive variable expansions if so desired
  783       # (we hope they are rather portable in practice).
  784       if ($var =~ /$_VARIABLE_RECURSIVE_PATTERN/o)
  785         {
  786           msg ('portability-recursive', $where,
  787            "$var: non-POSIX recursive variable expansion$gnuext");
  788         }
  789       else
  790         {
  791           msg ('portability', $where, "$var: non-POSIX variable name$gnuext");
  792         }
  793     }
  794     }
  795 }
  796 
  797 
  798 
  799 =item C<Automake::Variable::define($varname, $owner, $type, $cond, $value, $comment, $where, $pretty)>
  800 
  801 Define or append to a new variable.
  802 
  803 C<$varname>: the name of the variable being defined.
  804 
  805 C<$owner>: owner of the variable (one of C<VAR_MAKEFILE>,
  806 C<VAR_CONFIGURE>, or C<VAR_AUTOMAKE>, defined by L<Automake::VarDef>).
  807 Variables can be overridden, provided the new owner is not weaker
  808 (C<VAR_AUTOMAKE> < C<VAR_CONFIGURE> < C<VAR_MAKEFILE>).
  809 
  810 C<$type>: the type of the assignment (C<''> for C<FOO = bar>,
  811 C<':'> for C<FOO := bar>, and C<'+'> for C<'FOO += bar'>).
  812 
  813 C<$cond>: the C<Condition> in which C<$var> is being defined.
  814 
  815 C<$value>: the value assigned to C<$var> in condition C<$cond>.
  816 
  817 C<$comment>: any comment (C<'# bla.'>) associated with the assignment.
  818 Comments from C<+=> assignments stack with comments from the last C<=>
  819 assignment.
  820 
  821 C<$where>: the C<Location> of the assignment.
  822 
  823 C<$pretty>: whether C<$value> should be pretty printed (one of
  824 C<VAR_ASIS>, C<VAR_PRETTY>, C<VAR_SILENT>, or C<VAR_SORTED>, defined
  825 by by L<Automake::VarDef>).  C<$pretty> applies only to real
  826 assignments.  I.e., it does not apply to a C<+=> assignment (except
  827 when part of it is being done as a conditional C<=> assignment).
  828 
  829 This function will all run any hook registered with the C<hook>
  830 function.
  831 
  832 =cut
  833 
  834 sub define ($$$$$$$$)
  835 {
  836   my ($var, $owner, $type, $cond, $value, $comment, $where, $pretty) = @_;
  837 
  838   prog_error "$cond is not a reference"
  839     unless ref $cond;
  840 
  841   prog_error "$where is not a reference"
  842     unless ref $where;
  843 
  844   prog_error "pretty argument missing"
  845     unless defined $pretty && ($pretty == VAR_ASIS
  846                    || $pretty == VAR_PRETTY
  847                    || $pretty == VAR_SILENT
  848                    || $pretty == VAR_SORTED);
  849 
  850   error $where, "bad characters in variable name '$var'"
  851     if $var !~ /$_VARIABLE_PATTERN/o;
  852 
  853   # ':='-style assignments are not acknowledged by POSIX.  Moreover it
  854   # has multiple meanings.  In GNU make or BSD make it means "assign
  855   # with immediate expansion", while in OSF make it is used for
  856   # conditional assignments.
  857   msg ('portability', $where, "':='-style assignments are not portable")
  858     if $type eq ':';
  859 
  860   check_variable_expansions ($value, $where);
  861 
  862   # If there's a comment, make sure it is \n-terminated.
  863   if ($comment)
  864     {
  865       chomp $comment;
  866       $comment .= "\n";
  867     }
  868   else
  869     {
  870       $comment = '';
  871     }
  872 
  873   my $self = _cvar $var;
  874 
  875   my $def = $self->def ($cond);
  876   my $new_var = $def ? 0 : 1;
  877 
  878   # Additional checks for Automake definitions.
  879   if ($owner == VAR_AUTOMAKE && ! $new_var)
  880     {
  881       # An Automake variable must be consistently defined with the same
  882       # sign by Automake.
  883       if ($def->type ne $type && $def->owner == VAR_AUTOMAKE)
  884     {
  885       error ($def->location,
  886          "Automake variable '$var' was set with '"
  887          . $def->type . "=' here ...", partial => 1);
  888       error ($where, "... and is now set with '$type=' here.");
  889       prog_error ("Automake variable assignments should be consistently\n"
  890               . "defined with the same sign");
  891     }
  892 
  893       # If Automake tries to override a value specified by the user,
  894       # just don't let it do.
  895       if ($def->owner != VAR_AUTOMAKE)
  896     {
  897       if (! exists $_silent_variable_override{$var})
  898         {
  899           my $condmsg = ($cond == TRUE
  900                  ? '' : (" in condition '" . $cond->human . "'"));
  901           msg_cond_var ('override', $cond, $var,
  902                 "user variable '$var' defined here$condmsg ...",
  903                 partial => 1);
  904           msg ('override', $where,
  905            "... overrides Automake variable '$var' defined here");
  906         }
  907       verb ("refusing to override the user definition of:\n"
  908         . $self->dump ."with '" . $cond->human . "' => '$value'");
  909       return;
  910     }
  911     }
  912 
  913   # Differentiate assignment types.
  914 
  915   # 1. append (+=) to a variable defined for current condition
  916   if ($type eq '+' && ! $new_var)
  917     {
  918       $def->append ($value, $comment);
  919       $self->{'last-append'} = [];
  920 
  921       # Only increase owners.  A VAR_CONFIGURE variable augmented in a
  922       # Makefile.am becomes a VAR_MAKEFILE variable.
  923       $def->set_owner ($owner, $where->clone)
  924     if $owner > $def->owner;
  925     }
  926   # 2. append (+=) to a variable defined for *another* condition
  927   elsif ($type eq '+' && ! $self->conditions->false)
  928     {
  929       # * Generally, $cond is not TRUE.  For instance:
  930       #     FOO = foo
  931       #     if COND
  932       #       FOO += bar
  933       #     endif
  934       #   In this case, we declare an helper variable conditionally,
  935       #   and append it to FOO:
  936       #     FOO = foo $(am__append_1)
  937       #     @COND_TRUE@am__append_1 = bar
  938       #   Of course if FOO is defined under several conditions, we add
  939       #   $(am__append_1) to each definitions.
  940       #
  941       # * If $cond is TRUE, we don't need the helper variable.  E.g., in
  942       #     if COND1
  943       #       FOO = foo1
  944       #     else
  945       #       FOO = foo2
  946       #     endif
  947       #     FOO += bar
  948       #   we can add bar directly to all definition of FOO, and output
  949       #     @COND_TRUE@FOO = foo1 bar
  950       #     @COND_FALSE@FOO = foo2 bar
  951 
  952       my $lastappend = [];
  953       # Do we need an helper variable?
  954       if ($cond != TRUE)
  955         {
  956       # Can we reuse the helper variable created for the previous
  957       # append?  (We cannot reuse older helper variables because
  958       # we must preserve the order of items appended to the
  959       # variable.)
  960       my $condstr = $cond->string;
  961       my $key = "$var:$condstr";
  962       my ($appendvar, $appendvarcond) = @{$self->{'last-append'}};
  963       if ($appendvar && $condstr eq $appendvarcond)
  964         {
  965           # Yes, let's simply append to it.
  966           $var = $appendvar;
  967           $owner = VAR_AUTOMAKE;
  968           $self = var ($var);
  969           $def = $self->rdef ($cond);
  970           $new_var = 0;
  971         }
  972       else
  973         {
  974           # No, create it.
  975           my $num = ++$_appendvar;
  976           my $hvar = "am__append_$num";
  977           $lastappend = [$hvar, $condstr];
  978           &define ($hvar, VAR_AUTOMAKE, '+',
  979                $cond, $value, $comment, $where, $pretty);
  980 
  981           # Now HVAR is to be added to VAR.
  982           $comment = '';
  983           $value = "\$($hvar)";
  984         }
  985     }
  986 
  987       # Add VALUE to all definitions of SELF.
  988       foreach my $vcond ($self->conditions->conds)
  989         {
  990       # We have a bit of error detection to do here.
  991       # This:
  992       #   if COND1
  993       #     X = Y
  994       #   endif
  995       #   X += Z
  996       # should be rejected because X is not defined for all conditions
  997       # where '+=' applies.
  998       my $undef_cond = $self->not_always_defined_in_cond ($cond);
  999       if (! $undef_cond->false)
 1000         {
 1001           error ($where,
 1002              "cannot apply '+=' because '$var' is not defined "
 1003              . "in\nthe following conditions:\n  "
 1004              . join ("\n  ", map { $_->human } $undef_cond->conds)
 1005              . "\neither define '$var' in these conditions,"
 1006              . " or use\n'+=' in the same conditions as"
 1007              . " the definitions.");
 1008         }
 1009       else
 1010         {
 1011           &define ($var, $owner, '+', $vcond, $value, $comment,
 1012                $where, $pretty);
 1013         }
 1014     }
 1015       $self->{'last-append'} = $lastappend;
 1016     }
 1017   # 3. first assignment (=, :=, or +=)
 1018   else
 1019     {
 1020       # There must be no previous value unless the user is redefining
 1021       # an Automake variable or an AC_SUBST variable for an existing
 1022       # condition.
 1023       _check_ambiguous_condition ($self, $cond, $where)
 1024     unless (!$new_var
 1025         && (($def->owner == VAR_AUTOMAKE && $owner != VAR_AUTOMAKE)
 1026             || $def->owner == VAR_CONFIGURE));
 1027 
 1028       # Never decrease an owner.
 1029       $owner = $def->owner
 1030     if ! $new_var && $owner < $def->owner;
 1031 
 1032       # Assignments to a macro set its location.  We don't adjust
 1033       # locations for '+='.  Ideally I suppose we would associate
 1034       # line numbers with random bits of text.
 1035       $def = new Automake::VarDef ($var, $value, $comment, $where->clone,
 1036                    $type, $owner, $pretty);
 1037       $self->set ($cond, $def);
 1038       push @_var_order, $var;
 1039     }
 1040 
 1041   # Call any defined hook.  This helps to update some internal state
 1042   # *while* parsing the file.  For instance the handling of SUFFIXES
 1043   # requires this (see var_SUFFIXES_trigger).
 1044   &{$_hooks{$var}}($type, $value) if exists $_hooks{$var};
 1045 }
 1046 
 1047 =item C<variable_delete ($varname, [@conds])>
 1048 
 1049 Forget about C<$varname> under the conditions C<@conds>, or completely
 1050 if C<@conds> is empty.
 1051 
 1052 =cut
 1053 
 1054 sub variable_delete ($@)
 1055 {
 1056   my ($var, @conds) = @_;
 1057 
 1058   if (!@conds)
 1059     {
 1060       delete $_variable_dict{$var};
 1061     }
 1062   else
 1063     {
 1064       for my $cond (@conds)
 1065     {
 1066       delete $_variable_dict{$var}{'defs'}{$cond};
 1067     }
 1068     }
 1069   if ($var =~ /_([[:alnum:]]+)$/)
 1070     {
 1071       delete $_primary_dict{$1}{$var};
 1072     }
 1073 }
 1074 
 1075 =item C<$str = variables_dump>
 1076 
 1077 Return a string describing all we know about all variables.
 1078 For debugging.
 1079 
 1080 =cut
 1081 
 1082 sub variables_dump ()
 1083 {
 1084   my $text = "all variables:\n{\n";
 1085   foreach my $var (variables())
 1086     {
 1087       $text .= $var->dump;
 1088     }
 1089   $text .= "}\n";
 1090   return $text;
 1091 }
 1092 
 1093 
 1094 =item C<$var = set_seen ($varname)>
 1095 
 1096 =item C<$var = $var-E<gt>set_seen>
 1097 
 1098 Mark all definitions of this variable as examined, if the variable
 1099 exists.  See L<Automake::VarDef::set_seen>.
 1100 
 1101 Return the C<Variable> object if the variable exists, or 0
 1102 otherwise (i.e., as the C<var> function).
 1103 
 1104 =cut
 1105 
 1106 sub set_seen ($)
 1107 {
 1108   my ($self) = @_;
 1109   $self = ref $self ? $self : var $self;
 1110 
 1111   return 0 unless $self;
 1112 
 1113   for my $c ($self->conditions->conds)
 1114     {
 1115       $self->rdef ($c)->set_seen;
 1116     }
 1117 
 1118   return $self;
 1119 }
 1120 
 1121 
 1122 =item C<$count = require_variables ($where, $reason, $cond, @variables)>
 1123 
 1124 Make sure that each supplied variable is defined in C<$cond>.
 1125 Otherwise, issue a warning showing C<$reason> (C<$reason> should be
 1126 the reason why these variables are required, for instance C<'option foo
 1127 used'>).  If we know which macro can define this variable, hint the
 1128 user.  Return the number of undefined variables.
 1129 
 1130 =cut
 1131 
 1132 sub require_variables ($$$@)
 1133 {
 1134   my ($where, $reason, $cond, @vars) = @_;
 1135   my $res = 0;
 1136   $reason .= ' but ' unless $reason eq '';
 1137 
 1138   $configure_ac = find_configure_ac
 1139     unless defined $configure_ac;
 1140 
 1141  VARIABLE:
 1142   foreach my $var (@vars)
 1143     {
 1144       # Nothing to do if the variable exists.
 1145       next VARIABLE
 1146     if vardef ($var, $cond);
 1147 
 1148       my $text = "$reason'$var' is undefined\n";
 1149       my $v = var $var;
 1150       if ($v)
 1151     {
 1152       my $undef_cond = $v->not_always_defined_in_cond ($cond);
 1153       next VARIABLE
 1154         if $undef_cond->false;
 1155       $text .= ("in the following conditions:\n  "
 1156             . join ("\n  ", map { $_->human } $undef_cond->conds)
 1157             . "\n");
 1158     }
 1159 
 1160       ++$res;
 1161 
 1162       if (exists $_am_macro_for_var{$var})
 1163     {
 1164       my $mac = $_am_macro_for_var{$var};
 1165       $text .= "  The usual way to define '$var' is to add "
 1166         . "'$mac'\n  to '$configure_ac' and run 'aclocal' and "
 1167         . "'autoconf' again.";
 1168       # aclocal will not warn about undefined macros unless it
 1169       # starts with AM_.
 1170       $text .= "\n  If '$mac' is in '$configure_ac', make sure\n"
 1171         . "  its definition is in aclocal's search path."
 1172         unless $mac =~ /^AM_/;
 1173     }
 1174       elsif (exists $_ac_macro_for_var{$var})
 1175     {
 1176       $text .= "  The usual way to define '$var' is to add "
 1177         . "'$_ac_macro_for_var{$var}'\n  to '$configure_ac' and "
 1178         . "run 'autoconf' again.";
 1179     }
 1180 
 1181       error $where, $text, uniq_scope => US_GLOBAL;
 1182     }
 1183   return $res;
 1184 }
 1185 
 1186 =item C<$count = $var->requires_variables ($reason, @variables)>
 1187 
 1188 Same as C<require_variables>, but a method of Automake::Variable.
 1189 C<@variables> should be defined in the same conditions as C<$var> is
 1190 defined.
 1191 
 1192 =cut
 1193 
 1194 sub requires_variables ($$@)
 1195 {
 1196   my ($var, $reason, @args) = @_;
 1197   my $res = 0;
 1198   for my $cond ($var->conditions->conds)
 1199     {
 1200       $res += require_variables ($var->rdef ($cond)->location, $reason,
 1201                  $cond, @args);
 1202     }
 1203   return $res;
 1204 }
 1205 
 1206 
 1207 =item C<variable_value ($var)>
 1208 
 1209 Get the C<TRUE> value of a variable, warn if the variable is
 1210 conditionally defined.  C<$var> can be either a variable name
 1211 or a C<Automake::Variable> instance (this allows calls such
 1212 as C<$var-E<gt>variable_value>).
 1213 
 1214 =cut
 1215 
 1216 sub variable_value ($)
 1217 {
 1218     my ($var) = @_;
 1219     my $v = ref ($var) ? $var : var ($var);
 1220     return () unless $v;
 1221     $v->check_defined_unconditionally;
 1222     my $d = $v->def (TRUE);
 1223     return $d ? $d->value : "";
 1224 }
 1225 
 1226 =item C<$str = output_variables>
 1227 
 1228 Format definitions for all variables.
 1229 
 1230 =cut
 1231 
 1232 sub output_variables ()
 1233 {
 1234   my $res = '';
 1235   # We output variables it in the same order in which they were
 1236   # defined (skipping duplicates).
 1237   my @vars = uniq @_var_order;
 1238 
 1239   # Output all the Automake variables.  If the user changed one,
 1240   # then it is now marked as VAR_CONFIGURE or VAR_MAKEFILE.
 1241   foreach my $var (@vars)
 1242     {
 1243       my $v = rvar $var;
 1244       foreach my $cond ($v->conditions->conds)
 1245     {
 1246       $res .= $v->output ($cond)
 1247         if $v->rdef ($cond)->owner == VAR_AUTOMAKE;
 1248     }
 1249     }
 1250 
 1251   # Now dump the user variables that were defined.
 1252   foreach my $var (@vars)
 1253     {
 1254       my $v = rvar $var;
 1255       foreach my $cond ($v->conditions->conds)
 1256     {
 1257       $res .= $v->output ($cond)
 1258         if $v->rdef ($cond)->owner != VAR_AUTOMAKE;
 1259     }
 1260     }
 1261   return $res;
 1262 }
 1263 
 1264 =item C<$var-E<gt>traverse_recursively (&fun_item, &fun_collect, [cond_filter =E<gt> $cond_filter], [inner_expand =E<gt> 1], [skip_ac_subst =E<gt> 1])>
 1265 
 1266 Split the value of the Automake::Variable C<$var> on space, and
 1267 traverse its components recursively.
 1268 
 1269 If C<$cond_filter> is an C<Automake::Condition>, process any
 1270 conditions which are true when C<$cond_filter> is true.  Otherwise,
 1271 process all conditions.
 1272 
 1273 We distinguish two kinds of items in the content of C<$var>.
 1274 Terms that look like C<$(foo)> or C<${foo}> are subvariables
 1275 and cause recursion.  Other terms are assumed to be filenames.
 1276 
 1277 Each time a filename is encountered, C<&fun_item> is called with the
 1278 following arguments:
 1279 
 1280   ($var,        -- the Automake::Variable we are currently
 1281                    traversing
 1282    $val,        -- the item (i.e., filename) to process
 1283    $cond,       -- the Condition for the $var definition we are
 1284                    examining (ignoring the recursion context)
 1285    $full_cond)  -- the full Condition, taking into account
 1286                    conditions inherited from parent variables
 1287                    during recursion
 1288 
 1289 If C<inner_expand> is set, variable references occurring in filename
 1290 (as in C<$(BASE).ext>) are expanded before the filename is passed to
 1291 C<&fun_item>.
 1292 
 1293 If C<skip_ac_subst> is set, Autoconf @substitutions@ will be skipped,
 1294 i.e., C<&fun_item> will never be called for them.
 1295 
 1296 C<&fun_item> may return a list of items, they will be passed to
 1297 C<&fun_store> later on.  Define C<&fun_item> or @<&fun_store> as
 1298 C<undef> when they serve no purpose.
 1299 
 1300 Once all items of a variable have been processed, the result (of the
 1301 calls to C<&fun_items>, or of recursive traversals of subvariables)
 1302 are passed to C<&fun_collect>.  C<&fun_collect> receives three
 1303 arguments:
 1304 
 1305   ($var,         -- the variable being traversed
 1306    $parent_cond, -- the Condition inherited from parent
 1307                     variables during recursion
 1308    @condlist)    -- a list of [$cond, @results] pairs
 1309                     where each $cond appear only once, and @result
 1310                     are all the results for this condition.
 1311 
 1312 Typically you should do C<$cond->merge ($parent_cond)> to recompute
 1313 the C<$full_cond> associated to C<@result>.  C<&fun_collect> may
 1314 return a list of items, that will be used as the result of
 1315 C<Automake::Variable::traverse_recursively> (the top-level, or its
 1316 recursive calls).
 1317 
 1318 =cut
 1319 
 1320 # Contains a stack of 'from' and 'to' parts of variable
 1321 # substitutions currently in force.
 1322 my @_substfroms;
 1323 my @_substtos;
 1324 sub traverse_recursively ($&&;%)
 1325 {
 1326   ++$_traversal;
 1327   @_substfroms = ();
 1328   @_substtos = ();
 1329   my ($var, $fun_item, $fun_collect, %options) = @_;
 1330   my $cond_filter = $options{'cond_filter'};
 1331   my $inner_expand = $options{'inner_expand'};
 1332   my $skip_ac_subst = $options{'skip_ac_subst'};
 1333   return $var->_do_recursive_traversal ($var,
 1334                     $fun_item, $fun_collect,
 1335                     $cond_filter, TRUE, $inner_expand,
 1336                     $skip_ac_subst)
 1337 }
 1338 
 1339 # The guts of Automake::Variable::traverse_recursively.
 1340 sub _do_recursive_traversal ($$&&$$$$)
 1341 {
 1342   my ($var, $parent, $fun_item, $fun_collect, $cond_filter, $parent_cond,
 1343       $inner_expand, $skip_ac_subst) = @_;
 1344 
 1345   $var->set_seen;
 1346 
 1347   if ($var->{'scanned'} == $_traversal)
 1348     {
 1349       err_var $var, "variable '" . $var->name() . "' recursively defined";
 1350       return ();
 1351     }
 1352   $var->{'scanned'} = $_traversal;
 1353 
 1354   my @allresults = ();
 1355   my $cond_once = 0;
 1356   foreach my $cond ($var->conditions->conds)
 1357     {
 1358       if (ref $cond_filter)
 1359     {
 1360       # Ignore conditions that don't match $cond_filter.
 1361       next if ! $cond->true_when ($cond_filter);
 1362       # If we found out several definitions of $var
 1363       # match $cond_filter then we are in trouble.
 1364       # Tell the user we don't support this.
 1365       $var->check_defined_unconditionally ($parent, $parent_cond)
 1366         if $cond_once;
 1367       $cond_once = 1;
 1368     }
 1369       my @result = ();
 1370       my $full_cond = $cond->merge ($parent_cond);
 1371 
 1372       my @to_process = $var->value_as_list ($cond, $parent, $parent_cond);
 1373       while (@to_process)
 1374     {
 1375       my $val = shift @to_process;
 1376       # If $val is a variable (i.e. ${foo} or $(bar), not a filename),
 1377       # handle the sub variable recursively.
 1378       # (Backslashes before '}' and ')' within brackets are here to
 1379       # please Emacs's indentation.)
 1380       if ($val =~ /^\$\{([^\}]*)\}$/ || $val =~ /^\$\(([^\)]*)\)$/)
 1381         {
 1382           my $subvarname = $1;
 1383 
 1384           # If the user uses a losing variable name, just ignore it.
 1385           # This isn't ideal, but people have requested it.
 1386           next if ($subvarname =~ /\@.*\@/);
 1387 
 1388           # See if the variable is actually a substitution reference
 1389           my ($from, $to);
 1390               # This handles substitution references like ${foo:.a=.b}.
 1391           if ($subvarname =~ /^([^:]*):([^=]*)=(.*)$/o)
 1392         {
 1393           $subvarname = $1;
 1394           $to = $3;
 1395           $from = quotemeta $2;
 1396         }
 1397 
 1398           my $subvar = var ($subvarname);
 1399           # Don't recurse into undefined variables.
 1400           next unless $subvar;
 1401 
 1402           push @_substfroms, $from;
 1403           push @_substtos, $to;
 1404 
 1405           my @res = $subvar->_do_recursive_traversal ($parent,
 1406                               $fun_item,
 1407                               $fun_collect,
 1408                               $cond_filter,
 1409                               $full_cond,
 1410                               $inner_expand,
 1411                               $skip_ac_subst);
 1412           push (@result, @res);
 1413 
 1414           pop @_substfroms;
 1415           pop @_substtos;
 1416 
 1417           next;
 1418         }
 1419       # Try to expand variable references inside filenames such as
 1420       # '$(NAME).txt'.  We do not handle ':.foo=.bar'
 1421       # substitutions, but it would make little sense to use this
 1422       # here anyway.
 1423       elsif ($inner_expand
 1424          && ($val =~ /\$\{([^\}]*)\}/ || $val =~ /\$\(([^\)]*)\)/))
 1425         {
 1426           my $subvarname = $1;
 1427           my $subvar = var $subvarname;
 1428           if ($subvar)
 1429         {
 1430           # Replace the reference by its value, and reschedule
 1431           # for expansion.
 1432           foreach my $c ($subvar->conditions->conds)
 1433             {
 1434               if (ref $cond_filter)
 1435             {
 1436               # Ignore conditions that don't match $cond_filter.
 1437               next if ! $c->true_when ($cond_filter);
 1438               # If we found out several definitions of $var
 1439               # match $cond_filter then we are in trouble.
 1440               # Tell the user we don't support this.
 1441               $subvar->check_defined_unconditionally ($var,
 1442                                   $full_cond)
 1443                 if $cond_once;
 1444               $cond_once = 1;
 1445             }
 1446               my $subval = $subvar->rdef ($c)->value;
 1447               $val =~ s/\$\{$subvarname\}/$subval/g;
 1448               $val =~ s/\$\($subvarname\)/$subval/g;
 1449               unshift @to_process, split (' ', $val);
 1450             }
 1451           next;
 1452         }
 1453           # We do not know any variable with this name.  Fall through
 1454           # to filename processing.
 1455         }
 1456       elsif ($skip_ac_subst && $val =~ /^\@.+\@$/)
 1457         {
 1458           next;
 1459         }
 1460 
 1461       if ($fun_item) # $var is a filename we must process
 1462         {
 1463           my $substnum=$#_substfroms;
 1464           while ($substnum >= 0)
 1465         {
 1466           $val =~ s/$_substfroms[$substnum]$/$_substtos[$substnum]/
 1467             if defined $_substfroms[$substnum];
 1468           $substnum -= 1;
 1469         }
 1470 
 1471           # Make sure you update the doc of
 1472           # Automake::Variable::traverse_recursively
 1473           # if you change the prototype of &fun_item.
 1474           my @transformed = &$fun_item ($var, $val, $cond, $full_cond);
 1475           push (@result, @transformed);
 1476         }
 1477     }
 1478       push (@allresults, [$cond, @result]) if @result;
 1479     }
 1480 
 1481   # We only care about _recursive_ variable definitions.  The user
 1482   # is free to use the same variable several times in the same definition.
 1483   $var->{'scanned'} = -1;
 1484 
 1485   return ()
 1486     unless $fun_collect;
 1487   # Make sure you update the doc of Automake::Variable::traverse_recursively
 1488   # if you change the prototype of &fun_collect.
 1489   return &$fun_collect ($var, $parent_cond, @allresults);
 1490 }
 1491 
 1492 # _hash_varname ($VAR)
 1493 # --------------------
 1494 # Compute the key associated $VAR in %_gen_varname.
 1495 # See _gen_varname() below.
 1496 sub _hash_varname ($)
 1497 {
 1498   my ($var) = @_;
 1499   my $key = '';
 1500   foreach my $cond ($var->conditions->conds)
 1501     {
 1502       my @values = $var->value_as_list ($cond);
 1503       $key .= "($cond)@values";
 1504     }
 1505   return $key;
 1506 }
 1507 
 1508 # _hash_values (@VALUES)
 1509 # ----------------------
 1510 # Hash @VALUES for %_gen_varname.  @VALUES should be a list
 1511 # of pairs: ([$cond, @values], [$cond, @values], ...).
 1512 # See _gen_varname() below.
 1513 sub _hash_values (@)
 1514 {
 1515   my $key = '';
 1516   foreach my $pair (@_)
 1517     {
 1518       my ($cond, @values) = @$pair;
 1519       $key .= "($cond)@values";
 1520     }
 1521   return $key;
 1522 }
 1523 # ($VARNAME, $GENERATED)
 1524 # _gen_varname ($BASE, @DEFINITIONS)
 1525 # ----------------------------------
 1526 # Return a variable name starting with $BASE, that will be
 1527 # used to store definitions @DEFINITIONS.
 1528 # @DEFINITIONS is a list of pair [$COND, @OBJECTS].
 1529 #
 1530 # If we already have a $BASE-variable containing @DEFINITIONS, reuse
 1531 # it and set $GENERATED to 0.  Otherwise construct a new name and set
 1532 # $GENERATED to 1.
 1533 #
 1534 # This way, we avoid combinatorial explosion of the generated
 1535 # variables.  Especially, in a Makefile such as:
 1536 #
 1537 # | if FOO1
 1538 # | A1=1
 1539 # | endif
 1540 # |
 1541 # | if FOO2
 1542 # | A2=2
 1543 # | endif
 1544 # |
 1545 # | ...
 1546 # |
 1547 # | if FOON
 1548 # | AN=N
 1549 # | endif
 1550 # |
 1551 # | B=$(A1) $(A2) ... $(AN)
 1552 # |
 1553 # | c_SOURCES=$(B)
 1554 # | d_SOURCES=$(B)
 1555 #
 1556 # The generated c_OBJECTS and d_OBJECTS will share the same variable
 1557 # definitions.
 1558 #
 1559 # This setup can be the case of a testsuite containing lots (>100) of
 1560 # small C programs, all testing the same set of source files.
 1561 sub _gen_varname ($@)
 1562 {
 1563   my $base = shift;
 1564   my $key = _hash_values @_;
 1565 
 1566   return ($_gen_varname{$base}{$key}, 0)
 1567     if exists $_gen_varname{$base}{$key};
 1568 
 1569   my $num = 1 + ($_gen_varname_n{$base} || 0);
 1570   $_gen_varname_n{$base} = $num;
 1571   my $name = "${base}_${num}";
 1572   $_gen_varname{$base}{$key} = $name;
 1573 
 1574   return ($name, 1);
 1575 }
 1576 
 1577 =item C<$resvar = transform_variable_recursively ($var, $resvar, $base, $nodefine, $where, &fun_item, [%options])>
 1578 
 1579 =item C<$resvar = $var-E<gt>transform_variable_recursively ($resvar, $base, $nodefine, $where, &fun_item, [%options])>
 1580 
 1581 Traverse C<$var> recursively, and create a C<$resvar> variable in
 1582 which each filename in C<$var> have been transformed using
 1583 C<&fun_item>.  (C<$var> may be a variable name in the first syntax.
 1584 It must be an C<Automake::Variable> otherwise.)
 1585 
 1586 Helper variables (corresponding to sub-variables of C<$var>) are
 1587 created as needed, using C<$base> as prefix.
 1588 
 1589 Arguments are:
 1590   $var       source variable to traverse
 1591   $resvar    resulting variable to define
 1592   $base      prefix to use when naming subvariables of $resvar
 1593   $nodefine  if true, traverse $var but do not define any variable
 1594              (this assumes &fun_item has some useful side-effect)
 1595   $where     context into which variable definitions are done
 1596   &fun_item  a transformation function -- see the documentation
 1597              of &fun_item in Automake::Variable::traverse_recursively.
 1598 
 1599 This returns the string C<"\$($RESVAR)">.
 1600 
 1601 C<%options> is a list of options to pass to
 1602 C<Variable::traverse_recursively> (see this method).
 1603 
 1604 =cut
 1605 
 1606 sub transform_variable_recursively ($$$$$&;%)
 1607 {
 1608   my ($var, $resvar, $base, $nodefine, $where, $fun_item, %options) = @_;
 1609 
 1610   $var = ref $var ? $var : rvar $var;
 1611 
 1612   my $res = $var->traverse_recursively
 1613     ($fun_item,
 1614      # The code that defines the variable holding the result
 1615      # of the recursive transformation of a subvariable.
 1616      sub {
 1617        my ($subvar, $parent_cond, @allresults) = @_;
 1618        # If no definition is required, return anything: the result is
 1619        # not expected to be used, only the side effect of $fun_item
 1620        # should matter.
 1621        return 'report-me' if $nodefine;
 1622        # Cache $subvar, so that we reuse it if @allresults is the same.
 1623        my $key = _hash_varname $subvar;
 1624        $_gen_varname{$base}{$key} = $subvar->name;
 1625 
 1626        # Find a name for the variable, unless this is the top-variable
 1627        # for which we want to use $resvar.
 1628        my ($varname, $generated) =
 1629      ($var != $subvar) ? _gen_varname ($base, @allresults) : ($resvar, 1);
 1630 
 1631        # Define the variable if we are not reusing a previously
 1632        # defined variable.  At the top-level, we can also avoid redefining
 1633        # the variable if it already contains the same values.
 1634        if ($generated
 1635        && !($varname eq $var->name && $key eq _hash_values @allresults))
 1636      {
 1637        # If the new variable is the source variable, we assume
 1638        # we are trying to override a user variable.  Delete
 1639        # the old variable first.
 1640        variable_delete ($varname) if $varname eq $var->name;
 1641        # Define an empty variable in condition TRUE if there is no
 1642        # result.
 1643        @allresults = ([TRUE, '']) unless @allresults;
 1644        # Define the rewritten variable in all conditions not
 1645        # already covered by user definitions.
 1646        foreach my $pair (@allresults)
 1647          {
 1648            my ($cond, @result) = @$pair;
 1649            my $var = var $varname;
 1650            my @conds = ($var
 1651                 ? $var->not_always_defined_in_cond ($cond)->conds
 1652                 : $cond);
 1653 
 1654            foreach (@conds)
 1655          {
 1656            define ($varname, VAR_AUTOMAKE, '', $_, "@result",
 1657                '', $where, VAR_PRETTY);
 1658          }
 1659          }
 1660      }
 1661        set_seen $varname;
 1662        return "\$($varname)";
 1663      },
 1664      %options);
 1665   return $res;
 1666 }
 1667 
 1668 
 1669 =back
 1670 
 1671 =head1 SEE ALSO
 1672 
 1673 L<Automake::VarDef>, L<Automake::Condition>,
 1674 L<Automake::DisjConditions>, L<Automake::Location>.
 1675 
 1676 =cut
 1677 
 1678 1;