This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document config_args limitations reported in [perl #70912]
[metaconfig.git] / U / mkglossary
1 #!/usr/bin/perl
2
3 use strict;
4 use warnings;
5
6 use File::Basename;
7
8 # WARNING:  This is site-specific.  Change to the location
9 # where you have installed dist-3.0PL70.
10 my @std_units = glob ("/pro/3gl/CPAN/lib/dist/U/*.U");
11 my $PWD       =       "/pro/3gl/CPAN/perl";
12
13 -d "U" and chdir "U";
14 my @perl_units = glob ("$PWD/U/*/*.U");
15 push (@perl_units, @std_units);
16
17 # Get the list of config.sh symbols.  Be sure this is up to date!
18 # (I run the U/mksample script first to be sure.)
19 open my $wanted, "< $PWD/Porting/config.sh" or die "$0: open $PWD/Wanted: $!\n";
20 my @WANTED = map  { $_->[0] }
21              sort { $a->[1] cmp $b->[1] }
22              map  { [ $_, lc $_ ] } <$wanted>;
23 close $wanted;
24
25 print <<'EOM';
26
27 !!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
28 This file is built by metaconfig.
29
30 This file contains a description of all the shell variables whose value is
31 determined by the Configure script.  Variables intended for use in C
32 programs (e.g. I_UNISTD) are already described in config_h.SH.  [`configpm'
33 generates pod documentation for Config.pm from this file--please try to keep
34 the formatting regular.]
35
36 EOM
37
38 my ($Loc, %expl, %file, %predef);
39 foreach my $file (@perl_units) {
40     open my $fh, "< $file" or die "$0: open $file: $!";
41     my $base = basename ($file);
42     $Loc = $file, next if $base eq "Loc.U" and not defined $Loc;
43     my @var;
44     while (<$fh>) {
45         if (m/^\?S:\w+[ \t:]/ .. m/^\?S:\.$/) {
46             s/[ \t]+$//;
47             if (m/^\?S:.$/) {
48                 my ($var) = ((shift @var) =~ /^(\w+)/);
49                 unless (exists $expl{$var}) {
50                     $expl{$var} = [ @var, "\n" ];
51                     $file{$var} = $base;
52                     }
53                 @var = ();
54                 }
55             else {
56                 s/^\?S://;              # Remove leading ?S: markers.
57                 s/^\s+(?=.)/\t/;        # Ensure all lines begin with tabs.
58                 push @var, $_;
59                 }
60             }
61         }
62     close $fh or die "$0: close $file: $!";
63     }
64
65 defined $Loc or die "$0: Couldn't locate Loc.U: $!";
66
67 open my $fh, "< $Loc" or die "$0: open $Loc: $!";
68 while (<$fh>) {
69     m/^\?(\w+):\1$/ and ($expl{$1}, $file{$1}) = (1, "Loc.U");
70     }
71 close $fh or die "$0: close $Loc: $!";
72
73 {   local $/ = "\n\n";
74     for (<DATA>) {
75         m/^(\w+)/;
76         $predef{$1} = $_;
77         }
78     }
79
80 for (@WANTED) {
81     chomp;
82     m/^#/ and next;     # Skip comments
83     m/^:/ and next;     # Skip comments
84     m/^$/ and next;     # Skip empty sections
85     my ($var, $val) = split /=/, $_, 2;
86
87     if (exists $expl{$var}) {
88         if ($file{$var} eq "Loc.U") {
89             print "$var (Loc.U):\n";
90             if ($val eq "''") {
91                 # If we didn't have d_portable, this info might be
92                 # useful, but it still won't help with non-standard
93                 # stuff if perl is built on one system but installed
94                 # on others (this is common with Linux distributions,
95                 # for example).
96                 print <<EOE;
97         This variable is defined but not used by Configure.
98         The value is the empty string and is not useful.
99
100 EOE
101                 }
102             else {
103                 print <<EOE;
104         This variable is used internally by Configure to determine the
105         full pathname (if any) of the $var program.  After Configure runs,
106         the value is reset to a plain "$var" and is not useful.
107
108 EOE
109                 }
110             }
111         else {
112             print "$var ($file{$var}):\n";
113             print @{$expl{$var}};
114             }
115         next;
116         }
117
118     # Handle special variables from Oldsyms.U.  Since these start
119     # with capital letters, metalint considers them to be "special
120     # unit" symbols.  It's easier to define them here than to try
121     # to fool metalint any further.   --AD  22 Oct 1999
122     # Similarly, handle the config_arg* variables from Options.U.
123     # -- AD 8 Dec 2009
124     if (exists $predef{$var}) {
125         print  $predef{$var};
126         next;
127         }
128
129     $var =~ /^(Author|Date|Header|Id|Locker|Log|Mcc|RCSfile|Revision|Source|State)$|_cflags$|^config_arg/
130         or warn "$0: couldn't find $var\n"
131     }
132 __END__
133 PERL_REVISION (Oldsyms.U):
134         In a Perl version number such as 5.6.2, this is the 5.
135         This value is manually set in patchlevel.h
136
137 PERL_VERSION (Oldsyms.U):
138         In a Perl version number such as 5.6.2, this is the 6.
139         This value is manually set in patchlevel.h
140
141 PERL_SUBVERSION (Oldsyms.U):
142         In a Perl version number such as 5.6.2, this is the 2.
143         Values greater than 50 represent potentially unstable
144         development subversions.
145         This value is manually set in patchlevel.h
146
147 PERL_APIVERSION (Oldsyms.U):
148         This value is manually set in patchlevel.h and is used
149         to set the Configure apiversion variable.
150
151 CONFIGDOTSH (Oldsyms.U):
152         This is set to 'true' in config.sh so that a shell script
153         sourcing config.sh can tell if it has been sourced already.
154
155 PERL_CONFIG_SH (Oldsyms.U):
156         This is set to 'true' in config.sh so that a shell script
157         sourcing config.sh can tell if it has been sourced already.
158
159 PERL_API_REVISION (patchlevel.h):
160         This number describes the earliest compatible PERL_REVISION of
161         Perl ("compatibility" here being defined as sufficient binary/API
162         compatibility to run XS code built with the older version).
163         Normally this does not change across maintenance releases.
164         Please read the comment in patchlevel.h.
165
166 PERL_API_VERSION (patchlevel.h):
167         This number describes the earliest compatible PERL_VERSION of
168         Perl ("compatibility" here being defined as sufficient binary/API
169         compatibility to run XS code built with the older version).
170         Normally this does not change across maintenance releases.
171         Please read the comment in patchlevel.h.
172
173 PERL_API_SUBVERSION (patchlevel.h):
174         This number describes the earliest compatible PERL_SUBVERSION of
175         Perl ("compatibility" here being defined as sufficient binary/API
176         compatibility to run XS code built with the older version).
177         Normally this does not change across maintenance releases.
178         Please read the comment in patchlevel.h.
179
180 PERL_PATCHLEVEL (Oldsyms.U):
181         This symbol reflects the patchlevel, if available. Will usually
182         come from the .patch file, which is available when the perl
183         source tree was fetched with rsync.
184
185 config_args (Options.U):
186         This variable contains a single string giving the command-line
187         arguments passed to Configure.  Spaces within arguments,
188         quotes, and escaped characters are not correctly preserved.
189         To reconstruct the command line, you must assemble the individual
190         command line pieces, given in config_arg[0-9]*.
191
192 config_arg0 (Options.U):
193         This variable contains the string used to invoke the Configure
194         command, as reported by the shell in the $0 variable.
195
196 config_argc (Options.U):
197         This variable countains the number of command-line arguments
198         passed to Configure, as reported by the shell in the $# variable.
199         The individual arguments are stored as variables config_argc1,
200         config_argc2, etc.
201