• Stars
    star
    881
  • Rank 51,820 (Top 2 %)
  • Language
    Ruby
  • License
    Other
  • Created over 16 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Warbler chirpily constructs .war files of your Ruby applications.

Warbler <img src=“https://badge.fury.io/rb/warbler.svg” alt=“Gem Version” /> <img src=“https://github.com/jruby/warbler/actions/workflows/ci.yml/badge.svg” alt=“Build Status” />

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 9.2.0.0 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.

Getting Started

  1. Install the gem: gem install warbler.

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

  3. Choose one:

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

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

Usage

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 (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

Type warble to create the jar or war file.

Features

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 jrubyc to 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 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 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:

  • executables

  • require_paths

  • runtime dependencies added with add_dependency

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.

Bundler

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 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.

JBundler (experimental)

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.

War Files

Rails applications

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

  • Your application runs in the production environment by default. Change it in config/warble.rb (see below).

  • 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 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 production.

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

Configuration Notes

  • Warbler will load the environment Rake 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 = false at 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_specs is available, but the application needs to be loaded first before its contents are reliable.

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 file is fully-documented with the available options and default values.

Archive 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 class-path.

web.xml

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'
Warbler::Task.new

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

group :development do
  gem "warbler", :require => false
end

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

Troubleshooting

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.

Source

You can get the Warbler source using Git, in any of the following ways:

git clone git://github.com/jruby/warbler.git

You can also download a tarball of Warbler source at github.com/jruby/warbler/archive/master.zip.

Development

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 once.

After that, simply run rake.

Integration Tests

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
mvn verify

You’ll need to have Maven >= 3.1.1 installed, of course: maven.apache.org/

License

Warbler is provided under the terms of the MIT license.

Warbler © 2013-2018 The JRuby Team

Warbler © 2010-2012 Engine Yard, Inc.

Warbler © 2007-2009 Sun Microsystems, Inc.

More Repositories

1

jruby

JRuby, an implementation of Ruby on the JVM
Ruby
3,776
star
2

activerecord-jdbc-adapter

JRuby's ActiveRecord adapter using JDBC.
Ruby
462
star
3

jruby-rack

Rack for JRuby and Java appservers
Ruby
397
star
4

joni

Java port of Oniguruma regexp library
Java
166
star
5

jrubyfx

JavaFX JRuby binding
Ruby
144
star
6

jruby-maven-plugins

maven plugin to handle rubygems in a maven way. including support for rspec, rails, cucumber, rake, etc
Java
112
star
7

jruby-lint

See how ready your Ruby code is to run on JRuby
Ruby
101
star
8

heroku-buildpack-jruby

Shell
63
star
9

jruby-ossl

DEFUNCT, new repository at:
47
star
10

jruby-openssl

JRuby's OpenSSL gem
Java
45
star
11

jruby-parser

JRuby's parser customized for IDE usage
Java
44
star
12

maven_gem

A RubyGems plugin (and a utility) to install Maven artifacts as RubyGems
Ruby
40
star
13

perfer

Ruby
31
star
14

image_voodoo

ImageScience-compatible image processing for JRuby
Ruby
26
star
15

jruby-launcher

JRuby's native launcher executable
C++
24
star
16

jcodings

Java-based codings helper classes for Joni and JRuby
Java
20
star
17

using_jruby

Code samples from the "Using JRuby" book
Ruby
19
star
18

java_inline

JVM language support for RubyInline
Ruby
19
star
19

docker-jruby

Dockerfile
18
star
20

jruby-debug

JRuby-based backend for ruby-debug
Java
15
star
21

jruby-rails-templates

App templates for JRuby on Rails applications
Ruby
14
star
22

maven-tools

ruby helpers for maven related tasks
Ruby
14
star
23

jruby-mains

a couple of main methods for embedded (j)ruby inside a jar/war file
Ruby
10
star
24

jruby-ldap

JRuby/LDAP is a native LDAP implementation that uses JNDI to implement a Ruby/LDAP compatible API.
Ruby
10
star
25

bytelist

DEPRECATED: JRuby no longer maintains org.jruby.util.ByteList as a separate library
Java
10
star
26

rubygems-servlets

webapp which hosts rubygems or a proxy to rubygems. delivers gem maven artifacts as well
Java
9
star
27

jruby-demos

Demos for JRuby presentations at conferences
Ruby
8
star
28

jruby-dashboard

A Dashing dashboard for JRuby applications.
JavaScript
8
star
29

rubybench

Ruby
7
star
30

jrubyhub

Rails 3 + JRuby open source application
Ruby
7
star
31

blog.jruby.org

This is the site and data for blog.jruby.org
CSS
7
star
32

jruby-cext

The MRI C extension subsystem for JRuby
C++
7
star
33

collateral

Public collateral for JRuby
6
star
34

jruby-examples

A collection of examples to help you get the most out of JRuby
Java
5
star
35

jruby-workshop

Course material for JRuby workshop at RubyConf AU 2013
Ruby
4
star
36

jruby-startup

A collection of utilities to help improve JRuby startup time
Ruby
4
star
37

jruby-cdc

A stripped-down version of JRuby that runs on Java ME's CDC profile
Ruby
4
star
38

jruby-graal

Java
4
star
39

jruby-visualizer

Visualize JRuby's runtime in action
Ruby
4
star
40

jrubyconf.com

JRubyConf web sites and collateral
JavaScript
3
star
41

mavengem

Mavengem protocol and mavengem wagon
Ruby
3
star
42

jay

Jay grammar/parser tool
C
2
star
43

jruby-mac-installer

Ruby
2
star
44

dbm

DBM extension for JRuby
Java
2
star
45

jruby-prism

Java parts of integrating the Prism parser into JRuby. Plugs in using an SPI
Java
2
star
46

jruby-async-profiler

A Ruby gem for JRuby that installs the JVM async-profiler extension
Ruby
1
star
47

ruby-maven

Ruby
1
star
48

jzlib

JRuby's fork of the jzlib pure-Java zlib library
Java
1
star
49

gitosis-admin

Gitosis setup for jruby.org
1
star
50

jbang-catalog

Catalog for jbang command line launcher
1
star
51

jruby-readline

JRuby's `readline` library
Java
1
star