Abstract

If your local build fails, but you can build the same sources with upstream Maven then you can use xmvn-bisect tool to debug your build.

This command will first build your project in pure local and pure upstream modes and then try different combinations of upstream and local artifacts. It will point to two builds that differ only by one dependency. Normally one of the builds will be successful and the other one failed. Diff between these build logs can be very helpful when debugging build failure.

Requirements

To use xmvn-bisect tool to debug build failure of a project the following conditions must be met (hard requirements):

• the all project dependencies are available in both system repository and some external repository (upstream repository; for example Maven Central),
• project build initiated from local repository fails,
• project build initiated from upstream repository succeeds.

XMvn Bisect can give poor results unless the following conditions are met (soft requirements):

• the build is stable (there is no hazard; random build failures will likely cause false positives and greatly reduce usefulness of the result),
• only one dependency artifact is causing build failure in local mode (if there are multiple reasons of build failure then xmvn-bisect may be able to find one of them, but it can just fail to find any reason at all).

Preparation

Before you start debugging a project with xmvn-bisect it is recommended that you clean local repositories (like $HOME/.m2 and $PWD/.xm2) from any artifacts which are present in the reactor, if possible. This may be impossible if the project being built depends on itself.

It is also recommended to build the project from upstream repository attempting to run xmvn-bisect. This will cause any dependency artifacts to be downloaded and cached in local repository. After this step is complete xmvn-bisect can be ran in offline mode. Doing this should reduce pollution of build logs (otherwise some logs might contain lines informing about artifacts being downloaded) and reduce hazard in general (for example upstream artifact being accidentally used instead of local one).

Running XMvn Bisect

XMvn Bisect supports most of standard Maven command-line options. Run xmvn-bisect -h to see the full list of supported command-line options along with their meanings.

In most cases building project with XMvn Bisect is as simple as using standard Maven command and replacing mvn with xmvn-bisect, for example xmvn-bisect clean compile or xmvn-bisect -o -X -P jdk7 -Dmaven.test.skip=true clean verify.

Analyzing output

Upon successful completion of the command there should be several build logs in current working directory. Name of the logs are prefixed with bisect-. Two builds, usually one failed and one successful, should be pointed to. A command to see the diff between two build logs should also be given. For example:

[INFO] Failed build:     14, see bisect-build-14.log
[INFO] Successful build: 15, see bisect-build-15.log
[INFO] Try:
[INFO]   $ git diff --no-index --color bisect-build-14.log bisect-build-15.log

The diff between two build logs can be examined to look for differences that could cause build failure.

Notes

It is recommended to enable Maven debugging output (option -X) when debugging builds with XMvn Bisect. This doesn't affect XMvn Bisect run itself, but may help investigating the cause of the build failure.

Usually Maven Clean Plugin should be part of the build sequence. XMvn Bisect runs all the builds from the same working directory. Results of previous builds, if not cleaned properly, may interfere with next builds and negatively affect the build. To reduce interference it's usually good to run clean as the first goal.