MiMa (for "Migration Manager") is a tool for identifying binary incompatibilities in Scala libraries.
It's pronounced MEE-ma.
MiMa can report binary modifications that may
cause the JVM to throw 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 automate and simplify 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.
For Scala 3, in addition to binary compatible, TASTy compatibility becomes increasingly important. Another tool, TASTy-MiMa, is designed to automatically check TASTy compatibility in much the same way that MiMa checks binary compatibility.
Keep in mind that TASTy-MiMa is still young, as of early 2023. It is likely to contain bugs.
MiMa's sbt plugin supports sbt 1.x only. (Use v0.3.0 for sbt 0.13.x.)
To use it add the following to your project/plugins.sbt file:
addSbtPlugin("com.typesafe" % "sbt-mima-plugin" % "<version>")
Add the following to your build.sbt file:
mimaPreviousArtifacts := Set("com.example" %% "my-library" % "<version>")
and run mimaReportBinaryIssues to see something like the following:
[info] Found 4 potential binary incompatibilities
[error] * method rollbackTransactionResource()resource.Resource in object resource.Resource does not have a correspondent in new version
[error] * method now()scala.util.continuations.ControlContext in trait resource.ManagedResourceOperations does not have a correspondent in old version
[error] * abstract method now()scala.util.continuations.ControlContext in interface resource.ManagedResource does not have a correspondent in old version
[error] * method rollbackTransactionResource()resource.Resource in trait resource.MediumPriorityResourceImplicits does not have a correspondent in new version
[error] {file:/home/jsuereth/project/personal/scala-arm/}scala-arm/*:mima-report-binary-issues: Binary compatibility check failed!
[error] Total time: 15 s, completed May 18, 2012 11:32:29 AM
A MiMa plugin for Mill is maintained at lolgab/mill-mima.
To use it add the following to your build.sc:
import $ivy.`com.github.lolgab::mill-mima::x.y.z`
import com.github.lolgab.mill.mima._Please check this page for further information.
When MiMa reports a binary incompatibility that you consider acceptable, such as a change in an internal package,
you need to use the mimaBinaryIssueFilters setting to filter it out and get mimaReportBinaryIssues to
pass, like so:
import com.typesafe.tools.mima.core._
mimaBinaryIssueFilters ++= Seq(
ProblemFilters.exclude[MissingClassProblem]("com.example.mylibrary.internal.Foo"),
)You may also use wildcards in the package and/or the top Problem parent type for such situations:
mimaBinaryIssueFilters ++= Seq(
ProblemFilters.exclude[Problem]("com.example.mylibrary.internal.*"),
)Most MiMa checks (DirectMissingMethod, IncompatibleResultType,
IncompatibleMethType, etc) are against the "method descriptor", which
is the "raw" type signature, without any information about generic parameters.
The IncompatibleSignature check compares the Signature, which includes the
full signature including generic parameters. This can catch real
incompatibilities, but also sometimes triggers for a change in generics that
would not in fact cause problems at run time. Notably, it will warn when
updating your project to scala 2.12.9+ or 2.13.1+,
see this issue for details.
You can opt-in to this check by setting:
import com.typesafe.tools.mima.plugin.MimaKeys._
ThisBuild / mimaReportSignatureProblems := trueThe mimaExcludeAnnotations setting can be used to tell MiMa to
ignore classes, objects, and methods that have a particular
annotation. Such an annotation might typically have "experimental" or
"internal" in the name.
The setting is a Seq[String] containing fully qualified annotation
names.
Example:
mimaExcludeAnnotations += "scala.annotation.experimental"Caveat: mimaExcludeAnnotations is only implemented on Scala 3.
From time to time you may need to set mimaPreviousArtifacts according to some conditions. For
instance, if you have already ported your project to Scala 2.13 and set it up for cross-building to Scala 2.13,
but still haven't cut a release, you may want to define mimaPreviousArtifacts according to the Scala version,
with something like:
mimaPreviousArtifacts := {
if (CrossVersion.partialVersion(scalaVersion.value) == Some((2, 13)))
Set.empty
else
Set("com.example" %% "my-library" % "1.2.3")
}or perhaps using some of sbt 1.2's new API:
import sbt.librarymanagement.{ SemanticSelector, VersionNumber }
mimaPreviousArtifacts := {
if (VersionNumber(scalaVersion.value).matchesSemVer(SemanticSelector(">=2.13")))
Set.empty
else
Set("com.example" %% "my-library" % "1.2.3")
}The setting mimaFailOnNoPrevious defaults to true and will make
mimaReportBinaryIssues fail if mimaPreviousArtifacts hasn't been set.
To make mimaReportBinaryIssues not fail you may want to do one of the following:
- set
mimaPreviousArtifactson all the projects that should be checking their binary compatibility - avoid calling
mimaPreviousArtifactswhen binary compatibility checking isn't needed - set
mimaFailOnNoPrevious := falseon specific projects that want to opt-out (alternativelydisablePlugins(MimaPlugin)) - set
ThisBuild / mimaFailOnNoPrevious := false, which disables it build-wide, effectively reverting back to the previous behaviour
To refer to the project name in mimaPreviousArtifacts, use moduleName rather
than name, like
mimaPreviousArtifacts := Set(organization.value %% moduleName.value % "0.1.0")Unlike name, moduleName escapes characters like ., and is the name
actually used by publish and publishLocal to publish your project. It's
also the value your users should use when adding your project to their
dependencies.
![mergify[bot] avatar](https://avatars.githubusercontent.com/in/10562?v=4 "mergify[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent