Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 147 lines (90 sloc) 5.584 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
24 Although not released, you can still try it out. To do so:
25
26 1. Add the following to your `project/project/build.scala` file:
27
81965d9 @jsuereth Fixed readme formatting
jsuereth authored
28 import sbt._
29 object PluginDef extends Build {
30 override def projects = Seq(root)
31 lazy val root = Project("plugins", file(".")) dependsOn(mima)
32
33 lazy val mima = ProjectRef(file("/path/to/checkedout/mima"), "sbtplugin")
34 }
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
35
36 2. Add the following to your `build.sbt` file:
37
81965d9 @jsuereth Fixed readme formatting
jsuereth authored
38 import ssol.tools.mima.plugin.MimaPlugin.{mimaDefaultSettings, previousArtifact}
39
40 mimaDefaultSettings
41
42 previousArtifact := Some("com.jsuereth" % "scala-arm_2.9.1" % "1.2")
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
43
44 But replacing the scala-arm example with your own artifact.
45
9871813 updated README
Mirco authored
46
47 Eclipse
48 -------
49
250f358 @dotta Updated README with sbteclipse information.
dotta authored
50 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
51
29f22de @jsuereth Minor cleanup
jsuereth authored
52 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
53
d59b9d3 Added README file
Iulian Dragos authored
54
250f358 @dotta Updated README with sbteclipse information.
dotta authored
55 [sbteclipse]: https://github.com/typesafehub/sbteclipse/
56
d59b9d3 Added README file
Iulian Dragos authored
57 Build
58 -------
59
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.scala...
Mirco authored
60 Using [the xsbt tool][xsbt].
b03f83b Added README file
Iulian Dragos authored
61
9871813 updated README
Mirco authored
62 $ xsbt clean update compile
b03f83b Added README file
Iulian Dragos authored
63
64
29f22de @jsuereth Minor cleanup
jsuereth authored
65 Make sure to use tag 0.11.2, installation notes can be found [here][xsbt].
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.scala...
Mirco authored
66
29f22de @jsuereth Minor cleanup
jsuereth authored
67 [xsbt]: https://github.com/harrah/xsbt/tree/v0.11.2
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.scala...
Mirco authored
68
9871813 updated README
Mirco authored
69 This will recompile all MiMa's modules.
35fb00b update README with Launch section
Mirco authored
70
8304f82 @jsuereth Fixed publishing settings for maven-central. Added some more readme doc...
jsuereth authored
71 If you'd like to create distributable jar files run:
72
73 $ xsbt assembly
74
75 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.
76
9871813 updated README
Mirco authored
77
29f22de @jsuereth Minor cleanup
jsuereth authored
78 Launch MiMa Reporter UI
35fb00b update README with Launch section
Mirco authored
79 -------
9871813 updated README
Mirco authored
80 Type the following command to run the MiMa Reporter
35fb00b update README with Launch section
Mirco authored
81
29f22de @jsuereth Minor cleanup
jsuereth authored
82 $ xsbt reporter-ui/run
d59b9d3 Added README file
Iulian Dragos authored
83
29f22de @jsuereth Minor cleanup
jsuereth authored
84 Launch MiMa Reporter CLI
9871813 updated README
Mirco authored
85 -------
29f22de @jsuereth Minor cleanup
jsuereth authored
86 Type the following command to run the MiMa Reporter command-line
c9981b7 updated README with FAQ section
Mirco authored
87
29f22de @jsuereth Minor cleanup
jsuereth authored
88 $ xsbt reporter/run
9871813 updated README
Mirco authored
89
90 MiMa Reporter: Functional Tests
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.scala...
Mirco authored
91 -------
92
9871813 updated README
Mirco authored
93 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.scala...
Mirco authored
94
29f22de @jsuereth Minor cleanup
jsuereth authored
95 $ xsbt test-functional
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.scala...
Mirco authored
96
9871813 updated README
Mirco authored
97 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.scala...
Mirco authored
98
05034d0 Updated Readme
Mirco authored
99 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.scala...
Mirco authored
100
101 functional-tests
102 |
05034d0 Updated Readme
Mirco authored
103 | --> <your-new-test-folder> (folder for your new test)
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.scala...
Mirco authored
104 |
105 |-----> problems.txt (the expected list of reported errors - 1 line per error)
106 |-----> v1 (folder containing sources @ version 1)
107 |-----> v2 (folder containing sources @ version 2)
108
05034d0 Updated Readme
Mirco authored
109 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.scala...
Mirco authored
110
250f358 @dotta Updated README with sbteclipse information.
dotta authored
111 Tests within the `functional-tests` folder should always pass.
05034d0 Updated Readme
Mirco authored
112
113 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.scala...
Mirco authored
114
c9981b7 updated README with FAQ section
Mirco authored
115 FAQ
116 -------
117
9dca535 Cleaned SBT Build file. Moved resources
Mirco authored
118 `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
119
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.scala...
Mirco authored
120 Bugs and Feature requests
121 -------
d59b9d3 Added README file
Iulian Dragos authored
122
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.scala...
Mirco authored
123 Use the [Assembla project page][mima-assembla] for filing new tickets.
d59b9d3 Added README file
Iulian Dragos authored
124
35fb00b update README with Launch section
Mirco authored
125 [mima-assembla]: https://www.assembla.com/spaces/mima/tickets
7d17898 @jsuereth Added a MiMa sbt plugin. Appears to work well.
jsuereth authored
126
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
127
128 Contributing
129 ------------
130 If you'd like to contribute to the MiMa project, please sign the [contributor's licensing agreement](http://www.typesafe.com/contribute/cla).
131
7d17898 @jsuereth Added a MiMa sbt plugin. Appears to work well.
jsuereth authored
132 License
133 -------
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
134 Copyright 2012 Typesafe, Inc.
135
136 Licensed under the Apache License, Version 2.0 (the "License");
137 you may not use this file except in compliance with the License.
138 You may obtain a copy of the License at
139
140 [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
141
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
142 Unless required by applicable law or agreed to in writing, software
143 distributed under the License is distributed on an "AS IS" BASIS,
144 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
145 See the License for the specific language governing permissions and
146 limitations under the License.
Something went wrong with that request. Please try again.