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