From b024cd53019d0277efc067ccb56eae6bc11624db Mon Sep 17 00:00:00 2001 From: Nick Sieger Date: Sun, 7 Nov 2010 01:22:34 -0600 Subject: [PATCH] README.txt: first cut at making the docs generic to both wars and jars --- README.txt | 93 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 67 insertions(+), 26 deletions(-) diff --git a/README.txt b/README.txt index 1e88aa3a..2282b87e 100644 --- a/README.txt +++ b/README.txt @@ -1,18 +1,20 @@ = Warbler -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 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 web applications to assemble and Just Work. +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 Rails application: warble. -3. Deploy your myapp.war file to your favorite Java application server. +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. == Usage @@ -21,23 +23,23 @@ defined tasks. $ warble -T warble compiled # Feature: precompile all Ruby files - warble config # Generate a configuration file to customize your war + 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 jar + 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 .war file + warble war # Create the project war file + warble war:clean # Remove the project war file warble war:debug # Dump diagnostic information -Type warble or warble war to create the war file. +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 war file structure. For +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 (like a jar), without a servlet container: +running on its own, without a servlet container: warble executable war @@ -54,9 +56,11 @@ Currently, three 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 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. @@ -64,15 +68,50 @@ Currently, three features are available. Features may form the basis for a third-party plugin system in the future if there is demand. -== Configuration +== 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: + +* +default_executable+ +* +files+ +* +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[http://gembundler.com/], detected via -presence of a +Gemfile+, will have the gems packaged up into the war -file 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+. +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+. + +== War Files === Rails applications @@ -120,13 +159,7 @@ of how to configure Warbler to package Camping and Sinatra apps. uses? Gem.loaded_specs is available, but the application needs to be loaded first before its contents are reliable. -=== Custom configuration - -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. +== 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 @@ -139,6 +172,14 @@ 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. + === Web.xml Java web applications are configured mainly through this file, and Warbler