JRuby application packaging P-1

Any Info which regards the packaging of JRuby applications is quite scarce, in Java the options are clear and for the most part there is only one option (jar as you might have guessed already), jars aren't designed to carry Ruby code within them, they don't mix with the Ruby ecosystem too well (the interpreter cant run them directly, not without some wrapping) and they force some adjustments (like a Main Java class as an entry point).
Luckily JRuby does support Ruby's packaging system (rubygems) which offers some interesting options, still there are some pitfalls and issues to solve such as:

• The creation/installation/distribution of a JRuby gem.


• Jars and gems mixing (what is the correct mixture?).


• Automation and build integration.

In this post and the following one ill try to introduce some solutions to these issues starting with the basic gem packaging procedure.

A useful tool for dealing with gems is newgem, newgem is a command line utility which generates a skeleton of folders & files, this approach is the easiest way to get going:

 newgem dummy # our dummy project gem  

the resulting dummy folder will contain:

History.txt   Rakefile lib setup.rb 
License.txt   log tasks   website
Manifest.txt  config pkg test
README.txt    doc script  tmp

The lib folder is the destination of our Ruby code, at its post creation state this folder contains an empty folder which carries the application name and a single matching ruby script:

$:.unshift File.dirname(__FILE__)

module AppName

end

This script is the gateway to your application (it includes the first lines of code that will be executed upon gem requiring), in its naked form it only adds the code under the lib/app_name path to the interpreter's load path variable (LOAD_PATH aka $: which is an array), this will enable access to the the rest of the code:

# this loads up the gem
gem 'dummy'
# this will load up lib/dummy.rb and add /lib/dummy to $:
require 'dummy'
# now we may require any other piece of code under dummy
require 'dummy/bla'

Any to be packaged file & folder should have its name appended to the Manifest.txt file.

All that is left in order to package our code into a gem is to invoke:

rake package # The resulting gem will be placed under the pkg folder.
jruby -S gem pkg/app_name_version.gem # this will install it into the JRuby environment 

Another nice feature that newgem offers is the ability to create a binary command (like rake, rails) which is integrated into the Ruby environment along side the gem installation:

ruby script/generate executable dummy # run this under the generated folder path

This will generate a bin folder which contains a single file, all that is left is to append the desired functionality at the bottom of this file and add it to the Manifest.txt.

Summary:
In this post wev'e taken a look on basic gem creation, on the next one ill explain how to inject jar's into our gem and take a look on some automated newgem manipulation with buildr & rake.