warbler-1.3.6 Documentation

Warbler is a gem to make a Java jar or war file out of any Ruby, Rails, Merb, 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.

Getting Started

  1. Install the gem: gem install warbler.

  2. Run warbler in the top directory of your application: warble.

3a. For a web project, deploy your myapp.war file to your favorite Java application server.

3b. For a standalone applications, just run it: java -jar myapp.jar.


Warbler’s 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
warble gemjar      # Feature: package gem repository inside a war
warble pluginize   # Install Warbler tasks in your Rails application
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

Type 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:

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, three features are available.

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. Always 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 config/warble.rb.

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.

Jar Files

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:

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 and :test will be excluded by default, unless you specify with config.bundle_without in config/warble.rb.

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.

War Files

Rails applications

Rails applications are detected automatically and configured appropriately. The following items are set up for you:

Merb applications

Merb applications are detected automatically, and the merb-core gem and its dependencies are packaged.

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 will be set to production.

See the examples in the jruby-rack project of how to configure Warbler to package Camping and Sinatra apps.

Configuration auto-detect notes

Custom configuration

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

warble config

Finally, edit the config/warble.rb to your taste. The generated config/warble.rb file is fully-documented with the available options and default values.

War layout

The default configuration puts application files (app, config, lib, log, vendor, 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 classpath.


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.

  1. If you just want a static web.xml file whose contents you manually control, you may unzip the one generated for you in yourapp.war:WEB-INF/web.xml to config/web.xml and modify as needed. It will be copied into subsequent copies of the war file for you.

  2. If you want to inject some dynamic information into the file, copy the WARBLER_HOME/web.xml.erb to 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.customkey values in your config/warble.rb file.

For more information on configuration, see Warbler::Config.

Rakefile integration

If you’d like to control Warbler from your own project’s Rakefile, simply add the following code somewhere in the Rakefile:

require 'warbler'

If you’re using Bundler, you’ll want to add Warbler to your Gemfile:

group :development do
  gem "warbler"

Now you should be able to invoke “rake war” to create your war file.


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 kenai.com/jira/browse/WARBLER.


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
git clone git://kenai.com/warbler~main

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 “bundle install” once.

After that, simply run “rake”.


Warbler is provided under the terms of the MIT license.

Warbler © 2010-2012 Engine Yard, Inc. Warbler © 2007-2009 Sun Microsystems, Inc.





Generated with the Darkfish Rdoc Generator 2.