Skip to content

Commit

Permalink
Merge pull request #138 from kares/readme
Browse files Browse the repository at this point in the history 
README review
  • Loading branch information
@guilleiguaran
guilleiguaran committed Feb 4, 2013
2 parents 9eb1f90 + c1c6950 commit 387bfc4
Showing 1 changed file with 95 additions and 104 deletions.
199 changes: 95 additions & 104 deletions README.rdoc
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
= Warbler {<img src="https://travis-ci.org/jruby/warbler.png" />}[https://travis-ci.org/jruby/warbler]

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 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.
Expand All @@ -14,7 +13,8 @@ Ruby applications to assemble and Just Work.

2. Run warbler in the top directory of your application: <tt>warble</tt>.

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

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

Expand All @@ -26,22 +26,24 @@ 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 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 <tt>warble</tt> 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:
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

Expand All @@ -53,83 +55,81 @@ or configure them in <tt>config/warble.rb</tt> to always be used.

config.features = %w(FEATURE)

Currently, three features are available.
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.)
* +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 <tt>java -jar myapp.war</tt>.
* +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.
<tt>java -jar myrailsapp.war -S rake db:migrate</tt>.
* +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 <tt>java -jar myapp.war</tt>.
(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:

require __FILE__.sub(/\.rb$/, '.class')
* +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 : <tt>load __FILE__.sub(/\.rb$/, '.class')</tt>

Features may form the basis for a third-party plugin system in the
future if there is demand.
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, <tt>warble compiled; warble war</tt> 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
NOTE: Feature tasks must be included in the same command invocation and
inserted before the +war+ task in order to take effect. For example,
<tt>warble compiled; warble war</tt> 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 <tt>config/warble.rb</tt>.
or, if it's important that the war always be compiled, use the option above to
put the feature in your <tt>config/warble.rb</tt>.

== War or Jar?

War-based projects are for Rails, Merb, or Rack-based web
applications. They usually contain a <tt>config/environment.rb</tt>
file, a <tt>config/init.rb</tt> file, or a <tt>config.ru</tt> 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.
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 <tt>bin</tt> directory
and Ruby code in the <tt>lib</tt> directory. Warbler packages the
application so that <tt>java -jar myapp.jar</tt> runs the launcher
script.
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 <tt>lib</tt> directory. Warbler packages the application so that
<tt>java -jar myapp.jar</tt> runs the launcher script.

== Jar Files

=== Gem Specification (gemspec) Files

If your project has a <tt>.gemspec</tt> 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 has a <tt>.gemspec</tt> 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 <tt>.gemspec</tt>, Warbler will attempt
to guess the launcher from the contents of the <tt>bin</tt> directory
and use the <tt>lib</tt> directory as the lone require path. All files
in the project will be included in the archive.
If your project do not have a <tt>.gemspec</tt>, Warbler will attempt to guess
the launcher from the contents of the <tt>bin</tt> directory and use the
<tt>lib</tt> directory as the lone require path. All files in the project
will be included in the archive.

=== Bundler

Applications that use Bundler[http://gembundler.com/], 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+.
Applications that use Bundler[http://gembundler.com/], 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 <tt>config.bundle_without</tt> 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.
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

Expand All @@ -138,42 +138,34 @@ found in the +Gemfile+ and will refuse to include it in the archive.
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 <tt>config/warble.rb</tt> (see below).
* 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 (Rails 2.1 - 2.3)
* Multi-thread-safe execution (as introduced in Rails 2.2) is detected and runtime pooling is disabled.

=== Merb applications

Merb applications are detected automatically, and the merb-core gem and its
dependencies are packaged.
* 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.
<tt>ENV['RACK_ENV']</tt> will be set to +production+.
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. <tt>ENV['RACK_ENV']</tt> will be set to +production+.

See {the examples in the jruby-rack project}[http://github.com/jruby/jruby-rack/tree/master/examples/]
of how to configure Warbler to package Camping and Sinatra apps.

=== Configuration auto-detect 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+ to 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 application configuration.
* A more accurate way of detecting a Merb application's gems is
needed. Until then, you will have to specify them in
+config/warble.rb+. See below.
* Is it possible to more generally detect what gems an application
uses? Gem.loaded_specs is available, but the application needs to be
* 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
<tt>Warbler.framework_detection = false</tt> 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?
<tt>Gem.loaded_specs</tt> is available, but the application needs to be
loaded first before its contents are reliable.

== Custom configuration
Expand All @@ -185,17 +177,16 @@ 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.
Finally, edit the +config/warble.rb+ to your taste. The generated 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
+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.
automatically be placed in +WEB-INF/lib+ for placement on the web app's
class-path.

=== Web.xml

Expand All @@ -220,48 +211,48 @@ 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:
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:
If you're using Bundler, you'll want to add Warbler to your +Gemfile+ :

group :development do
gem "warbler"
end

Now you should be able to invoke "rake war" to create your war file.
Now you should be able to invoke <tt>rake war</tt> 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 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
https://github.com/jruby/warbler/issues.

== Source

You can get the Warbler source using Git:
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
https://github.com/jruby/warbler/archive/master.tar.gz
https://github.com/jruby/warbler/tarball/master.

== 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 install" once.
You can develop Warbler with any implementation of Ruby. To write Warbler code
and run specs, you need to have Bundler installed and run <tt>bundle</tt> once.

After that, simply run "rake".
After that, simply run <tt>rake</tt>.

== License

Warbler is provided under the terms of the MIT license.

Warbler (c) 2010-2013 Engine Yard, Inc.
Warbler (c) 2010-2012 Engine Yard, Inc.
Warbler (c) 2007-2009 Sun Microsystems, Inc.

0 comments on commit 387bfc4

Please sign in to comment.