Warbler is a gem to make a Java jar or war file out of any Ruby, Rails or Rack application. Warbler provides a minimal, flexible, Ruby-like way to bundle up all of your application files for deployment to a Java environment.
Warbler provides a sane set of out-of-the box defaults that should allow most Ruby applications to assemble and Just Work.
Version 2.x of Warbler supports versions of JRuby from 188.8.131.52 and up.
Version 1.4.x of Warbler supports versions of JRuby up to 1.7.x. The 1.x-dev branch is the working code for this.
Install the gem:
gem install warbler.
Run warbler in the top directory of your application:
For a web project, deploy your
myapp.warfile to your favorite Java application server.
For a standalone applications, just run it:
java -jar myapp.jar.
warble command is just a small wrapper around Rake with internally defined tasks.
$ warble -T warble compiled # Feature: precompile all Ruby files warble config # Generate a configuration file to customize your archive warble executable # Feature: make an executable archive (runnable + an emb... warble gemjar # Feature: package gem repository inside a jar warble pluginize # Install Warbler tasks in your Rails application warble runnable # Feature: make a runnable archive (e.g. java -jar rails... warble version # Display version of Warbler warble war # Create the project war file warble war:clean # Remove the project war file warble war:debug # Dump diagnostic information
warble to create the jar or war file.
Warbler “features” are small Rake tasks that run before the creation of the war file and make manipulations to the archive structure. For instance, the
executable feature makes your war file capable of running on its own, without a servlet container (using an embedded web server) :
warble executable war
You can either add features to the warbler command line:
warble FEATURE war
or configure them in
config/warble.rb to always be used.
config.features = %w(FEATURE)
Currently, the following features are available :
gemjar: This bundles all gems into a single gem file to reduce the number of files in the .war. This is mostly useful for Google AppEngine where the number of files per application has a limit. (Note: not applicable for jar-based applications.)
runnable: This makes a (standard Java) runnable .war archive thus you can execute binary bundled (gem) commands e.g. “rake”. You should use the -S switch to specify the binary followed by any arguments in takes e.g.
java -jar myrailsapp.war -S rake db:migrate.
executable: This bundles an embedded web server into the .war so that it can either be deployed into a traditional java web server or run as a standalone application using
java -jar myapp.war. (Note: jar-based applications are executable by default.)
compiled: This uses
jrubycto precompile all .rb files in your application to .class files and includes those in the .war instead of the Ruby sources. NOTE: The war file will still contain .rb files, but they will be short stubs containing the following code :
load __FILE__.sub(/\.rb$/, '.class')
Features may form the basis for a third-party plugin system (in the future) if there is demand.
NOTE: Feature tasks must be included in the same command invocation and inserted before the
war task in order to take effect. For example,
warble compiled; warble war does not compile and obfuscate
.rb sources because the second invocation of
warble does not run the
compiled feature and creates a basic war with the sources included, make sure you run :
warble compiled war
or, if it's important that the war always be compiled, use the option above to put the feature in your
War or Jar?
War-based projects are for Rails, Merb, or Rack-based web applications. They usually contain a
config/environment.rb file, a
config/init.rb file, or a
config.ru file. The presence of these files are used to determine if the project is a web application, and thus a Java EE compatible war file is built for the project.
Jar-based projects are for standalone Ruby applications. Usually a Ruby application has a launcher script in the
bin directory and Ruby code in the
lib directory. Warbler packages the application so that
java -jar myapp.jar runs the launcher script.
Gem Specification (gemspec) Files
If your project has a
.gemspec file in the top directory, it will be used to configure the project's dependencies, launcher script, require paths, and the files to be included in the archive. For best results make sure your gemspec specifies all of the following attributes:
runtime dependencies added with
If your project do not have a
.gemspec, Warbler will attempt to guess the launcher from the contents of the
bin directory and use the
lib directory as the lone require path. All files in the project will be included in the archive.
Applications that use Bundler, detected via presence of a
Gemfile, will have the gems packaged up into the archive along with the Gemfile. The Bundler groups named “:development”, “:test” and “:assets” will be excluded by default, unless you specify with
Warbler supports Bundler for gems and git repositories, but not for plain path components. Warbler will warn when a
:path component is found in the
Gemfile and will refuse to include it in the archive.
Applications that use JBundler, detected via presence of a
Jarfile, will have the jars packaged up into the archive. the JBundler gem is *not* needed for runtime since all jars are already part of the classloader.
Rails applications are detected automatically and configured appropriately. The following items are set up for you:
Your application runs in the
productionenvironment by default. Change it in
The Rails gem is packaged if you haven't vendored Rails (Rails <= 2.x).
Other gems configured in Rails.configuration.gems are packaged (2.1 - 2.3)
Multi-thread-safe execution (as introduced in Rails 2.2) is detected and runtime pooling is disabled.
Other Rack-based applications
If you have a
config.ru file in the top directory or one of the immediate subdirectories of your application, it will be included and used as the rackup script for your Rack-based application. You will probably need to specify framework and application gems in
config/warble.rb unless you're using Bundler to manage your gems.
ENV['RACK_ENV'] will be set to
See the examples in the jruby-rack project of how to configure Warbler to package Camping and Sinatra apps.
Configuration auto-detect notes
Warbler will load the
environmentRake task in a Rails application to try to detect some configuration. If you don't have database access in the environment where you package your application, you may wish to set
Warbler.framework_detection = falseat the top of
config.rb. In this case you may need to specify additional details such as booter, gems and other settings that would normally be gleaned from the app configuration.
Is it possible to more generally detect what gems an application uses?
Gem.loaded_specsis available, but the application needs to be loaded first before its contents are reliable.
If the default settings are not appropriate for your application, you can customize Warbler's behavior. To customize files, libraries, and gems included in the .war file, you'll need a config/warble.rb file. There a two ways of doing this. With the gem, simply run
Finally, edit the
config/warble.rb to your taste. The generated file is fully-documented with the available options and default values.
The default configuration puts application files (
tmp) under the .war file's
WEB-INF directory, and files in
public in the root of the .war file. Any Java .jar files stored in lib will automatically be placed in
WEB-INF/lib for placement on the web app's class-path.
Java web applications are configured mainly through this file, and Warbler creates a suitable default file for you for use. However, if you need to customize it in any way, you have two options.
If you just want a static web.xml file whose contents you manually control, you may unzip the one generated for you in
config/web.xmland modify as needed. It will be copied into subsequent copies of the war file for you.
If you want to inject some dynamic information into the file, copy the
config/web.xml.erb. Its contents will be evaluated for you and put in the webapp. Note that you can also pass arbitrary properties to the ERb template by setting
config.webxml.customkeyvalues in your
For more information on configuration, see Warbler::Config.
If you'd like to control Warbler from your own project's
Rakefile, simply add the following code somewhere in the
require 'warbler' ::.
If you're using Bundler, you'll want to add Warbler to your
group :development do gem "warbler", :require => false end
Now you should be able to invoke
rake war to create your war file.
Ruby 1.8 compatibility
Warbler supports versions of JRuby that support Ruby 1.8, so Warbler itself continues to support Ruby 1.8. However, many gems are choosing to drop 1.8 support; one of these gems is rubyzip(github.com/rubyzip/rubyzip), which Warbler relies on. If you need to use Warbler in a 1.8 environment, you will need to lock the
rubyzip gem to a version before 1.0.0.
If Warbler isn't packaging the files you were expecting, use the
war:debug task to give you more insight into what's going on.
If you think you found a bug, please file one at github.com/jruby/warbler/issues.
You can get the Warbler source using Git, in any of the following ways:
git clone git://git.caldersphere.net/warbler.git git clone git://github.com/jruby/warbler.git
You can also download a tarball of Warbler source at github.com/jruby/warbler/tarball/master.
You can develop Warbler with any implementation of Ruby. To write Warbler code and run specs, you need to have Bundler installed and run
After that, simply run
There are a few integration tests in the `integration` directory that build WAR file with Warbler, and run some basic smoke tests against them. You can run these like so:
cd integration export MAVEN_OPTS="-XX:MaxPermSize=128m" mvn verify
The increased PermGen space is for the Rails4 test. And You'll need to have Maven 3.1.1 installed, of course: maven.apache.org/ Be aware the homebrew installs 3.0.5, which doesn't work (and I don't really know why).
Warbler is provided under the terms of the MIT license.
Warbler © 2013-2015 The JRuby project
Warbler © 2010-2012 Engine Yard, Inc.
Warbler © 2007-2009 Sun Microsystems, Inc.