view release on metacpan or  search on metacpan

xt/warnings-transitions.pl  view on Meta::CPAN

appeared.

=head1 USAGE

Call this program with command-line switches.  At the present time there are 4
command-line switches whose values the user must provide, as there are no
defaults.  There is 1 command-line switch which is recommended and for which a
value must be provided.  There are currently 4 other command-line switches for
which defaults are provided.  All switches are called in "long option" style,
I<i.e.> starting with two hyphens (C<-->).

=head2 Required Command-Line Switches

=over 4

=item * C<--git_checkout_dir>

Full path to a directory holding a F<git> checkout of the Perl 5 core
distribution.

=item * C<--workdir>

Full path to a directory where files created in the course of running the
program will be deposited.

=item * C<--first>

Full (40 character) SHA of the first (chronologically earliest) F<git> commit
to the Perl 5 repository to be tested during bisection.

=item * C<--last>

Full (40 character) SHA of the last (chronologically latest) F<git> commit to
the Perl 5 repository to be tested during bisection.

=back

=head2 Recommended Command-Line Switch

=over 4

=item * C<--pattern_sought>

String holding the build-time (F<make>) warning whose first appearance you are trying to ascertain,
subject to these modifications:

=item *

Substitute one underscore character (C<_>) for the line number
(vertical) and character number (horizontal).

=item *

Remove the hyphen (C<->) between the open bracket (C<\[>) and the upper-case
'W' (C<W>) in the warnings category.

=back

Hence, a warning which appears in captured F<make> output like this:

    Opcode.xs: In function ‘XS_Opcode_invert_opset’:
    Opcode.xs:363:25: warning: overflow in implicit constant conversion [-Woverflow]
      bitmap[opset_len-1] &= ~(0xFF << (PL_maxo & 0x07));
                             ^

... will be called on the command-line like this:

    --pattern_sought="Opcode.xs:_:_: warning: overflow in implicit constant conversion [Woverflow]"

If this switch is called, a value must be provided.  But if the switch is not
called, the program will simply avoid running the code which uses the value.

Note:  If the pattern contains any single-quote mark (C<'>) or similar
characters, you are probably better off double-quoting the pattern on the
command line (as above).

=head2 Optional Command-Line Switches

=over 4

=item * C<compiler>

Compiler (and possibly compiler version) which is generating the warning.
The warning pattern is currently observed in various versions of F<gcc>,
F<g++> and F<clang>.  Defaults to C<gcc>.  Note that if your default version
of F<gcc> is C<7> but you wish to track a warning generated by a different
version of F<gcc>, you would call something like C<gcc-8> (on Linux) or
C<gcc8> on FreeBSD.

    --compiler='gcc-8'

Needless to say, you must have these alternate compiler versions installed.

=item * C<branch>

Branch of the Perl 5 core distribution you are testing for the warning.
Defaults to C<blead>.

    --branch=blead

=item * C<configure_command>

String holding the invocation of F<./Configure> used in builds where the warning's first appearance is being explored.  Defaults to:

    --configure_command='sh ./Configure -des -Dusedevel -Dcc=gcc 1>/dev/null 2>&1'

=item * C<make_command>

String holding the invocation of F<make> used in the builds under investigation.  Defaults to:

    --make_command='make -j${TEST_JOBS} 1>/dev/null'

=back

=head1 PREREQUISITES

Once you have installed the Devel-Git-MultiBisect distribution from CPAN, the
only non-core distribution you need is Data-Dump.

=head1 OUTPUTS

Like all programs using L<Devel::Git::MultiBisect::BuildTransistions>, the
program prints a log to STDOUT of each commit tested.  In the course of