Dale Wijnand edited this page Jan 6, 2017 · 12 revisions
Clone this wiki locally

Welcome to the Migration Manager User Documentation

What is the Migration Manager

The Migration Manager (MiMa in short) can report binary modifications that may lead the JVM throwing a java.lang.LinkageError (or one of its subtypes, like AbstractMethodError) at runtime. Linkage errors are usually the consequence of modifications in classes/members signature.

MiMa compares all classfiles of two released libraries and reports all source of incompatibilities that may lead to a linkage error. MiMa provides you, the library maintainer, with a tool that can greatly automates and simplifies the process of ensuring the release-to-release binary compatibility of your libraries.

A key aspect of MiMa to be aware of is that it only looks for syntactic binary incompatibilities. The semantic binary incompatibilities (such as adding or removing a method invocation) are not considered. This is a pragmatic approach as it is up to you, the library maintainer, to make sure that no semantic changes have occurred between two binary compatible releases. If a semantic change occurred, then you should make sure to provide this information as part of the new release's change list.

In addition, it is worth mentioning that binary compatibility does not imply source compatibility, i.e., some of the changes that are considered compatible at the bytecode level may still break a codebase that depends on it. Interestingly, this is not an issue intrinsic to the Scala language. In the Java language binary compatibility does not imply source compatibility as well. MiMa focuses on binary compatibility and currently provides no insight into source compatibility.

The current version of MiMa provides an aggressive reporting module for finding all potential binary incompatibilties.


You can download the Migration Manager here. Two different packages are available so that you can pick the one that suits your platform. Your options are:

This guide assumes that you have Java 1.6 or later installed on you machine and java on your PATH.

You need to make sure that $JAVA_HOME environment variable is set to the root of the Java distribution. You also need to make sure that the $JAVA_HOME/bin is on your PATH.

$ export JAVA_HOME=..root of java distribution..
$ export PATH=$PATH:$JAVA_HOME/bin

You can test your installation by invoking Java.

$ java -version
java version "1.6.0_24"
Java(TM) SE Runtime Environment (build 1.6.0_24-b07-334-10M3326)
Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02-334, mixed mode)