Ricardo SIGNES > perl-5.20.0 > bisect.pl

Download:
perl-5.20.0.tar.gz

Annotate this POD

Website

Source   Latest Release: perl-5.21.6

NAME ^

bisect.pl - use git bisect to pinpoint changes

SYNOPSIS ^

    # When did this become an error?
    .../Porting/bisect.pl -e 'my $a := 2;'
    # When did this stop being an error?
    .../Porting/bisect.pl --expect-fail -e '1 // 2'
    # When did this test start failing?
    .../Porting/bisect.pl --target t/op/sort.t
    # When were all lines matching this pattern removed from all files?
    .../Porting/bisect.pl --match '\b(?:PL_)hash_seed_set\b'
    # When was some line matching this pattern added to some file?
    .../Porting/bisect.pl --expect-fail --match '\buseithreads\b'
    # When did this test program stop exiting 0?
    .../Porting/bisect.pl -- ./perl -Ilib ../test_prog.pl
    # When did this first become valid syntax?
    .../Porting/bisect.pl --target=miniperl --end=v5.10.0 \
         --expect-fail -e 'my $a := 2;'
    # What was the last revision to build with these options?
    .../Porting/bisect.pl --test-build -Dd_dosuid
    # When did this test program start generating errors from valgrind?
    .../Porting/bisect.pl --valgrind ../test_prog.pl

DESCRIPTION ^

Together bisect.pl and bisect-runner.pl attempt to automate the use of git bisect as much as possible. With one command (and no other files) it's easy to find out

usually without needing to know which versions of perl to use as start and end revisions.

By default bisect.pl will process all options, then use the rest of the command line as arguments to list system to run a test case. By default, the test case should pass (exit with 0) on earlier perls, and fail (exit non-zero) on blead. bisect.pl will use bisect-runner.pl to find the earliest stable perl version on which the test case passes, check that it fails on blead, and then use bisect-runner.pl with git bisect run to find the commit which caused the failure.

Many of perl's own test scripts exit 0 even if their TAP reports test failures, and some need particular setup (such as running from the right directory, or adding -T to the command line). Hence if you want to bisect a test script, you can specify it with the --target option, and it will be invoked using t/TEST which performs all the setup, and exits non-zero if the TAP reports failures. This works for any file ending .t, so you can use it with a file outside of the working checkout, for example to test a particular version of a test script, as a path inside the repository will (of course) be testing the version of the script checked out for the current revision, which may be too early to have the test you are interested in.

Because the test case is the complete argument to system, it is easy to run something other than the perl built, if necessary. If you need to run the perl built, you'll probably need to invoke it as ./perl -Ilib .... As a special case, if the first argument of the test case is a readable file (whether executable or not), matching qr{\A#!./(?:mini)?perl\b} then it will have ./perl <-Ilib> (or ./miniperl) prepended to it.

You need a clean checkout to run a bisect. You can use the checkout containing Porting/bisect.pl if you wish - in this case Porting/bisect.pl will copy Porting/bisect-runner.pl to a temporary file generated by File::Temp::tempfile(). If doing this, beware that when the bisect ends (or you abort it) then your checkout is no longer at blead, so you will need to git checkout blead before restarting, to get the current version of Porting/bisect.pl again. It's often easier either to copy Porting/bisect.pl and Porting/bisect-runner.pl to another directory (e.g. ~/bin, if you have one), or to create a second git repository for running bisect. To create a second local repository, if your working checkout is called perl, a simple solution is to make a local clone, and run from that. i.e.:

    cd ..
    git clone perl perl2
    cd perl2
    ../perl/Porting/bisect.pl ...

By default, bisect-runner.pl will automatically disable the build of DB_File for commits earlier than ccb44e3bf3be2c30, as it's not practical to patch DB_File 1.70 and earlier to build with current Berkeley DB headers. (ccb44e3bf3be2c30 was in September 1999, between 5.005_62 and 5.005_63.) If your db.h is old enough you can override this with -Unoextensions.

OPTIONS ^

syntax highlighting: