Skip to content
Browse files

Merge pull request #138 from kares/readme

README review
  • Loading branch information...
2 parents 9eb1f90 + c1c6950 commit 387bfc4eed65c6cba5919a6e07e50a2a6d0125a8 @guilleiguaran guilleiguaran committed
Showing with 95 additions and 104 deletions.
  1. +95 −104 README.rdoc
View
199 README.rdoc
@@ -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.
@@ -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>.
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
Something went wrong with that request. Please try again.