-
Notifications
You must be signed in to change notification settings - Fork 71
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #213 from SethTisue/merge-in-wiki
merge wiki contents into README.md and CONTRIBUTING.md
- Loading branch information
Showing
2 changed files
with
179 additions
and
76 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,97 +1,94 @@ | ||
Migration Manager for Scala | ||
=========================== | ||
# Migration Manager for Scala | ||
|
||
The Migration Manager for Scala (MiMa in short) is a tool for diagnosing binary incompatibilities for Scala libraries. | ||
The Migration Manager for Scala (MiMa in short) is a tool for | ||
diagnosing binary incompatibilities for Scala libraries. | ||
|
||
If you don't know how to use MiMa, please [read the user documentation](https://github.com/lightbend/migration-manager/wiki). | ||
## What it is | ||
|
||
MiMa's Modules | ||
-------------- | ||
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 is split into Several modules: | ||
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. | ||
|
||
- Core: classes that are used for detection. | ||
- Reporter: reporting classes. | ||
- SBT Plugin: the sbt plugin for usage inside sbt builds. | ||
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. | ||
|
||
Usage | ||
----- | ||
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. | ||
|
||
To use MiMa as an sbt plugin, see the [sbt plugin wiki page](https://github.com/lightbend/migration-manager/wiki/Sbt-plugin). | ||
The current version of MiMa provides an aggressive reporting module for finding | ||
all potential binary incompatibilties. | ||
|
||
## Usage | ||
|
||
Build | ||
----- | ||
The sbt plugin is released for sbt versions 0.13.x and 1.x. To try it, do the following: | ||
|
||
Using [sbt][sbt]: | ||
Add the following to your `project/plugins.sbt` file: | ||
|
||
$ sbt compile | ||
``` | ||
addSbtPlugin("com.typesafe" % "sbt-mima-plugin" % "0.2.0") | ||
``` | ||
|
||
[sbt]: http://www.scala-sbt.org/ | ||
Add the following to your `build.sbt` file: | ||
|
||
This will recompile all MiMa's modules. | ||
``` | ||
mimaPreviousArtifacts := Set("com.jsuereth" % "scala-arm_2.9.1" % "1.2") // replace with your old artifact id | ||
``` | ||
|
||
If you'd like to create distributable jar files for the CLI, run: | ||
Run `mimaReportBinaryIssues`. You should see something like the following: | ||
|
||
$ sbt assembly | ||
``` | ||
[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 | ||
``` | ||
|
||
This will create `reporter/target/mima-reporter-assembly-....jar` jar file that can be used to launch the command line version of MiMa. | ||
## Advanced Usage (Filtering Binary Incompatibilities) | ||
|
||
Sometimes you may want to filter out some binary incompatibility. For instance, because you warn your users to never use a class or method marked with a particular annotation (e.g., [`@experimental`](https://github.com/lightbend/migration-manager/issues/160) - note, this annotation is **not** part of the Scala standard library), you may want to exclude all classes/methods that use such annotation. In MiMa you can do this by _explicitly list each binary incompatibility_ that you want to ignore (unfortunately, it doesn't yet support annotation-based filtering - PR is welcomed! :)). | ||
|
||
MiMa Reporter: Functional Tests | ||
------------------------------- | ||
Open your `build.sbt` file, and | ||
|
||
The directory containing the MiMa Reporter module ('reporter') there is a 'functional-tests' folder that contains several functional tests exercising the system. All tests are executed as part of the build, therefore when running | ||
1. List the binary incompatibilities you would like to ignore | ||
|
||
$ sbt testFunctional | ||
``` | ||
val ignoredABIProblems = { | ||
import com.typesafe.tools.mima.core._ | ||
import com.typesafe.tools.mima.core.ProblemFilters._ | ||
Seq( | ||
exclude[MissingClassProblem]("akka.dispatch.SharingMailbox"), | ||
exclude[IncompatibleMethTypeProblem]("akka.dispatch.DefaultPromise.<<") | ||
) | ||
} | ||
``` | ||
|
||
if one (or more) test fails the build is stop and no jar will not be produced. | ||
2. Configure MiMa to include the defined binary incompatibility ignores | ||
|
||
To add a new functional test to the suite, create a new folder within 'functional-tests' directory with the following structure: | ||
``` | ||
mimaPreviousArtifacts := Set("com.jsuereth" % "scala-arm_2.9.1" % "1.2") // replace with your old artifact id | ||
mimaBinaryIssueFilters ++= ignoredABIProblems | ||
``` | ||
|
||
functional-tests | ||
| | ||
| --> <your-new-test-folder> (folder for your new test) | ||
| | ||
|-----> problems.txt (the expected list of reported errors - 1 line per error) | ||
|-----> v1 (folder containing sources @ version 1) | ||
|-----> v2 (folder containing sources @ version 2) | ||
|
||
After doing that, `reload` if you are in a `sbt` console session (if that makes no sense to you, it means you are fine and you can run the test as usual). | ||
|
||
Tests within the `functional-tests` folder should always pass. | ||
|
||
Note: The `problems.txt` is the test oracle. Expected errors are declared using the MiMa's reporting output (i.e., the output of the tool and the expected errors should match perfectly). Admittedly, this coupling is an issue since the testing framework is highly coupled with the tool output used to report errors to the user. We should improve this and make the two independent. Until then, mind that by changing the output of the tool you will likely have to update some of the test oracles (i.e., problems.txt file). When running tests against Scala 2.12 or higher, `problems-2.12.txt` is preferred over `problems.txt` if the former exists. | ||
|
||
FAQ | ||
--- | ||
## FAQ | ||
|
||
`java.lang.OutOfMemoryError - Java heap space:` If you are experiencing out of memory exception you may need to increase the VM arguments for the initial heap size and the maximum heap size. The default values are `-Xms64m` for for the initial heap size and `-Xmx256m` for the maximum heap size. | ||
|
||
Bugs and Feature requests | ||
------------------------- | ||
|
||
Use the [GitHub project page][mima-github] for filing new tickets. | ||
|
||
[mima-github]: https://github.com/lightbend/migration-manager/issues | ||
|
||
|
||
Contributing | ||
------------ | ||
If you'd like to contribute to the MiMa project, please sign the [contributor's licensing agreement](http://www.lightbend.com/contribute/cla). | ||
|
||
License | ||
------- | ||
Copyright 2012-2018 Lightbend, Inc. | ||
|
||
Licensed under the Apache License, Version 2.0 (the "License"); | ||
you may not use this file except in compliance with the License. | ||
You may obtain a copy of the License at | ||
|
||
[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) | ||
|
||
Unless required by applicable law or agreed to in writing, software | ||
distributed under the License is distributed on an "AS IS" BASIS, | ||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
See the License for the specific language governing permissions and | ||
limitations under the License. |