lib/Automake/Options.pm

   1 # Copyright (C) 2003-2013 Free Software Foundation, Inc.
   2
   3 # This program is free software; you can redistribute it and/or modify
   4 # it under the terms of the GNU General Public License as published by
   5 # the Free Software Foundation; either version 2, or (at your option)
   6 # any later version.
   7
   8 # This program is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 # GNU General Public License for more details.
  12
  13 # You should have received a copy of the GNU General Public License
  14 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  15
  16 package Automake::Options;
  17
  18 use 5.006;
  19 use strict;
  20 use Exporter;
  21 use Automake::Config;
  22 use Automake::ChannelDefs;
  23 use Automake::Channels;
  24 use Automake::Version;
  25
  26 use vars qw (@ISA @EXPORT);
  27
  28 @ISA = qw (Exporter);
  29 @EXPORT = qw (option global_option
  30               set_option set_global_option
  31               unset_option unset_global_option
  32               process_option_list process_global_option_list
  33               set_strictness $strictness $strictness_name
  34               &FOREIGN &GNU &GNITS);
  35
  36 =head1 NAME
  37
  38 Automake::Options - keep track of Automake options
  39
  40 =head1 SYNOPSIS
  41
  42   use Automake::Options;
  43
  44   # Option lookup and setting.
  45   $opt = option 'name';
  46   $opt = global_option 'name';
  47   set_option 'name', 'value';
  48   set_global_option 'name', 'value';
  49   unset_option 'name';
  50   unset_global_option 'name';
  51
  52   # Batch option setting.
  53   process_option_list $location, @names;
  54   process_global_option_list $location, @names;
  55
  56   # Strictness lookup and setting.
  57   set_strictness 'foreign';
  58   set_strictness 'gnu';
  59   set_strictness 'gnits';
  60   if ($strictness >= GNU) { ... }
  61   print "$strictness_name\n";
  62
  63 =head1 DESCRIPTION
  64
  65 This packages manages Automake's options and strictness settings.
  66 Options can be either local or global.  Local options are set using an
  67 C<AUTOMAKE_OPTIONS> variable in a F<Makefile.am> and apply only to
  68 this F<Makefile.am>.  Global options are set from the command line or
  69 passed as an argument to C<AM_INIT_AUTOMAKE>, they apply to all
  70 F<Makefile.am>s.
  71
  72 =cut
  73
  74 # Values are the Automake::Location of the definition.
  75 use vars '%_options';        # From AUTOMAKE_OPTIONS
  76 use vars '%_global_options'; # From AM_INIT_AUTOMAKE or the command line.
  77
  78 # Whether process_option_list has already been called for the current
  79 # Makefile.am.
  80 use vars '$_options_processed';
  81 # Whether process_global_option_list has already been called.
  82 use vars '$_global_options_processed';
  83
  84 =head2 Constants
  85
  86 =over 4
  87
  88 =item FOREIGN
  89
  90 =item GNU
  91
  92 =item GNITS
  93
  94 Strictness constants used as values for C<$strictness>.
  95
  96 =back
  97
  98 =cut
  99
 100 # Constants to define the "strictness" level.
 101 use constant FOREIGN => 0;
 102 use constant GNU     => 1;
 103 use constant GNITS   => 2;
 104
 105 =head2 Variables
 106
 107 =over 4
 108
 109 =item C<$strictness>
 110
 111 The current strictness.  One of C<FOREIGN>, C<GNU>, or C<GNITS>.
 112
 113 =item C<$strictness_name>
 114
 115 The current strictness name.  One of C<'foreign'>, C<'gnu'>, or C<'gnits'>.
 116
 117 =back
 118
 119 =cut
 120
 121 # Strictness levels.
 122 use vars qw ($strictness $strictness_name);
 123
 124 # Strictness level as set on command line.
 125 use vars qw ($_default_strictness $_default_strictness_name);
 126
 127
 128 =head2 Functions
 129
 130 =over 4
 131
 132 =item C<Automake::Options::reset>
 133
 134 Reset the options variables for the next F<Makefile.am>.
 135
 136 In other words, this gets rid of all local options in use by the
 137 previous F<Makefile.am>.
 138
 139 =cut
 140
 141 sub reset ()
 142 {
 143   $_options_processed = 0;
 144   %_options = %_global_options;
 145   # The first time we are run,
 146   # remember the current setting as the default.
 147   if (defined $_default_strictness)
 148     {
 149       $strictness = $_default_strictness;
 150       $strictness_name = $_default_strictness_name;
 151     }
 152   else
 153     {
 154       $_default_strictness = $strictness;
 155       $_default_strictness_name = $strictness_name;
 156     }
 157 }
 158
 159 =item C<$value = option ($name)>
 160
 161 =item C<$value = global_option ($name)>
 162
 163 Query the state of an option.  If the option is unset, this
 164 returns the empty list.  Otherwise it returns the option's value,
 165 as set by C<set_option> or C<set_global_option>.
 166
 167 Note that C<global_option> should be used only when it is
 168 important to make sure an option hasn't been set locally.
 169 Otherwise C<option> should be the standard function to
 170 check for options (be they global or local).
 171
 172 =cut
 173
 174 sub option ($)
 175 {
 176   my ($name) = @_;
 177   return () unless defined $_options{$name};
 178   return $_options{$name};
 179 }
 180
 181 sub global_option ($)
 182 {
 183   my ($name) = @_;
 184   return () unless defined $_global_options{$name};
 185   return $_global_options{$name};
 186 }
 187
 188 =item C<set_option ($name, $value)>
 189
 190 =item C<set_global_option ($name, $value)>
 191
 192 Set an option.  By convention, C<$value> is usually the location
 193 of the option definition.
 194
 195 =cut
 196
 197 sub set_option ($$)
 198 {
 199   my ($name, $value) = @_;
 200   $_options{$name} = $value;
 201 }
 202
 203 sub set_global_option ($$)
 204 {
 205   my ($name, $value) = @_;
 206   $_global_options{$name} = $value;
 207 }
 208
 209
 210 =item C<unset_option ($name)>
 211
 212 =item C<unset_global_option ($name)>
 213
 214 Unset an option.
 215
 216 =cut
 217
 218 sub unset_option ($)
 219 {
 220   my ($name) = @_;
 221   delete $_options{$name};
 222 }
 223
 224 sub unset_global_option ($)
 225 {
 226   my ($name) = @_;
 227   delete $_global_options{$name};
 228 }
 229
 230
 231 =item C<process_option_list (@list)>
 232
 233 =item C<process_global_option_list (@list)>
 234
 235 Process Automake's option lists.  C<@list> should be a list of hash
 236 references with keys C<option> and C<where>, where C<option> is an
 237 option as they occur in C<AUTOMAKE_OPTIONS> or C<AM_INIT_AUTOMAKE>,
 238 and C<where> is the location where that option occurred.
 239
 240 These functions should be called at most once for each set of options
 241 having the same precedence; i.e., do not call it twice for two options
 242 from C<AM_INIT_AUTOMAKE>.
 243
 244 Return 0 on error, 1 otherwise.
 245
 246 =cut
 247
 248 # $BOOL
 249 # _option_is_from_configure ($OPTION, $WHERE)
 250 # ----------------------------------------------
 251 # Check that the $OPTION given in location $WHERE is specified with
 252 # AM_INIT_AUTOMAKE, not with AUTOMAKE_OPTIONS.
 253 sub _option_is_from_configure ($$)
 254 {
 255   my ($opt, $where)= @_;
 256   return 1
 257     if $where->get =~ /^configure\./;
 258   error $where,
 259         "option '$opt' can only be used as argument to AM_INIT_AUTOMAKE\n" .
 260         "but not in AUTOMAKE_OPTIONS makefile statements";
 261   return 0;
 262 }
 263
 264 # $BOOL
 265 # _is_valid_easy_option ($OPTION)
 266 # -------------------------------
 267 # Explicitly recognize valid automake options that require no
 268 # special handling by '_process_option_list' below.
 269 sub _is_valid_easy_option ($)
 270 {
 271   my $opt = shift;
 272   return scalar grep { $opt eq $_ } qw(
 273     check-news
 274     color-tests
 275     dejagnu
 276     dist-bzip2
 277     dist-lzip
 278     dist-xz
 279     dist-zip
 280     info-in-builddir
 281     no-define
 282     no-dependencies
 283     no-dist
 284     no-dist-gzip
 285     no-exeext
 286     no-installinfo
 287     no-installman
 288     no-texinfo.tex
 289     nostdinc
 290     readme-alpha
 291     serial-tests
 292     parallel-tests
 293     silent-rules
 294     std-options
 295     subdir-objects
 296   );
 297 }
 298
 299 # $BOOL
 300 # _process_option_list (\%OPTIONS, @LIST)
 301 # ------------------------------------------
 302 # Process a list of options.  \%OPTIONS is the hash to fill with options
 303 # data.  @LIST is a list of options as get passed to public subroutines
 304 # process_option_list() and process_global_option_list() (see POD
 305 # documentation above).
 306 sub _process_option_list (\%@)
 307 {
 308   my ($options, @list) = @_;
 309   my @warnings = ();
 310
 311   foreach my $h (@list)
 312     {
 313       local $_ = $h->{'option'};
 314       my $where = $h->{'where'};
 315       $options->{$_} = $where;
 316       if ($_ eq 'gnits' || $_ eq 'gnu' || $_ eq 'foreign')
 317         {
 318           set_strictness ($_);
 319         }
 320       # TODO: Remove this special check in Automake 3.0.
 321       elsif (/^(.*\/)?ansi2knr$/)
 322         {
 323           # Obsolete (and now removed) de-ANSI-fication support.
 324           error ($where,
 325                  "automatic de-ANSI-fication support has been removed");
 326           return 0;
 327         }
 328       # TODO: Remove this special check in Automake 3.0.
 329       elsif ($_ eq 'cygnus')
 330         {
 331           error $where, "support for Cygnus-style trees has been removed";
 332           return 0;
 333         }
 334       # TODO: Remove this special check in Automake 3.0.
 335       elsif ($_ eq 'dist-lzma')
 336         {
 337           error ($where, "support for lzma-compressed distribution " .
 338                          "archives has been removed");
 339           return 0;
 340         }
 341       # TODO: Make this a fatal error in Automake 2.0.
 342       elsif ($_ eq 'dist-shar')
 343         {
 344           msg ('obsolete', $where,
 345                "support for shar distribution archives is deprecated.\n" .
 346                "  It will be removed in Automake 2.0");
 347         }
 348       # TODO: Make this a fatal error in Automake 2.0.
 349       elsif ($_ eq 'dist-tarZ')
 350         {
 351           msg ('obsolete', $where,
 352                "support for distribution archives compressed with " .
 353                "legacy program 'compress' is deprecated.\n" .
 354                "  It will be removed in Automake 2.0");
 355         }
 356       elsif (/^filename-length-max=(\d+)$/)
 357         {
 358           delete $options->{$_};
 359           $options->{'filename-length-max'} = [$_, $1];
 360         }
 361       elsif ($_ eq 'tar-v7' || $_ eq 'tar-ustar' || $_ eq 'tar-pax')
 362         {
 363           if (not _option_is_from_configure ($_, $where))
 364             {
 365               return 0;
 366             }
 367           for my $opt ('tar-v7', 'tar-ustar', 'tar-pax')
 368             {
 369               next
 370                 if $opt eq $_ or ! exists $options->{$opt};
 371               error ($where,
 372                      "options '$_' and '$opt' are mutually exclusive");
 373               return 0;
 374             }
 375         }
 376       elsif (/^\d+\.\d+(?:\.\d+)?[a-z]?(?:-[A-Za-z0-9]+)?$/)
 377         {
 378           # Got a version number.
 379           if (Automake::Version::check ($VERSION, $&))
 380             {
 381               error ($where, "require Automake $_, but have $VERSION",
 382                      uniq_scope => US_GLOBAL);
 383               return 0;
 384             }
 385         }
 386       elsif (/^(?:--warnings=|-W)(.*)$/)
 387         {
 388           my @w = map { { cat => $_, loc => $where} } split (',', $1);
 389           push @warnings, @w;
 390         }
 391       elsif (! _is_valid_easy_option $_)
 392         {
 393           error ($where, "option '$_' not recognized");
 394           return 0;
 395         }
 396     }
 397   # We process warnings here, so that any explicitly-given warning setting
 398   # will take precedence over warning settings defined implicitly by the
 399   # strictness.
 400   foreach my $w (@warnings)
 401     {
 402       msg 'unsupported', $w->{'loc'},
 403           "unknown warning category '$w->{'cat'}'"
 404         if switch_warning $w->{cat};
 405     }
 406   return 1;
 407 }
 408
 409 sub process_option_list (@)
 410 {
 411   prog_error "local options already processed"
 412     if $_options_processed;
 413   $_options_processed = 1;
 414   _process_option_list (%_options, @_);
 415 }
 416
 417 sub process_global_option_list (@)
 418 {
 419   prog_error "global options already processed"
 420     if $_global_options_processed;
 421   $_global_options_processed = 1;
 422   _process_option_list (%_global_options, @_);
 423 }
 424
 425 =item C<set_strictness ($name)>
 426
 427 Set the current strictness level.
 428 C<$name> should be one of C<'foreign'>, C<'gnu'>, or C<'gnits'>.
 429
 430 =cut
 431
 432 # Set strictness.
 433 sub set_strictness ($)
 434 {
 435   $strictness_name = $_[0];
 436
 437   Automake::ChannelDefs::set_strictness ($strictness_name);
 438
 439   if ($strictness_name eq 'gnu')
 440     {
 441       $strictness = GNU;
 442     }
 443   elsif ($strictness_name eq 'gnits')
 444     {
 445       $strictness = GNITS;
 446     }
 447   elsif ($strictness_name eq 'foreign')
 448     {
 449       $strictness = FOREIGN;
 450     }
 451   else
 452     {
 453       prog_error "level '$strictness_name' not recognized";
 454     }
 455 }
 456
 457 1;
 458
 459 ### Setup "GNU" style for perl-mode and cperl-mode.
 460 ## Local Variables:
 461 ## perl-indent-level: 2
 462 ## perl-continued-statement-offset: 2
 463 ## perl-continued-brace-offset: 0
 464 ## perl-brace-offset: 0
 465 ## perl-brace-imaginary-offset: 0
 466 ## perl-label-offset: -2
 467 ## cperl-indent-level: 2
 468 ## cperl-brace-offset: 0
 469 ## cperl-continued-brace-offset: 0
 470 ## cperl-label-offset: -2
 471 ## cperl-extra-newline-before-brace: t
 472 ## cperl-merge-trailing-else: nil
 473 ## cperl-continued-statement-offset: 2
 474 ## End: