bisect

Documentation

Overview

Bisect finds changes responsible for causing a failure. A typical use is to identify the source locations in a program that are miscompiled by a given compiler optimization.

Usage:

bisect [flags] [var=value...] command [arguments...]

Bisect operates on a target command line – the target – that can be run with various changes individually enabled or disabled. With none of the changes enabled, the target is known to succeed (exit with exit code zero). With all the changes enabled, the target is known to fail (exit any other way). Bisect repeats the target with different sets of changes enabled, using binary search to find (non-overlapping) minimal change sets that preserve the failure.

The target must cooperate with bisect by accepting a change pattern and then enabling and reporting the changes that match that pattern. The change pattern is passed to the target by substituting it anywhere the string PATTERN appears in the environment values or the command arguments. For each change that matches the pattern, the target must enable that change and also print one or more “match lines” (to standard output or standard error) describing the change. The golang.org/x/tools/internal/bisect package provides functions to help targets implement this protocol. We plan to publish that package in a non-internal location after finalizing its API.

Command Line Flags

Bisect supports the following command-line flags:

-max M

Stop after finding M minimal change sets. The default is no maximum, meaning to run until all changes that provoke a failure have been identified.

-maxset S

Disallow change sets larger than S elements. The default is no maximum.

-timeout D

If the target runs for longer than duration D, stop the target and interpret that as a failure. The default is no timeout.

-count N

Run each trial N times (default 2), checking for consistency.

-v

Print verbose output, showing each run and its match lines.

Example

For example, the Go compiler can be used as a bisect target to determine the source locations that cause a test failure when compiled with a new optimization:

bisect go test -gcflags=all=-d=loopvarhash=PATTERN

The -gcflags=all= instructs the go command to pass the -d=... to the Go compiler when compiling all packages. Bisect replaces the literal text “PATTERN” with a specific pattern on each invocation, varying the patterns to determine the minimal set of changes needed to reproduce the failure.

Defeating Build Caches

Build systems cache build results, to avoid repeating the same compilations over and over. When using a cached build result, the go command (correctly) reprints the cached standard output and standard error associated with that command invocation. (This makes commands like 'go build -gcflags=-S' for printing an assembly listing work reliably.)

Unfortunately, most build systems, including Bazel, are not as careful as the go command about reprinting compiler output. If the compiler is what prints match lines, a build system that suppresses compiler output when using cached compiler results will confuse bisect. To defeat such build caches, bisect replaces the literal text “RANDOM” in environment values and command arguments with a random 64-bit value during each invocation. The Go compiler conveniently accepts a -d=ignore=... debug flag that ignores its argument, so to run the previous example using Bazel, the invocation is:

bazel test --define=gc_goopts=-d=loopvarhash=PATTERN,unused=RANDOM //path/to:test