Context Navigation

Variable.pm

Visit:

Last change on this file was 3147, checked in by bird, 18 years ago
automake 1.10
File size: 44.8 KB

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

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: trunk/essentials/sys-devel/automake-1.10/lib/Automake/Variable.pm

Download in other formats: