lib/Autom4te/ChannelDefs.pm

   1 # Copyright (C) 2002, 2003, 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 Autom4te::ChannelDefs;
  19
  20 use Autom4te::Channels;
  21
  22 =head1 NAME
  23
  24 Autom4te::ChannelDefs - channel definitions for Automake and helper functions
  25
  26 =head1 SYNOPSIS
  27
  28   use Autom4te::ChannelDefs;
  29
  30   print Autom4te::ChannelDefs::usage (), "\n";
  31   prog_error ($MESSAGE, [%OPTIONS]);
  32   error ($WHERE, $MESSAGE, [%OPTIONS]);
  33   error ($MESSAGE);
  34   fatal ($WHERE, $MESSAGE, [%OPTIONS]);
  35   fatal ($MESSAGE);
  36   verb ($MESSAGE, [%OPTIONS]);
  37   switch_warning ($CATEGORY);
  38   parse_WARNINGS ();
  39   parse_warnings ($OPTION, $ARGUMENT);
  40   Autom4te::ChannelDefs::set_strictness ($STRICTNESS_NAME);
  41
  42 =head1 DESCRIPTION
  43
  44 This packages defines channels that can be used in Automake to
  45 output diagnostics and other messages (via C<msg()>).  It also defines
  46 some helper function to enable or disable these channels, and some
  47 shorthand function to output on specific channels.
  48
  49 =cut
  50
  51 use 5.005;
  52 use strict;
  53 use Exporter;
  54
  55 use vars qw (@ISA @EXPORT);
  56
  57 @ISA = qw (Exporter);
  58 @EXPORT = qw (&prog_error &error &fatal &verb
  59               &switch_warning &parse_WARNINGS &parse_warnings);
  60
  61 =head2 CHANNELS
  62
  63 The following channels can be used as the first argument of
  64 C<Autom4te::Channel::msg>.  For some of them we list a shorthand
  65 function that makes the code more readable.
  66
  67 =over 4
  68
  69 =item C<fatal>
  70
  71 Fatal errors.  Use C<&fatal> to send messages over this channel.
  72
  73 =item C<error>
  74
  75 Common errors.   Use C<&error> to send messages over this channel.
  76
  77 =item C<error-gnu>
  78
  79 Errors related to GNU Standards.
  80
  81 =item C<error-gnu/warn>
  82
  83 Errors related to GNU Standards that should be warnings in "foreign" mode.
  84
  85 =item C<error-gnits>
  86
  87 Errors related to GNITS Standards (silent by default).
  88
  89 =item C<automake>
  90
  91 Internal errors.  Use C<&prog_error> to send messages over this channel.
  92
  93 =item C<cross>
  94
  95 Constructs compromising the cross-compilation of the package.
  96
  97 =item C<gnu>
  98
  99 Warnings related to GNU Coding Standards.
 100
 101 =item C<obsolete>
 102
 103 Warnings about obsolete features (silent by default).
 104
 105 =item C<override>
 106
 107 Warnings about user redefinitions of Automake rules or
 108 variables (silent by default).
 109
 110 =item C<portability>
 111
 112 Warnings about non-portable constructs.
 113
 114 =item C<syntax>
 115
 116 Warnings about weird syntax, unused variables, typos...
 117
 118 =item C<unsupported>
 119
 120 Warnings about unsupported (or mis-supported) features.
 121
 122 =item C<verb>
 123
 124 Messages output in C<--verbose> mode.  Use C<&verb> to send such messages.
 125
 126 =item C<note>
 127
 128 Informative messages.
 129
 130 =back
 131
 132 =cut
 133
 134 # Initialize our list of error/warning channels.
 135 # Do not forget to update &usage and the manual
 136 # if you add or change a warning channel.
 137
 138 register_channel 'fatal', type => 'fatal';
 139 register_channel 'error', type => 'error';
 140 register_channel 'error-gnu', type => 'error';
 141 register_channel 'error-gnu/warn', type => 'error';
 142 register_channel 'error-gnits', type => 'error', silent => 1;
 143 register_channel 'automake', type => 'fatal', backtrace => 1,
 144   header => ("####################\n" .
 145              "## Internal Error ##\n" .
 146              "####################\n"),
 147   footer => "\nPlease contact <bug-automake\@gnu.org>.";
 148
 149 register_channel 'cross', type => 'warning', silent => 1;
 150 register_channel 'gnu', type => 'warning';
 151 register_channel 'obsolete', type => 'warning', silent => 1;
 152 register_channel 'override', type => 'warning', silent => 1;
 153 register_channel 'portability', type => 'warning', silent => 1;
 154 register_channel 'syntax', type => 'warning';
 155 register_channel 'unsupported', type => 'warning';
 156
 157 register_channel 'verb', type => 'debug', silent => 1;
 158 register_channel 'note', type => 'debug', silent => 0;
 159
 160 =head2 FUNCTIONS
 161
 162 =over 4
 163
 164 =item C<usage ()>
 165
 166 Return the warning category descriptions.
 167
 168 =cut
 169
 170 sub usage ()
 171 {
 172   return "Warning categories include:
 173   `cross'         cross compilation issues
 174   `gnu'           GNU coding standards (default in gnu and gnits modes)
 175   `obsolete'      obsolete features or constructions
 176   `override'      user redefinitions of Automake rules or variables
 177   `portability'   portability issues (default in gnu and gnits modes)
 178   `syntax'        dubious syntactic constructs (default)
 179   `unsupported'   unsupported or incomplete features (default)
 180   `all'           all the warnings
 181   `no-CATEGORY'   turn off warnings in CATEGORY
 182   `none'          turn off all the warnings
 183   `error'         treat warnings as errors";
 184 }
 185
 186 =item C<prog_error ($MESSAGE, [%OPTIONS])>
 187
 188 Signal a programming error (on channel C<automake>),
 189 display C<$MESSAGE>, and exit 1.
 190
 191 =cut
 192
 193 sub prog_error ($;%)
 194 {
 195   my ($msg, %opts) = @_;
 196   msg 'automake', '', $msg, %opts;
 197 }
 198
 199 =item C<error ($WHERE, $MESSAGE, [%OPTIONS])>
 200
 201 =item C<error ($MESSAGE)>
 202
 203 Uncategorized errors.
 204
 205 =cut
 206
 207 sub error ($;$%)
 208 {
 209   my ($where, $msg, %opts) = @_;
 210   msg ('error', $where, $msg, %opts);
 211 }
 212
 213 =item C<fatal ($WHERE, $MESSAGE, [%OPTIONS])>
 214
 215 =item C<fatal ($MESSAGE)>
 216
 217 Fatal errors.
 218
 219 =cut
 220
 221 sub fatal ($;$%)
 222 {
 223   my ($where, $msg, %opts) = @_;
 224   msg ('fatal', $where, $msg, %opts);
 225 }
 226
 227 =item C<verb ($MESSAGE, [%OPTIONS])>
 228
 229 C<--verbose> messages.
 230
 231 =cut
 232
 233 sub verb ($;%)
 234 {
 235   my ($msg, %opts) = @_;
 236   msg 'verb', '', $msg, %opts;
 237 }
 238
 239 =item C<switch_warning ($CATEGORY)>
 240
 241 If C<$CATEGORY> is C<mumble>, turn on channel C<mumble>.
 242 If it is C<no-mumble>, turn C<mumble> off.
 243 Else handle C<all> and C<none> for completeness.
 244
 245 =cut
 246
 247 sub switch_warning ($)
 248 {
 249   my ($cat) = @_;
 250   my $has_no = 0;
 251
 252   if ($cat =~ /^no-(.*)$/)
 253     {
 254       $cat = $1;
 255       $has_no = 1;
 256     }
 257
 258   if ($cat eq 'all')
 259     {
 260       setup_channel_type 'warning', silent => $has_no;
 261     }
 262   elsif ($cat eq 'none')
 263     {
 264       setup_channel_type 'warning', silent => ! $has_no;
 265     }
 266   elsif ($cat eq 'error')
 267     {
 268       $warnings_are_errors = ! $has_no;
 269       # Set exit code if Perl warns about something
 270       # (like uninitialized variables).
 271       $SIG{"__WARN__"} =
 272         $has_no ? 'DEFAULT' : sub { print STDERR @_; $exit_code = 1; };
 273     }
 274   elsif (channel_type ($cat) eq 'warning')
 275     {
 276       setup_channel $cat, silent => $has_no;
 277     }
 278   else
 279     {
 280       return 1;
 281     }
 282   return 0;
 283 }
 284
 285 =item C<parse_WARNINGS ()>
 286
 287 Parse the WARNINGS environment variable.
 288
 289 =cut
 290
 291 sub parse_WARNINGS ()
 292 {
 293   if (exists $ENV{'WARNINGS'})
 294     {
 295       # Ignore unknown categories.  This is required because WARNINGS
 296       # should be honored by many tools.
 297       switch_warning $_ foreach (split (',', $ENV{'WARNINGS'}));
 298     }
 299 }
 300
 301 =item C<parse_warnings ($OPTION, @ARGUMENT)>
 302
 303 Parse the argument of C<--warning=CATEGORY> or C<-WCATEGORY>.
 304
 305 C<$OPTIONS> is C<"--warning"> or C<"-W">, C<@ARGUMENT> is a list of
 306 C<CATEGORY>.
 307
 308 This can be used as a argument to C<Getopt>.
 309
 310 =cut
 311
 312 sub parse_warnings ($@)
 313 {
 314   my ($opt, @categories) = @_;
 315
 316   foreach my $cat (map { split ',' } @categories)
 317     {
 318       msg 'unsupported', "unknown warning category `$cat'"
 319         if switch_warning $cat;
 320     }
 321 }
 322
 323 =item C<set_strictness ($STRICTNESS_NAME)>
 324
 325 Configure channels for strictness C<$STRICTNESS_NAME>.
 326
 327 =cut
 328
 329 sub set_strictness ($)
 330 {
 331   my ($name) = @_;
 332
 333   if ($name eq 'gnu')
 334     {
 335       setup_channel 'error-gnu', silent => 0;
 336       setup_channel 'error-gnu/warn', silent => 0, type => 'error';
 337       setup_channel 'error-gnits', silent => 1;
 338       setup_channel 'portability', silent => 0;
 339       setup_channel 'gnu', silent => 0;
 340     }
 341   elsif ($name eq 'gnits')
 342     {
 343       setup_channel 'error-gnu', silent => 0;
 344       setup_channel 'error-gnu/warn', silent => 0, type => 'error';
 345       setup_channel 'error-gnits', silent => 0;
 346       setup_channel 'portability', silent => 0;
 347       setup_channel 'gnu', silent => 0;
 348     }
 349   elsif ($name eq 'foreign')
 350     {
 351       setup_channel 'error-gnu', silent => 1;
 352       setup_channel 'error-gnu/warn', silent => 0, type => 'warning';
 353       setup_channel 'error-gnits', silent => 1;
 354       setup_channel 'portability', silent => 1;
 355       setup_channel 'gnu', silent => 1;
 356     }
 357   else
 358     {
 359       prog_error "level `$name' not recognized\n";
 360     }
 361 }
 362
 363 =back
 364
 365 =head1 SEE ALSO
 366
 367 L<Autom4te::Channels>
 368
 369 =head1 HISTORY
 370
 371 Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt>.
 372
 373 =cut
 374
 375 ### Setup "GNU" style for perl-mode and cperl-mode.
 376 ## Local Variables:
 377 ## perl-indent-level: 2
 378 ## perl-continued-statement-offset: 2
 379 ## perl-continued-brace-offset: 0
 380 ## perl-brace-offset: 0
 381 ## perl-brace-imaginary-offset: 0
 382 ## perl-label-offset: -2
 383 ## cperl-indent-level: 2
 384 ## cperl-brace-offset: 0
 385 ## cperl-continued-brace-offset: 0
 386 ## cperl-label-offset: -2
 387 ## cperl-extra-newline-before-brace: t
 388 ## cperl-merge-trailing-else: nil
 389 ## cperl-continued-statement-offset: 2
 390 ## End: