Readme.md in jar-dependencies-0.0.2 vs Readme.md in jar-dependencies-0.0.3
- old
+ new
@@ -1,27 +1,54 @@
# jar-dependencies #
-manage jar dependencies for gems and keep track which jar was already loaded using maven artifact coordinates. it warns on version conflicts and loads only ONE jar assuming the first one is compatible to the second one otherwise your project needs to lock down the right version.
+* [](http://travis-ci.org/mkristian/jar-dependencies)
+* [](https://codeclimate.com/github/mkristian/jar-dependencies)
-via environment variable or system properties the jar loading can be switched of completely, allowing the servlet container or jbundler or any other container to take care of the jar loading.
+add gem dependencies for jar files to ruby gems.
-in case the jars are vendored using the following path convention
+## features ##
-**{group\_id}/{artifact\_id}-{version}.jar**
+ * vendors jar dependencies during installion of the gem
+ * jar dependencies are declared in the gemspec of the gem
+ * jar declaration uses the same notation as jbundler
+ * transitive jar dependencies will be resolved as well using (ruby-)maven
+ * when there are two gems with different versions of the same jar dependency an warning will be given and the first version wins, i.e. **only one** version of the a library inside the jruby-classloader
+ * it hooks into gem, i.e. once the jar-dependency gem is installed the feature can be used by any gem
+ * offer 'bundle-with-jars' command which hooks the jar_installer into rubytems before delegating all arguments to bundler
+ * it integrates with an existing maven local repository and obeys the maven setup in ~/.m2/settings.xml, like mirrors, proxieds, etc
-it will be loaded in case the local maven repository does not have it (maybe the preference should be the other way around ?).
+## some drawbacks ##
-the gem is tiny on purpose since the all gems with jar dependencies should use and funny double loaded jars can be avoided in future. also java project using the jruby ScriptingContainer can manage their jar dependencies including those coming from the gem files.
+ * first you need to install the jar-dependency gem with its development dependencies installed (then ruby-maven gets installed as well)
+ * bundler does not install the jar-dependencies
+ * gems need an extra dependency on jar-dependencies during runtime and for development and installation you need ruby-maven installed as well (which you get via the development dependencies)
-# create a gem with jar dependencies #
+## just look at the example ##
-see add you jar dependency declaration in gemspec via the **requirements**, see [example.gemspec](example/example.gemspec). create an extension **ext/extconf.rb** and use the **setup** from [ruby-maven](http://rubygems.org/gem/ruby-maven) to install the jar dependencies on installation of the gem - see [ext/extconf.rb](example/ext/extconf.rb). this setup will create **{gem.name}\_jars.rb** inside the lib directory (**require_path** of the gemspec) of your gem .
+the [readme.md](example/Readme.md) walks you through an example and shows how development works and shows what happens during installation.
-note: you need ruby-maven-3.1.1.0.3.dev or newer for the GemSetup class
+# configuration #
-your gem just need require this **{gem.name}_jars.rb** in your code whenever you want to load these jars (see [lib/example.rb](example/lib/example.rb)).
-
-the gem itself also needs the **jar-dependencies** gem as runtime-dependency since that is used to load the jar or let [jbundler](http://rubygems.org/gem/jbundler) or similar frameworks deal with the jar dependencies.
+<table border='1'>
+<tr>
+<td>ENV</td><td>java system property</td><td>default</td><td>description</td>
+</tr>
+<tr>
+<td>`JARS_DEBUG`</td><td>jars.debug</td><td>false</td><td>if set to true it will produce lots of debug out (maven -X switch)</td>
+</tr>
+<tr>
+<td>`JARS_VERBOSE`</td><td>jars.verbose</td><td>false</td><td>if set to true it will produce some extra output</td>
+</tr>
+<tr>
+<td>`JARS_HOME`</td><td>jars.home</td><td>$HOME/.m2/repository</td><td>filesystem location where to store the jar files and some metadata</td>
+</tr>
+<tr>
+<td>`JARS_MAVEN_SETTINGS`</td><td>jars.maven.settings</td><td>$HOME/.m2/settings.xml</td><td>setting.xml for maven to use</td>
+</tr>
+<tr>
+<td>`JARS_VENDOR`</td><td>jars.vendor</td><td>true</td><td>set to true means that the jars will be stored in JARS_HOME only</td>
+</tr>
+</table>
# motivation #
just today I tumbled across [https://github.com/arrigonialberto86/ruby-band](https://github.com/arrigonialberto86/ruby-band) which usees jbundler to manage their jar dependencies which happens on the first 'require "ruby-band"'. their is no easy or formal way to find out which jars are added to jruby-classloader.