/ 
Perl5-Build-Warnings-0.05
River stage zero No dependents
/ Perl5::Build::Warnings

NAME

Perl5::Build::Warnings - Parse make output for build-time warnings

SYNOPSIS

use Perl5::Build::Warnings;

my $self = Perl5::Build::Warnings->new( { file => '/path/to/make.log' } );

my $hashref = $self->get_warnings_groups;

my $arrayref = $self->get_warnings;

$self->report_warnings_groups;

$arrayref = $self->get_warnings_for_group('Wunused-variable');

$arrayref = $self->get_warnings_for_source('op.c');

DESCRIPTION

Perl5::Build::Warnings is a module for use in studying build-time warnings emitted by make when building the Perl 5 core distribution from source code.

Prerequisites

CPAN module Capture::Tiny is used in this library's test suite, but not in the module itself. There are currently no other prerequisites not found in the Perl 5 core distribution.

Assumptions

Logging of make Output

The module assumes that the user has logged the output of make (or make test_prep -- but not make test -- or Windows equivalents) to a plain-text file. Something like:

make test_prep 2>&1 > /path/to/make.log

The build log may be gzipped-compressed, e.g.:

make test_prep 2>&1 | gzip -c > /path/to/make.log.gz

Format for Build-Time Warnings

The module assumes that within such a logfile, warnings are recorded in this format:

op.c:5468:34: warning: argument ‘o’ might be clobbered by ‘longjmp’ or ‘vfork’ [-Wclobbered]

That is,

<filename>:<line_number>:<character_number>: warning: <warning_description> [-<Wwarning_class>]

Note that the first field recorded, filename may be either the basename of a file in the top-level of the source code or a relative path to a file beneath the top-level.

Note further that the last field recorded, the class of warning, starts with an open bracket ([), followed by a hyphen and an upper-case 'W' (-W), followed by the warning class, followed by a close bracket (]). In this module we will ignore the open and close brackets and the hyphen, but we will capture and report the upper-case 'W'. Hence, whereas the log will record

[-Wclobbered]

... this module will store and report that information as:

Wclobbered

This is done in part because we may wish to use this data on the command-line and the hyphen is likely to be significant to the shell.

METHODS

new()

  • Purpose

    Perl5::Build::Warnings constructor.

  • Arguments

    $file = "./t/data/make.g++-8-list-util-fallthrough.output.txt";
$self = Perl5::Build::Warnings->new( { file => $file } );

    Single hash reference with one required element, file, whose value is a path to a file holding a log of make's output.

  • Return Value

    Perl5::Build::Warnings object.

get_warnings_groups()

  • Purpose

    Identify the types of build-time warnings found in the make log and the number of each such type.

  • Arguments

    $hashref = $self->get_warnings_groups();

    None.

  • Return Value

    Reference to a hash whose elements are keyed on warnings classes (e.g., Wclobbered). The value of each element is the number of times such class appeared in the file.

report_warnings_groups()

  • Purpose

    Pretty-print to STDOUT the information returned by get_warnings_groups.

  • Arguments

    $self->report_warnings_groups;

    None.

  • Return Value

    Implicitly returns a Perl-true value.

  • Comment

    The information reported will appear as below (2 leading whitespaces), but may change in the future.

    Wcast-function-type                        6
Wclobbered                                 2
Wformat-overflow=                          2
Wignored-qualifiers                        4
Wimplicit-fallthrough=                    32
Wmultistatement-macros                     1
Wpragmas                                   3

get_warnings()

  • Purpose

    Generate a list of all warnings.

  • Arguments

    $arrayref = $self->get_warnings();

  • Return Value

    Array reference, each element of which is a reference to a hash holding a parsing of the elements of an individual warning.

get_warnings_for_group()

  • Purpose

    Get a list of all the warnings for one specified warnings group.

  • Arguments

    $arrayref = $self->get_warnings_for_group("Wduplicate-decl-specifier");

    String holding name of one group of warnings. Each such string must begin with an upper-case W. As mentioned above, we drop the leading hyphen to avoid confusing the shell.

  • Return Value

    Array reference, each element of which is a reference to a hash holding a parsing of the elements of an individual warning of the specified warnings group.

get_warnings_for_source()

  • Purpose

    Get a list of all the warnings generated from one specified source file.

  • Arguments

    $arrayref = $self->get_warnings_for_source('op.c');

    String holding name of one source file. Note that there may be some ambiguity here. Use with caution.

  • Return Value

    Array reference, each element of which is a reference to a hash holding a parsing of the elements of an individual warning of the specified warnings source.

BUGS

None reported so far. The author prefers patches filed at http://rt.cpan.org rather than pull requests at github.

AUTHOR

James E Keenan
CPAN ID: JKEENAN
jkeenan@cpan.org
http://thenceforward.net/perl/modules/Perl5-Build-Warnings/

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl(1).