Skip to content
Newer
Older
100644 179 lines (110 sloc) 7.07 KB
d59b9d3 Added README file
Iulian Dragos authored
1 Migration Manager for Scala
2 ==============
3
789ed59 @dotta Updated README
dotta authored
4 A tool for diagnosing and fixing migration problems for Scala libraries
5 =======================================================================
6
299a376 @jsuereth One last readme fix.
jsuereth authored
7 The Migration Manager for Scala (MiMa in short) is a tool for diagnosing binary incompatibilities for Scala libraries.
9871813 updated README
Mirco authored
8
f05536b @dotta updated link to issue tracker in README
dotta authored
9 Please, use the [mima-user Mailing List][mima-user-ml] for questions and comments.
789ed59 @dotta Updated README
dotta authored
10
9871813 updated README
Mirco authored
11 MiMa's Modules
12 -------
13
29f22de @jsuereth Minor cleanup
jsuereth authored
14 MiMa is split into Several modules:
9871813 updated README
Mirco authored
15
6880d2b @jsuereth removed migrator references.
jsuereth authored
16 - Core: Classes that are used for detection.
17 - Core-UI: UI Classes that can be re-used between different detectors.
29f22de @jsuereth Minor cleanup
jsuereth authored
18 - Reporter: Raw reporting classes and the command line interface.
19 - Reporter-UI: Swing interface to the reporter.
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
20 - SBT Plugin: The SBT plugin for usage inside SBT builds.
21
22
23 SBT Plugin
24 ----------
25
97445db @jsuereth Bumped readme for released sbt plugin.
jsuereth authored
26 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
27
28 1. Add the following to your `project/project/build.scala` file:
29
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
30 ```
97445db @jsuereth Bumped readme for released sbt plugin.
jsuereth authored
31 resolvers += Resolver.url("sbt-plugin-releases", new URL("http://scalasbt.artifactoryonline.com/scalasbt/sbt-plugin-releases/"))(Resolver.ivyStylePatterns)
32
a35337f @jsuereth Version 0.1.3 release.
jsuereth authored
33 addSbtPlugin("com.typesafe" % "sbt-mima-plugin" % "0.1.3")
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
34 ```
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
35
36 2. Add the following to your `build.sbt` file:
37
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
38 ```
86098de @jsuereth Missed readme in refactoring.
jsuereth authored
39 import com.typesafe.tools.mima.plugin.MimaPlugin.mimaDefaultSettings
40 import com.typesafe.tools.mima.plugin.MimaKeys.previousArtifact
81965d9 @jsuereth Fixed readme formatting
jsuereth authored
41
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
42 mimaDefaultSettings
81965d9 @jsuereth Fixed readme formatting
jsuereth authored
43
cd58697 @jsuereth Attempt #317 to fix formatting of readme.
jsuereth authored
44 previousArtifact := Some("com.jsuereth" % "scala-arm_2.9.1" % "1.2")
45 ```
46
0442b01 @jsuereth Added usage help for SBT plugin.
jsuereth authored
47
48 But replacing the scala-arm example with your own artifact.
49
97445db @jsuereth Bumped readme for released sbt plugin.
jsuereth authored
50 3. Run `mima-report-binary-issues`. You should see something like the following:
51
52 ```
53 [info] Found 4 potential binary incompatibilities
54 [error] * method rollbackTransactionResource()resource.Resource in object resource.Resource does not have a correspondent in new version
55 [error] * method now()scala.util.continuations.ControlContext in trait resource.ManagedResourceOperations does not have a correspondent in old version
56 [error] * abstract method now()scala.util.continuations.ControlContext in interface resource.ManagedResource does not have a correspondent in old version
57 [error] * method rollbackTransactionResource()resource.Resource in trait resource.MediumPriorityResourceImplicits does not have a correspondent in new version
58 [error] {file:/home/jsuereth/project/personal/scala-arm/}scala-arm/*:mima-report-binary-issues: Binary compatibility check failed!
59 [error] Total time: 15 s, completed May 18, 2012 11:32:29 AM
60 ```
61
9871813 updated README
Mirco authored
62
63 Eclipse
64 -------
65
089b3ba @dotta Updated instructions for using sbteclipse
dotta authored
66 In order to create Eclipse metadata files (i.e., .classpath and .project) we recomend to use [sbteclipse][sbteclipse].
67
68 Setting up [sbteclipse][sbteclipse] is a simple three-steps process:
69
70 * Create a ``eclipse.sbt`` file under the ``project`` folder and add the [sbteclipse][sbteclipse] plugin.
71 At the time of this writing, my ``project/eclipse.sbt`` contains the following:
72
73 ``addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "2.1.0-RC1")``
74
75 * Create a ``eclipse.sbt`` file under the ``core`` folder and add:
76
77 ``EclipseKeys.createSrc := EclipseCreateSrc.Default + EclipseCreateSrc.Managed``
78
79 This will make sure to add ``src_managed`` to the project's build-path in Eclipse
80 (the ``src_managed`` folder is created by Sbt during the ``source-generators`` phase).
81
82 * 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
83
d59b9d3 Added README file
Iulian Dragos authored
84
250f358 @dotta Updated README with sbteclipse information.
dotta authored
85 [sbteclipse]: https://github.com/typesafehub/sbteclipse/
86
d59b9d3 Added README file
Iulian Dragos authored
87 Build
88 -------
89
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
90 Using [the xsbt tool][xsbt].
b03f83b Added README file
Iulian Dragos authored
91
9871813 updated README
Mirco authored
92 $ xsbt clean update compile
b03f83b Added README file
Iulian Dragos authored
93
94
8e062ce @jsuereth Bumped required sbt version.
jsuereth authored
95 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
96
8e062ce @jsuereth Bumped required sbt version.
jsuereth authored
97 [xsbt]: https://github.com/harrah/xsbt/tree/v0.11.3
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
98
9871813 updated README
Mirco authored
99 This will recompile all MiMa's modules.
35fb00b update README with Launch section
Mirco authored
100
8304f82 @jsuereth Fixed publishing settings for maven-central. Added some more readme d…
jsuereth authored
101 If you'd like to create distributable jar files run:
102
103 $ xsbt assembly
104
105 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.
106
9871813 updated README
Mirco authored
107
29f22de @jsuereth Minor cleanup
jsuereth authored
108 Launch MiMa Reporter UI
35fb00b update README with Launch section
Mirco authored
109 -------
9871813 updated README
Mirco authored
110 Type the following command to run the MiMa Reporter
35fb00b update README with Launch section
Mirco authored
111
29f22de @jsuereth Minor cleanup
jsuereth authored
112 $ xsbt reporter-ui/run
d59b9d3 Added README file
Iulian Dragos authored
113
29f22de @jsuereth Minor cleanup
jsuereth authored
114 Launch MiMa Reporter CLI
9871813 updated README
Mirco authored
115 -------
29f22de @jsuereth Minor cleanup
jsuereth authored
116 Type the following command to run the MiMa Reporter command-line
c9981b7 updated README with FAQ section
Mirco authored
117
29f22de @jsuereth Minor cleanup
jsuereth authored
118 $ xsbt reporter/run
9871813 updated README
Mirco authored
119
120 MiMa Reporter: Functional Tests
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
121 -------
122
9871813 updated README
Mirco authored
123 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
124
29f22de @jsuereth Minor cleanup
jsuereth authored
125 $ xsbt test-functional
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
126
9871813 updated README
Mirco authored
127 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
128
05034d0 Updated Readme
Mirco authored
129 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
130
131 functional-tests
132 |
05034d0 Updated Readme
Mirco authored
133 | --> <your-new-test-folder> (folder for your new test)
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
134 |
135 |-----> problems.txt (the expected list of reported errors - 1 line per error)
136 |-----> v1 (folder containing sources @ version 1)
137 |-----> v2 (folder containing sources @ version 2)
138
05034d0 Updated Readme
Mirco authored
139 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
140
250f358 @dotta Updated README with sbteclipse information.
dotta authored
141 Tests within the `functional-tests` folder should always pass.
05034d0 Updated Readme
Mirco authored
142
143 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
144
c9981b7 updated README with FAQ section
Mirco authored
145 FAQ
146 -------
147
9dca535 Cleaned SBT Build file. Moved resources
Mirco authored
148 `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
149
f24137b Updated README.md. Created new functional-tests. Updated sbt Build.sc…
Mirco authored
150 Bugs and Feature requests
151 -------
d59b9d3 Added README file
Iulian Dragos authored
152
f05536b @dotta updated link to issue tracker in README
dotta authored
153 Use the [GitHub project page][mima-github] for filing new tickets. For questions and comments, please use the [mima-user Mailing List][mima-user-ml].
d59b9d3 Added README file
Iulian Dragos authored
154
f05536b @dotta updated link to issue tracker in README
dotta authored
155 [mima-github]: https://github.com/typesafehub/migration-manager/issues
7d17898 @jsuereth Added a MiMa sbt plugin. Appears to work well.
jsuereth authored
156
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
157
158 Contributing
159 ------------
160 If you'd like to contribute to the MiMa project, please sign the [contributor's licensing agreement](http://www.typesafe.com/contribute/cla).
161
7d17898 @jsuereth Added a MiMa sbt plugin. Appears to work well.
jsuereth authored
162 License
163 -------
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
164 Copyright 2012 Typesafe, Inc.
165
166 Licensed under the Apache License, Version 2.0 (the "License");
167 you may not use this file except in compliance with the License.
168 You may obtain a copy of the License at
169
170 [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
171
bd4753e @jsuereth Adding licensing and CLA information for OSS releasing
jsuereth authored
172 Unless required by applicable law or agreed to in writing, software
173 distributed under the License is distributed on an "AS IS" BASIS,
174 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
175 See the License for the specific language governing permissions and
176 limitations under the License.
f05536b @dotta updated link to issue tracker in README
dotta authored
177
178 [mima-user-ml]: https://groups.google.com/group/migration-manager-user/topics
Something went wrong with that request. Please try again.