Skip to content
Newer
Older
100644 161 lines (101 sloc) 6.37 KB
d59b9d3 Added README file
Iulian Dragos authored
1 Migration Manager for Scala
2 ==============
3
4 A tool for diagnosing and fixing migration problems for Scala libraries.
19d93fa merged tag v0.1.0 back into master
Mirco authored
5 =======
29f22de @jsuereth Minor cleanup
jsuereth authored
6 The Migration Manager for Scala (MiMa in short) is a tool for diagnosing and fixing binary incompatibilities for Scala libraries. The OSS version includes only
7 features which allow inspecting binary compatibility.
9871813 updated README
Mirco authored
8
9 MiMa's Modules
10 -------
11
29f22de @jsuereth Minor cleanup
jsuereth authored
12 MiMa is split into Several modules:
9871813 updated README
Mirco authored
13
29f22de @jsuereth Minor cleanup
jsuereth authored
14 - Core: Classes that are used for both migrations and reporting.
15 - Core-UI: UI Classes that can be re-used between the migrator and the reporter.
16 - Reporter: Raw reporting classes and the command line interface.
17 - Reporter-UI: Swing interface to the reporter.
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
18 - SBT Plugin: The SBT plugin for usage inside SBT builds.
19
20
21 SBT Plugin
22 ----------
23
97445db @jsuereth Bumped readme for released sbt plugin.
jsuereth authored
24 The SBT Plugin is released for SBT version 0.11.3. To try it, do the following:
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
25
26 1. Add the following to your `project/project/build.scala` file:
27
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
28 ```
97445db @jsuereth Bumped readme for released sbt plugin.
jsuereth authored
29 resolvers += Resolver.url("sbt-plugin-releases", new URL("http://scalasbt.artifactoryonline.com/scalasbt/sbt-plugin-releases/"))(Resolver.ivyStylePatterns)
30
31 addSbtPlugin("com.typesafe" % "sbt-mima-plugin" % "0.1.2")
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
32 ```
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
33
34 2. Add the following to your `build.sbt` file:
35
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
36 ```
97445db @jsuereth Bumped readme for released sbt plugin.
jsuereth authored
37 import ssol.tools.mima.plugin.MimaPlugin.mimaDefaultSettings
38 import ssol.tools.mima.plugin.MimaKeys.previousArtifact
81965d9 @jsuereth Fixed readme formatting
jsuereth authored
39
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
40 mimaDefaultSettings
81965d9 @jsuereth Fixed readme formatting
jsuereth authored
41
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
42 previousArtifact := Some("com.jsuereth" % "scala-arm_2.9.1" % "1.2")
43 ```
44
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
45
46 But replacing the scala-arm example with your own artifact.
47
97445db @jsuereth Bumped readme for released sbt plugin.
jsuereth authored
48 3. Run `mima-report-binary-issues`. You should see something like the following:
49
50 ```
51 [info] Found 4 potential binary incompatibilities
52 [error] * method rollbackTransactionResource()resource.Resource in object resource.Resource does not have a correspondent in new version
53 [error] * method now()scala.util.continuations.ControlContext in trait resource.ManagedResourceOperations does not have a correspondent in old version
54 [error] * abstract method now()scala.util.continuations.ControlContext in interface resource.ManagedResource does not have a correspondent in old version
55 [error] * method rollbackTransactionResource()resource.Resource in trait resource.MediumPriorityResourceImplicits does not have a correspondent in new version
56 [error] {file:/home/jsuereth/project/personal/scala-arm/}scala-arm/*:mima-report-binary-issues: Binary compatibility check failed!
57 [error] Total time: 15 s, completed May 18, 2012 11:32:29 AM
58 ```
59
9871813 updated README
Mirco authored
60
61 Eclipse
62 -------
63
250f358 @dotta Updated README with sbteclipse information.
dotta authored
64 In order to create Eclipse metadata files (i.e., .classpath and .project) we recomend to use [sbteclipse][sbteclipse]. Once done, to set up the three modules in Eclipse just click on `File > Import > General > Exisiting Projects Into Workspace`, and select the MiMa project's root folder, the three modules should be correctly loaded.
9871813 updated README
Mirco authored
65
29f22de @jsuereth Minor cleanup
jsuereth authored
66 In the `reporter-ui` folders you can also find a `*.launch` file configuration, which can be imported in Eclipse and can be used to start the programs.
9871813 updated README
Mirco authored
67
d59b9d3 Added README file
Iulian Dragos authored
68
250f358 @dotta Updated README with sbteclipse information.
dotta authored
69 [sbteclipse]: https://github.com/typesafehub/sbteclipse/
70
d59b9d3 Added README file
Iulian Dragos authored
71 Build
72 -------
73
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
74 Using [the xsbt tool][xsbt].
b03f83b Added README file
Iulian Dragos authored
75
9871813 updated README
Mirco authored
76 $ xsbt clean update compile
b03f83b Added README file
Iulian Dragos authored
77
78
8e062ce @jsuereth Bumped required sbt version.
jsuereth authored
79 Make sure to use tag 0.11.3, installation notes can be found [here][xsbt].
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
80
8e062ce @jsuereth Bumped required sbt version.
jsuereth authored
81 [xsbt]: https://github.com/harrah/xsbt/tree/v0.11.3
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
82
9871813 updated README
Mirco authored
83 This will recompile all MiMa's modules.
35fb00b update README with Launch section
Mirco authored
84
8304f82 @jsuereth Fixed publishing settings for maven-central. Added some more readme d…
jsuereth authored
85 If you'd like to create distributable jar files run:
86
87 $ xsbt assembly
88
89 This will create `reporter/target/mima-reporter-assembly-....jar` and `reporter-ui/target/mima-reporter-ui-assembly-....jar` jar files that can be used to launch the command line and ui version of MiMa.
90
9871813 updated README
Mirco authored
91
29f22de @jsuereth Minor cleanup
jsuereth authored
92 Launch MiMa Reporter UI
35fb00b update README with Launch section
Mirco authored
93 -------
9871813 updated README
Mirco authored
94 Type the following command to run the MiMa Reporter
35fb00b update README with Launch section
Mirco authored
95
29f22de @jsuereth Minor cleanup
jsuereth authored
96 $ xsbt reporter-ui/run
d59b9d3 Added README file
Iulian Dragos authored
97
29f22de @jsuereth Minor cleanup
jsuereth authored
98 Launch MiMa Reporter CLI
9871813 updated README
Mirco authored
99 -------
29f22de @jsuereth Minor cleanup
jsuereth authored
100 Type the following command to run the MiMa Reporter command-line
c9981b7 updated README with FAQ section
Mirco authored
101
29f22de @jsuereth Minor cleanup
jsuereth authored
102 $ xsbt reporter/run
9871813 updated README
Mirco authored
103
104 MiMa Reporter: Functional Tests
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
105 -------
106
9871813 updated README
Mirco authored
107 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
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
108
29f22de @jsuereth Minor cleanup
jsuereth authored
109 $ xsbt test-functional
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
110
9871813 updated README
Mirco authored
111 if one (or more) test fails the build is stop and no jar will not be produced.
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
112
05034d0 Updated Readme
Mirco authored
113 To add a new functional test to the suite, create a new folder within 'functional-tests' directory with the following structure:
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
114
115 functional-tests
116 |
05034d0 Updated Readme
Mirco authored
117 | --> <your-new-test-folder> (folder for your new test)
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
118 |
119 |-----> problems.txt (the expected list of reported errors - 1 line per error)
120 |-----> v1 (folder containing sources @ version 1)
121 |-----> v2 (folder containing sources @ version 2)
122
05034d0 Updated Readme
Mirco authored
123 After doing that, `reload` if you are in a `xsbt` console session (if that makes nosense to you, it means you are fine and you can run the test as usual).
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
124
250f358 @dotta Updated README with sbteclipse information.
dotta authored
125 Tests within the `functional-tests` folder should always pass.
05034d0 Updated Readme
Mirco authored
126
127 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).
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
128
c9981b7 updated README with FAQ section
Mirco authored
129 FAQ
130 -------
131
9dca535 Cleaned SBT Build file. Moved resources
Mirco authored
132 `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.
c9981b7 updated README with FAQ section
Mirco authored
133
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
134 Bugs and Feature requests
135 -------
d59b9d3 Added README file
Iulian Dragos authored
136
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
137 Use the [Assembla project page][mima-assembla] for filing new tickets.
d59b9d3 Added README file
Iulian Dragos authored
138
35fb00b update README with Launch section
Mirco authored
139 [mima-assembla]: https://www.assembla.com/spaces/mima/tickets
7d17898 @jsuereth Added a MiMa sbt plugin. Appears to work well.
jsuereth authored
140
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
141
142 Contributing
143 ------------
144 If you'd like to contribute to the MiMa project, please sign the [contributor's licensing agreement](http://www.typesafe.com/contribute/cla).
145
7d17898 @jsuereth Added a MiMa sbt plugin. Appears to work well.
jsuereth authored
146 License
147 -------
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
148 Copyright 2012 Typesafe, Inc.
149
150 Licensed under the Apache License, Version 2.0 (the "License");
151 you may not use this file except in compliance with the License.
152 You may obtain a copy of the License at
153
154 [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
7d17898 @jsuereth Added a MiMa sbt plugin. Appears to work well.
jsuereth authored
155
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
156 Unless required by applicable law or agreed to in writing, software
157 distributed under the License is distributed on an "AS IS" BASIS,
158 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
159 See the License for the specific language governing permissions and
160 limitations under the License.
Something went wrong with that request. Please try again.