sparrowhawk 0.9.5 → 0.9.6

data/README.md

@@ -2,24 +2,103 @@
 
 'The Warbler Killer' is kind of tongue-in-cheek. Sparrowhawk is for teams that would like to distribute their application as a WAR file, but prefer that their distribution tool chain remain purely MRI. That's not to say that Sparrowhawk won't run on JRuby, just that the goal was to produce a tool that would run on any ruby.
 
-## Why Sparrowhawk?
+Documentation is a little sparse at the moment. The test rake_task.feature demonstrates using the rake task. You can review the source and report issues at Github:
+
+* [Source](https://github.com/kofno/Sparrowhawk)
+* [Bug Tracker](https://github.com/kofno/Sparrowhawk/issues)
+* [RDoc](http://rubydoc.info/github/kofno/Sparrowhawk/master/frames)
+
+You can also follow our progress on [Pivotal Tracker](https://www.pivotaltracker.com/projects/164959#)
+
+## Install
+
+Sparrowhawk is distributed as a gem:
+
+    $ gem install sparrowhawk
+
+Or add Sparrowhawk to your Gemfile:
+
+    # Gemfile
+    gem "sparrowhawk"
+
+    #CLI
+    $ bundle install --local
+
+## Usage
+
+### Rake Task
+Sparrowhawk ships with a rake task.
+
+    require 'sparrowhawk/rake_task'
+
+    Sparrowhawk::RakeTask.new
 
-Why would you pick Sparrowhawk over another tool, like, ohhhhh I don't know... Warbler?
+This will create a task named 'war' in your project. If you don't like that name, you can change it:
 
-I can think of two reasons.
+    Sparrowhawk::RakeTask.new :package
 
-First, we run on any ruby (or, we will, by 1.0.0)
+Now you'll have a task named 'package' instead.
 
-The second reason depends on preference. Warbler is a command line tool based on rake. To use warbler, you need to load up all of rake. There are times when this can have negative ramifications.
+Sparrowhawk will try to do the right thing, but it sometimes will need a little coaxing.
 
->TODO: Give examples of negative ramifications
+    Sparrowhawk::RakeTask.new do |t|
+      t.other_files = FileList['README', 'LICENSE', 'CHANGELOG']
+      t.runtimes = 1..5
+    end
 
-Sparrowhawk, on the other hand, is a library for packaging Rack applications as war files. It happens that sparrowhawk ships with a rake task, but rake isn't required to use Sparrowhawk.
+This configuration adds three additional files to the war, and sets the minimum number of runtimes to one, and the maiximum to five.
+
+There are only a few configuration options. They are documented [here](http://rubydoc.info/github/kofno/Sparrowhawk/master/Sparrowhawk/Configuration)
+
+### Programmatic
+
+The rake example above could have been written this way:
+
+    require 'sparrowhawk'
+    
+    task :war do
+      Sparrowhawk::Configuration.new do |c|
+        c.other_files = FileList['README', 'LICENSE', 'CHANGELOG']
+        c.runtimes = 1..5
+      end.war.build
+    end
+
+This produces the exact same outcome. So why bother? The nice thing about the Configuration class is that it is fairly extensible. If, for example, you were using Sparrowhawk, but didn't want to use bundler to manage you gem files. In that case, you might extend the Configuration class and write youe own implementation of the #gem_entities method.
+
+    class MyWarConfig < Sparrowhawk::Configuration
+     
+      def gem_entries
+        # my impl
+        ...
+      end
+    end
+    
+    task :war do
+      MyWarConfig.new.war.build
+    end
+
+## Why Sparrowhawk?
+
+So, why did I build Sparrowhawk?
+
+1. I needed to a reliable way to build a war file on MRI. This means:
+    - Handling symlinks correctly on MRI
+    - Packaging for the JRuby platform, even from MRI
+2. I wanted a simple, programatic way to build war files.
+    - No extra config files
+    - Minimal configuration
+3. Whenever I would update Warbler, something would break
+
+That being said, Warbler is a fine tool, and if your needa aren't similar to mine, there's probably not a good reason to switch.
 
 ## Notes and Warnings
 
-Sparrowhawk was built to package TriSano.
+So far, I've packaged and deployed a large rails (2.3.x) app and a small sinatra app. Rack support is very new, but I would expect to be able to package most rails or rack based applications, provided they are compatible on JRuby. However, the current sample size is small.
+
+Sparrowhawk requires bundler!
+
+For Sparrowhawk to work from MRI, you must package your bundle, and you must bundle install --local from JRuby at least once. This is so bundler can find the java versions of your gems.
 
-Sparrowhawk only does rails applications so far. Full Rack support is forth coming, but wasn't our first priority.
+## Word!
 
-I've only tested Sparrowhawk on Rails 2.3.x applications w/ bundler integration (a niche group, to be certain). It does, however, work beautifully on one such application (TriSano).
+If you're using Sparrowhawk, drop me a line. I'd love to hear about it!

data/lib/sparrowhawk.rb

@@ -1,30 +1,32 @@
 require 'bundler'
 
 module Sparrowhawk
-  VERSION = "0.9.5"
+  VERSION = "0.9.6"
 
-  autoload :War                        ,'sparrowhawk/war'
-  autoload :Configuration              ,'sparrowhawk/configuration'
+  autoload :War                        , 'sparrowhawk/war'
+  autoload :Configuration              , 'sparrowhawk/configuration'
 
-  autoload :Entry                      ,'sparrowhawk/entry'
-  autoload :FileEntry                  ,'sparrowhawk/file_entry'
-  autoload :WebXmlEntry                ,'sparrowhawk/web_xml_entry'
-  autoload :ManifestEntry              ,'sparrowhawk/manifest_entry'
-  autoload :JarEntry                   ,'sparrowhawk/jar_entry'
-  autoload :JRubyCoreJarEntry          ,'sparrowhawk/jruby_core_jar_entry'
-  autoload :JRubyStdLibJarEntry        ,'sparrowhawk/jruby_stdlib_jar_entry'
-  autoload :JRubyRackJarEntry          ,'sparrowhawk/jruby_rack_jar_entry'
-  autoload :GemfileEntry               ,'sparrowhawk/gemfile_entry'
-  autoload :LockfileEntry              ,'sparrowhawk/lockfile_entry'
-  autoload :BundlerConfigurationEntry  ,'sparrowhawk/bundler_configuration_entry'
+  autoload :Entry                      , 'sparrowhawk/entry'
+  autoload :FileEntry                  , 'sparrowhawk/file_entry'
+  autoload :WebXmlEntry                , 'sparrowhawk/web_xml_entry'
+  autoload :RailsWebXmlEntry           , 'sparrowhawk/rails_web_xml_entry'
+  autoload :RackWebXmlEntry            , 'sparrowhawk/rack_web_xml_entry'
+  autoload :ManifestEntry              , 'sparrowhawk/manifest_entry'
+  autoload :JarEntry                   , 'sparrowhawk/jar_entry'
+  autoload :JRubyCoreJarEntry          , 'sparrowhawk/jruby_core_jar_entry'
+  autoload :JRubyStdLibJarEntry        , 'sparrowhawk/jruby_stdlib_jar_entry'
+  autoload :JRubyRackJarEntry          , 'sparrowhawk/jruby_rack_jar_entry'
+  autoload :GemfileEntry               , 'sparrowhawk/gemfile_entry'
+  autoload :LockfileEntry              , 'sparrowhawk/lockfile_entry'
+  autoload :BundlerConfigurationEntry  , 'sparrowhawk/bundler_configuration_entry'
 
-  autoload :FileEntryMapper            ,'sparrowhawk/file_entry_mapper'
-  autoload :PublicDirMapper            ,'sparrowhawk/public_dir_mapper'
-  autoload :ApplicationFilesMapper     ,'sparrowhawk/application_files_mapper'
-  autoload :GemMapper                  ,'sparrowhawk/gem_mapper'
-  autoload :BundlerArtifactMapper      ,'sparrowhawk/bundler_artifact_mapper'
+  autoload :FileEntryMapper            , 'sparrowhawk/file_entry_mapper'
+  autoload :PublicDirMapper            , 'sparrowhawk/public_dir_mapper'
+  autoload :ApplicationFilesMapper     , 'sparrowhawk/application_files_mapper'
+  autoload :GemMapper                  , 'sparrowhawk/gem_mapper'
+  autoload :BundlerArtifactMapper      , 'sparrowhawk/bundler_artifact_mapper'
 
-  autoload :BundlerGemFinder           ,'sparrowhawk/bundler_gem_finder'
-  autoload :BundlerDefinition          ,'sparrowhawk/bundler_definition'
-  autoload :Index                      ,'sparrowhawk/index'
+  autoload :BundlerGemFinder           , 'sparrowhawk/bundler_gem_finder'
+  autoload :BundlerDefinition          , 'sparrowhawk/bundler_definition'
+  autoload :Index                      , 'sparrowhawk/index'
 end

data/lib/sparrowhawk/bundler_artifact_mapper.rb

@@ -16,14 +16,15 @@ module Sparrowhawk
     private
 
     def entries
-      entries = []
-      entries << GemfileEntry.new
-      entries << LockfileEntry.new
-      entries << gems
+      return @entries if @entries
+      @entries = []
+      @entries << GemfileEntry.new
+      @entries << LockfileEntry.new
+      @entries << gems
       unless groups.empty?
-        entries << bundler_configuration
+        @entries << bundler_configuration
       end
-      entries.flatten
+      @entries.flatten
     end
 
     def gems

data/lib/sparrowhawk/configuration.rb

@@ -2,54 +2,103 @@ module Sparrowhawk
 
   class Configuration
 
-    #Sets the name/file path of the war file. Ex: ../distro/example.war
+    # Sets the name/file path of the war file. Ex: ../distro/example.war
     attr_accessor :war_file
 
-    #Sets the base directories that will be scanned for application
-    #files (not static content). Some directories will always be
-    #excluded implicitly (e.g. vendor/cache)
+    # Sets the base directories that will be scanned for application
+    # files (not static content). Some directories will always be
+    # excluded implicitly (e.g. vendor/cache)
     attr_accessor :application_dirs
 
-    #The min and max runtimes that will be used to service
-    #requests. Accepts a range.
+    # The min and max runtimes that will be used to service
+    # rails requests. Accepts a range. Only applies to rails
     attr_accessor :runtimes
 
-    #Which environment to use when running the application
+    # Which environment to use when running the application. Only applies to rails.
     attr_accessor :environment
 
-    #Other files to include in the application code (LICENSE, README, etc.)
+    # Other files to include in the application code (LICENSE, README, etc.)
     attr_accessor :other_files
 
-    #Returns an object instance that can be used to build a war
+    # Set the rack config file. Defaults to 'config.ru'
+    attr_accessor :rack_config
+
+    # Returns an object instance that can be used to build a war
     def war
       war = War.new war_file
-      war.entries << PublicDirMapper.new.to_a
-      war.entries << WebXmlEntry.new(web_xml_options)
-      war.entries << ManifestEntry.new
-      war.entries << ApplicationFilesMapper.new(application_dirs).to_a
-      war.entries << JRubyCoreJarEntry.new
-      war.entries << JRubyStdLibJarEntry.new
-      war.entries << JRubyRackJarEntry.new
-      war.entries << BundlerArtifactMapper.new.to_a
+      war.entries += public_dir_entries
+      war.entries << web_xml_entry
+      war.entries << manifest_entry
+      war.entries += application_file_entries
+      war.entries << jruby_core_jar_entry
+      war.entries << jruby_std_jar_entry
+      war.entries << jruby_rack_jar_entry
+      war.entries += gem_entries
       other_files.each do |file|
-        war.entries << FileEntry.new("WEB-INF/#{file}", file)
+        war.entries << file_entry("WEB-INF/#{file}", file)
       end if other_files
       war
     end
 
     def initialize
+      @rack_config = default_rack_config
       yield self if block_given?
     end
 
+    def rack_app?
+      File.file? File.expand_path(rack_config)
+    end
+
     private
 
-    def web_xml_options
+    def manifest_entry
+      @manifest_entry ||= ManifestEntry.new
+    end
+
+    def public_dir_entries
+      @public_dir_entries ||= PublicDirMapper.new.to_a
+    end
+
+    def application_file_entries
+      @application_file_entries ||= ApplicationFilesMapper.new(application_dirs).to_a
+    end
+
+    def jruby_core_jar_entry
+      @jruby_core_jar_entry ||= JRubyCoreJarEntry.new
+    end
+
+    def jruby_std_jar_entry
+      @jruby_std_jar_entry ||= JRubyCoreJarEntry.new
+    end
+
+    def jruby_rack_jar_entry
+      @jruby_rack_jar_entry ||= JRubyRackJarEntry.new
+    end
+
+    def gem_entries
+      @gem_entries ||= BundlerArtifactMapper.new.to_a
+    end
+
+    def file_entry entry_name, path
+      FileEntry.new entry_name, path
+    end
+
+    def web_xml_entry
+      @web_xml_entry ||= (rack_app? ? 
+        RackWebXmlEntry.new(:rackup => rack_config) :
+        RailsWebXmlEntry.new(rails_web_xml_options))
+    end
+
+    def rails_web_xml_options
       options = {}
       options[:runtimes] = runtimes if runtimes
       options[:environment] = environment if environment
       options
     end
 
+    def default_rack_config
+      './config.ru'
+    end
   end
 
 end

data/lib/sparrowhawk/rack_web_xml_entry.rb

@@ -0,0 +1,25 @@
+module Sparrowhawk
+  class RackWebXmlEntry < WebXmlEntry
+    def initialize options={}
+      super
+      @rackup_file = options[:rackup]
+    end
+
+    def content
+      web_app do |xml|
+        xml << public_root
+        xml << context_param('rackup', rackup) if rackup?
+        xml << rack_filter
+        xml << listener('org.jruby.rack.RackServletContextListener')
+      end.target!
+    end
+
+    def rackup
+      @rackup ||= IO.read(@rackup_file)
+    end
+
+    def rackup?
+      @rackup_file && File.exists?(@rackup_file)
+    end
+  end
+end

data/lib/sparrowhawk/rails_web_xml_entry.rb

@@ -0,0 +1,33 @@
+module Sparrowhawk
+
+  class RailsWebXmlEntry < WebXmlEntry
+    attr_reader :name, :environment
+
+    def initialize options={}
+      super
+      @runtimes = options[:runtimes] || (1..1)
+      @environment = options[:environment] || 'development'
+    end
+
+    def content
+      web_app do |xml|
+        xml << context_param('rails.env', environment)
+        xml << public_root
+        xml << context_param('jruby.min.runtimes', min_runtimes)
+        xml << context_param('jruby.max.runtimes', max_runtimes)
+        xml << rack_filter
+        xml << listener('org.jruby.rack.rails.RailsServletContextListener')
+      end.target!
+    end
+
+    def max_runtimes
+      @runtimes.end.to_s
+    end
+
+    def min_runtimes
+      @runtimes.begin.to_s
+    end
+
+  end
+
+end

data/lib/sparrowhawk/war.rb

@@ -4,7 +4,8 @@ module Sparrowhawk
 
   class War
 
-    attr_reader :name, :entries
+    attr_reader :name
+    attr_accessor :entries
 
     def initialize file_name=nil
       @name = file_name || default_file_name

data/lib/sparrowhawk/web_xml_entry.rb

@@ -1,45 +1,29 @@
 require 'builder'
 
 module Sparrowhawk
-
   class WebXmlEntry
-    attr_reader :name, :environment
+    attr_reader :name
 
-    def initialize options={}
-      @name = 'WEB-INF/web.xml'
-      @runtimes = options[:runtimes] || (1..1)
-      @environment = options[:environment] || 'development'
+    def initialize *args
+      @name = "WEB-INF/web.xml"
     end
 
     def content
+      raise NotImplementedError, "#content should be implemented in a subclass"
+    end
+
+    private
+
+    def web_app
       xml = Builder::XmlMarkup.new
       xml.instruct!
-      xml.declare!(:DOCTYPE, 'web-app'.to_sym, :PUBLIC,
-                   "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN",
-                   "http://java.sun.com/dtd/web-app_2_3.dtd")
+      xml << doctype_declaration
       xml.tag! 'web-app' do |xml|
-        xml << context_param('rails.env', environment)
-        xml << context_param('public.root', '/')
-        xml << context_param('jruby.min.runtimes', min_runtimes)
-        xml << context_param('jruby.max.runtimes', max_runtimes)
-        xml << filter(:name  => 'RackFilter',
-                      :class => 'org.jruby.rack.RackFilter',
-                      :url   => '/*')
-        xml << listener('org.jruby.rack.rails.RailsServletContextListener')
+        yield xml if block_given?
       end
-      xml.target!
-    end
-
-    def max_runtimes
-      @runtimes.end.to_s
-    end
-
-    def min_runtimes
-      @runtimes.begin.to_s
+      xml
     end
 
-    private
-
     def context_param name, value
       xml = Builder::XmlMarkup.new
       xml.tag! 'context-param' do |xml|
@@ -70,6 +54,22 @@ module Sparrowhawk
       xml.target!
     end
 
-  end
+    def public_root
+      context_param('public.root', '/')
+    end
 
+    def doctype_declaration
+      xml = Builder::XmlMarkup.new
+      xml.declare!(:DOCTYPE, 'web-app'.to_sym, :PUBLIC,
+                   "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN",
+                   "http://java.sun.com/dtd/web-app_2_3.dtd")
+      xml.target!
+    end
+
+    def rack_filter
+      filter(:name  => 'RackFilter',
+             :class => 'org.jruby.rack.RackFilter',
+             :url   => '/*')
+    end
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sparrowhawk
 version: !ruby/object:Gem::Version 
-  hash: 49
-  prerelease: false
+  hash: 55
+  prerelease: 
   segments: 
   - 0
   - 9
-  - 5
-  version: 0.9.5
+  - 6
+  version: 0.9.6
 platform: ruby
 authors: 
 - Ryan L. Bell
@@ -15,12 +15,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-31 00:00:00 -05:00
+date: 2011-02-05 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -31,12 +30,12 @@ dependencies:
         - 0
         - 6
         version: 1.0.6
-  type: :runtime
-  version_requirements: *id001
+  requirement: *id001
+  prerelease: false
   name: bundler
+  type: :runtime
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -45,12 +44,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :runtime
-  version_requirements: *id002
+  requirement: *id002
+  prerelease: false
   name: rubyzip
+  type: :runtime
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -59,12 +58,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :runtime
-  version_requirements: *id003
+  requirement: *id003
+  prerelease: false
   name: jruby-jars
+  type: :runtime
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -73,12 +72,26 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :runtime
-  version_requirements: *id004
+  requirement: *id004
+  prerelease: false
   name: jruby-rack
+  type: :runtime
 - !ruby/object:Gem::Dependency 
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id005
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  name: builder
+  type: :runtime
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -87,12 +100,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
-  version_requirements: *id005
+  requirement: *id006
+  prerelease: false
   name: rake
+  type: :development
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -101,12 +114,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
-  version_requirements: *id006
+  requirement: *id007
+  prerelease: false
   name: rspec
+  type: :development
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  version_requirements: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -115,12 +128,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
-  version_requirements: *id007
+  requirement: *id008
+  prerelease: false
   name: cucumber
+  type: :development
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  requirement: &id008 !ruby/object:Gem::Requirement 
+  version_requirements: &id009 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -129,12 +142,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
-  version_requirements: *id008
+  requirement: *id009
+  prerelease: false
   name: aruba
+  type: :development
 - !ruby/object:Gem::Dependency 
-  prerelease: false
-  requirement: &id009 !ruby/object:Gem::Requirement 
+  version_requirements: &id010 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -143,9 +156,10 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  type: :development
-  version_requirements: *id009
+  requirement: *id010
+  prerelease: false
   name: nokogiri
+  type: :development
 description: Sparrowhawk uses bundler and vendor/cache to package rails applications into a war file, without executing Java or JRuby
 email: 
 - ryan.l.bell@gmail.com
@@ -166,6 +180,7 @@ files:
 - lib/sparrowhawk/web_xml_entry.rb
 - lib/sparrowhawk/manifest_entry.rb
 - lib/sparrowhawk/bundler_definition.rb
+- lib/sparrowhawk/rails_web_xml_entry.rb
 - lib/sparrowhawk/jruby_core_jar_entry.rb
 - lib/sparrowhawk/file_entry_mapper.rb
 - lib/sparrowhawk/application_files_mapper.rb
@@ -173,6 +188,7 @@ files:
 - lib/sparrowhawk/configuration.rb
 - lib/sparrowhawk/gemfile_entry.rb
 - lib/sparrowhawk/gem_mapper.rb
+- lib/sparrowhawk/rack_web_xml_entry.rb
 - lib/sparrowhawk/lockfile_entry.rb
 - lib/sparrowhawk/file_entry.rb
 - lib/sparrowhawk/entry.rb
@@ -214,7 +230,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.4.1
 signing_key: 
 specification_version: 3
 summary: An MRI friendly war packaginer for rack applications