Path: | README.txt |
Last Update: | Tue Dec 06 08:58:34 +0000 2011 |
Warbler is a gem to make a .war file out of a Rails, Merb, or Rack-based application. The intent is to provide a minimal, flexible, ruby-like way to bundle up all of your application files for deployment to a Java application server.
Warbler provides a sane set of out-of-the box defaults that should allow most Rails applications without external gem dependencies (aside from Rails itself) to assemble and Just Work.
Warbler bundles JRuby and the JRuby-Rack servlet adapter for dispatching requests to your application inside the java application server, and assembles all jar files in WARBLER_HOME/lib/*.jar into your application. No external dependencies are downloaded.
Warbler‘s warble command is just a small wrapper around Rake with internally defined tasks. (Notice "rake" still prints out in the message, but you should substitute "warble" for "rake" on the command line when running this way.)
$ warble -T rake config # Generate a configuration file to customize your war assembly rake pluginize # Unpack warbler as a plugin in your Rails application rake war # Create trunk.war rake war:app # Copy all application files into the .war rake war:clean # Clean up the .war file and the staging area rake war:gems # Unpack all gems into WEB-INF/gems rake war:jar # Run the jar command to create the .war rake war:java_libs # Copy all java libraries into the .war rake war:public # Copy all public HTML files to the root of the .war rake war:webxml # Generate a web.xml file for the webapp
Warbler makes heavy use of Rake‘s file and directory tasks, so only recently updated files will be copied, making repeated assemblies much faster.
Rails applications are detected automatically and configured appropriately. The following items are set up for you:
Merb applications are detected automatically, and the merb-core gem and its dependencies are packaged.
If you have a ‘config.ru’ file in the top directory of your application, its contents will be used as the rackup script for your Rack-based application. You will probably need to specify framework and application gems in config/warble.rb.
See <a href="the">jruby-rack.kenai.com/sources/main/show/examples">the examples in the jruby-rack project</a> of how to configure Warbler to package Camping and Sinatra apps.
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.
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
If you have Warbler installed as a plugin, use the generator:
script/generate warble
Finally, edit the config/warble.rb to your taste. If you install the gem but later decide you‘d like to have it as a plugin, use the pluginize command:
warble pluginize
If you wish to upgrade or switch one or more java libraries from what‘s bundled in the Warbler gem, simply change the jars in WARBLER_HOME/lib, or modify the java_libs attribute of Warbler::Config to include the files you need.
Once Warbler is installed as a plugin, you can use rake to build the war (with the same set of tasks as above).
The generated config/warble.rb file is fully-documented with the available options and default values.
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.
For more information on configuration, see Warbler::Config.
If Warbler isn‘t packaging the files you were expecting, there are several debug tasks available to give you more insight into what‘s going on.
You can get the Warbler source using Git, in any of the following ways:
git clone git://kenai.com/warbler~main git clone git://git.caldersphere.net/warbler.git git clone git://github.com/nicksieger/warbler.git
You can also download a tarball of Warbler source at github.com/nicksieger/warbler/tree/master.
Warbler is provided under the terms of the MIT license.
Warbler (c) 2007-2009 Sun Microsystems, Inc.
Warbler also bundles several other pieces of software for convenience. Please read the file LICENSES.txt to ensure that you agree with the terms of all the components.