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