buildr-gemjar
is an extension for buildr that makes it easy to
package gems and their dependencies into a jar so that JRuby can
detect them on the classpath.
buildr-gemjar
is distributed as a rubygem on
rubygems.org. Install it as you would any other gem:
$ gem install buildr-gemjar
buildr-gemjar
provides a package type called
:gemjar
. Sample use:
# buildfile
require 'buildr-gemjar'
define 'sinatra-gems' do
project.version = '1.1.2'
package(:gemjar).with_gem('sinatra', project.version)
end
When you run buildr package
, the result will be a JAR which contains
sinatra 1.1.2 and all its dependencies.
You can specify multiple gems:
package(:gemjar).
with_gem('activesupport', '2.3.10').
with_gem('facets, '2.4.5')
You can specify additional sources on top of rubygems.org:
package(:gemjar).
add_source('http://myrepo.local/gems').
with_gem('my-orm', '1.0.3')
You can also include a gem for which you have a .gem
package:
package(:gemjar).with_gem(:file => _('snapshot-gem-2.0.7.pre.gem'))
Many gems that are intended for use in JRuby embed one or more JARs containing "native" java code. jruby-openssl is a popular example of this practice. If these jars are embedded as-is into the gemjar, they won't be visible to ruby code.
To resolve this, buildr-gemjar
will unpack any jar found under the
lib directory of any installed gem (including dependent gems) and
include its contents in the gemjar directly. You can control this
behavior for an individual gem with the :unpack_jars
option to
with_gems
. It can be set to one of the following values:
- an array of globs; e.g.,
["lib/shared/**/*.jar"]
. Each glob will be applied at the root of the installed gem's contents and each match will be unpacked into the gemjar. true
. Equivalent to["lib/**/*.jar"]
. This is the default.false
. Do not unpack any jars from this gem.
The default is :unpack_jars => true
. Note that you can only apply
different unpack behavior for gems which are explicitly included via
with_gem
. Any transitively installed gems will have the default
unpack behavior (i.e., unpack every JAR under lib) applied.
It's important that the name of your JAR not be the same as anything
you will require
from it. E.g., in the sample above, if the JAR
were named sinatra.jar
, it would not be possible to require "sinatra"
from it. (This is a general JRuby requirement, not
something that's specific to this tool.)
Embedded JARs will not have any of their metadata (manifests, META-INF service registrations, etc.) preserved if they are unpacked.
buildr-gemjar
is tested with buildr 1.4.11 on Ruby 1.9.3 and JRuby 1.7.2. It's
expected that it will work with any fairly recent version of buildr.
It requires RubyGems 1.5.0 or later. This means that it won't work with JRuby before 1.6.1. Several of the early revisions of JRuby in the 1.6 line had a severe issue installing certain gems; to be safe, use 1.6.5 or later.
It's been tested on OS X and Linux; it may or may not work on Windows.
- Remember requested gems so that rebuilds can automatically happen on configuration changes. (Workaround: build clean.)
- Use bundler to get a coherent list of dependencies across
several gems. (It would already do this, except that bundler
doesn't support sourcing a gem from a
.gem
file, which is a more important feature.) - Improve performance. Currently a new JVM is spun up to do each gem install, which can be slow if there are a lot of gems. However, the install process needs to change the environment for rubygems so I'm not sure this can be avoided.
- Support Windows.
For bugs and feature requests, please use the github issue tracker. For other questions, please use the buildr users mailing list or e-mail me directly.
Copyright 2011, Rhett Sutphin.
buildr-gemjar
was built at NUBIC.