sprout 0.5.29 → 0.7.153

data/lib/sprout.rb

@@ -1,278 +1,366 @@
-$:.push(File.dirname(__FILE__))
 require 'rubygems'
-require 'rake/clean'
-require 'rake/tasklib'
-require 'yaml'
-require 'log'
-require 'erb'
-require 'uri'
-require 'fileutils'
-require 'zip/zipfilesystem'
 require 'archive/tar/minitar'
-require 'platform'
+require 'rake'
+require 'rake/clean'
 
-if(Platform::OS == :win32)
-  require 'win32/open3'
-end
+$:.push(File.dirname(__FILE__))
+require 'progress_bar'
+require 'sprout/log'
+require 'sprout/user'
+require 'sprout/zip_util'
+require 'sprout/remote_file_target'
+require 'sprout/remote_file_loader'
+require 'sprout/simple_resolver'
+require 'sprout/template_resolver'
 
-module PatternPark
-  class SproutError < StandardError; end
-  class UsageError < SproutError; end
+require 'rubygems/installer'
+require 'rubygems/source_info_cache'
+require 'rubygems/version'
+require 'rubygems/digest/md5'
 
-  class Sprout
-    attr_accessor :name,
-                  :type,
-                  :render,
-                  :platform,
-                  :base_url,
-                  :dependencies,
-                  :targets,
-                  :config_cache,
-                  :config
+require 'sprout/project_model'
+require 'sprout/builder'
+require 'sprout/version'
+require 'sprout/tasks/tool_task'
+require 'sprout/general_tasks'
+
+module Sprout
+  class SproutError < StandardError #:nodoc:
+  end
 
-    @@base_urls = ['http://projectsprouts.googlecode.com/svn/branches/release/sprouts/',
-                   'http://projectsprouts.googlecode.com/svn/trunk/sprouts/',
-                   'http://www.projectsprouts.org/sprout/']
+  # Sprouts is an open-source, cross-platform project generation and configuration tool
+  # for ActionScript 2, ActionScript 3, Adobe AIR and Flex projects. It is built on top 
+  # of Ruby Gems, Rails Generators and is intended to work on any platform that Ruby runs
+  # on including specifically, Windows XP, Windows Vista, Cygwin, OS X and Linux.
+  #
+  # Sprouts can be separated into some core concepts as follows:
+  #
+  # ----
+  # == Tools
+  # :include: ../doc/Tool
+  #
+  # ----
+  # == Libraries
+  # :include: ../doc/Library
+  # 
+  # ----
+  # == Bundles
+  # :include: ../doc/Bundle
+  #
+  # ----
+  # == Generators
+  # :include: ../doc/Generator
+  #
+  # ----
+  # == Tasks
+  # :include: ../doc/Task
+  #
+  # ----
+  # == Sprout
+  #
+  # Tools, Libraries and Bundles are distributed as RubyGems and given a specific gem name suffix. For some examples:
+  #   sprout-flex2sdk-tool
+  #   sprout-asunit-library
+  #   sprout-as3-bundle
+  #
+  # The Sprout application provides shared functionality for each of the different types of Sprouts.
+  # 
+  # The Sprout command line tool primarily provides access to project generators from any sprout bundle that is available
+  # to your system, either locally or from the network.
+  # 
+  # When executed from the system path, this class will download and install a named bundle, and execute a +project+
+  # generator within that bundle. Following is an example:
+  # 
+  #   sprout -n as3 SomeProject
+  #
+  # The previous command will download and install the latest version of the sprout-as3-bundle gem and initiate the 
+  # project_generator with a single argument of 'SomeProject'. If the string passed to the -n parameter begins with
+  # 'sprout-' it will be unmodified for the lookup. For example:
+  #
+  #   spout -n sprout-as3-bundle SomeProject
+  #
+  # will not have duplicate strings prepended or suffixed.
+  #
+  # ----
+  # Some additional resources or references:
+  #
+  # Rake:
+  # http://rake.rubyforge.org
+  # http://martinfowler.com/articles/rake.html
+  #
+  # RubyGems:
+  # * http://www.rubygems.org
+  # * http://www.linuxjournal.com/article/8967
+  #
+  # Ruby Raven (Mostly Inspiration)
+  # * http://raven.rubyforge.org
+  #
+  class Sprout
     @@default_rakefiles = ['rakefile', 'Rakefile', 'rakefile.rb', 'Rakefile.rb'].freeze
-    @@universal = 'universal'
-    @@update = false
-    @@project_name = ''
-    @@config_cache = nil
-    @@home = nil
-    @@cache = nil
-    @@project_path = nil
-    @@base_url = nil
+
+    @@name      = 'Sprouts'
+    @@cache     = 'cache'
+    @@lib       = 'lib'
+    @@spec      = 'sprout.spec'
+    @@home  = File.expand_path(File.dirname(File.dirname(__FILE__)))
+
+    # Execute a generator that is available locally or from the network.
+    # * +sprout_name+ A full gem name (ex., sprout-as3-bundle) that contains a generator that matches +generator_name+
+    # * +generator_name+ A string like 'project' or 'class' that maps to a generator
+    # * +params+ Arbitrary parameters to pass to the generator
+    # * +project_path+ Optional parameter. Will default to the nearest folder that contains a valid Rakefile.
+    # This Rakefile will usually be loaded by the referenced Generator, and it should have a configured ProjectModel
+    # defined in it.
+    def self.generate(sprout_name, generator_name, params, project_path=nil)
+      Rails::Generator::Base.use_sprout_sources!(sprout_name, project_path)
+      generator = Rails::Generator::Base.instance(generator_name, params)
+      generator.command(:create).invoke!
+    end
     
-    ##
-    # Given a simple string @name, request that sprout
-    # definition from each location in the location list
-    # until it's found
-    #
-    def Sprout.load(name)
-      local = File.join(Sprout.config_cache, name)
-      if(!Sprout.update && File.exists?(local))
-        return Sprout.load_local(local)
-      else
-        @@base_urls.each do |url|
-          begin
-            @@base_url = url
-            loader = RemoteFileLoader.new
-            loader.get_remote_file(url + name, local)
-            sprout = Sprout.load_local(local)
-#            if(sprout.post_install)
-#              eval(sprout.post_install)
-#            end
-            return sprout
-          rescue OpenURI::HTTPError => e
-            Log.puts("[WARNING] Sprout not found at: #{url + name}, trying next location")
-            next
-          end
-          raise SproutError.new("\n[ERROR] Sprout could not find '#{name}' definition at any known locations, please check the sprout name and try again.")
+    # Remove all installed RubyGems that begin with the string 'sprout' and clear the local sprout cache
+    def self.remove_all
+      # Set up sudo prefix if not on win machine
+      # Only show confirmation if there is at least one installed sprout gem
+      confirmation = false
+      count = 0
+      # For each sprout found, remove it!
+      Rails::Generator::GemGeneratorSource.new().each_sprout do |sprout|
+        count += 1
+        command = "#{get_gem_preamble} uninstall -x -a -i -q #{sprout.name}"
+
+        if(!confirmation)
+          break unless confirmation = remove_gems_confirmation
         end
+        raise ">> Exited with errors: #{$?}" unless system(command)
       end
-    end
-    
-    ##
-    # Retrieve and resolve a locally downloaded Sprout
-    def Sprout.load_local(path)
-      data = nil
-      File.open(path, 'r') do |f|
-        data = f.read
+      
+      if(confirmation)
+        puts "All Sprout gems have been successfully uninstalled"
+      elsif(count > 0)
+        puts "Some Sprout gems have been left on the system"
+      else
+        puts "No Sprout gems were found on this system"
       end
-      data = ERB.new(data, nil, '>').result(binding)
-      begin
-        sprout = YAML.load(data)
-      rescue StandardError => e
-        Log.puts("[ERROR] An invalid sprout definition was encountered at: [#{path}] with:\n\n#{data}\n\nPlease try again...")
-        if(File.exists?(path))
-          File.delete(path)
+
+      # Now clear out the cache
+      cache = File.dirname(File.dirname(Sprout.sprout_cache))
+      
+      if(File.exists?(cache))
+        puts "\n[WARNING]\n\nAbout to irrevocably destroy the sprout cache at:\n\n#{cache}\n\n"
+        puts "Are you absolutely sure? [Yn]"
+        response = $stdin.gets.chomp!
+        if(response.downcase.index('y'))
+          FileUtils.rm_rf(cache)
+        else
+          puts "Leaving the Sprout file cache in tact...."
         end
-        raise UsageError.new('Invalid Sprout definiton')
+      else
+        puts "No cached files found on this system"
       end
-      sprout.resolve
-      return sprout
-    end
-    
-    def Sprout.update=(update)
-      @@update = update
+      
+      puts "To completely remove sprouts now, run:"
+      puts "  #{get_gem_preamble} uninstall sprout"
     end
     
-    def Sprout.base_url
-      return @@base_url
+    # Build up the platform-specific preamble required
+    # to call the gem binary from Kernel.execute
+    def self.get_gem_preamble
+      usr = User.new()
+      if(!usr.is_a?(WinUser))
+        # Everyone but Win and Cygwin users get 'sudo '
+        return "sudo gem"
+      elsif(!usr.is_a?(CygwinUser))
+        # We're in the DOS Shell
+        return "ruby #{get_executable_from_path('gem')}"
+      end
+      # We're either a CygwinUser or some other non-sudo supporter
+      return 'gem'
     end
     
-    def Sprout.update
-      return @@update
-    end
-
-    ##
-    # Begin loading and resolving this Sprout instance
-    # and recursively call on dependencies
-    def resolve
-      begin
-        load_target
-        load_dependencies
-      rescue StandardError => e
-        puts "[ERROR] Sprout '#{name}' encountered an error, this may prevent your project from working correctly!"
-        puts e
-        puts e.backtrace
+    # Retrieve the full path to an executable that is
+    # available in the system path
+    def self.get_executable_from_path(exe)
+      path = ENV['PATH']
+      file_path = nil
+      path.split(get_path_delimiter).each do |p|
+        file_path = File.join(p, exe)
+#        file_path = file_path.split("/").join("\\")
+#        file_path = file_path.split("\\").join("/")
+        if(File.exists?(file_path))
+          return User.clean_path(file_path)
+        end
       end
+      return nil
     end
     
-    def execute
-      dependencies.each do |dep|
-        dep.execute
+    def self.get_path_delimiter
+      usr = User.new
+      if(usr.is_a?(WinUser) && !usr.is_a?(CygwinUser))
+        return ';'
+      else
+        return ':'
       end
     end
     
-    def post_install
-      if(target.nil?)
-        return nil
+    def self.remove_gems_confirmation
+      msg =<<EOF 
+About to uninstall all RubyGems that match 'sprout-'....
+Are you sure you want to do this? [Yn]
+EOF
+      puts msg
+      response = $stdin.gets.chomp!
+      if(response.downcase.index('y'))
+        return true
       end
-      return target.post_install
+      return false
     end
 
-    ##
-    # Load the remote file target associated with this sprout instance
-    def load_target
-      target = get_platform_target
-      if(target)
-        # Forward type name so that RemoteFileTargets can place
-        # downloaded files into the appropriate user home folder
-        target.type = type
-        target.resolve
+    # Retrieve the file target to an executable by sprout name. Usually, these are tool sprouts.
+    # * +name+ Full sprout gem name that contains an executable file
+    # * +archive_path+ Optional parameter for tools that contain more than one executable, or for
+    # when you don't want to use the default executable presented by the tool. For example, the Flex 2 SDK
+    # has many executables, when this method is called for them, one might use something like:
+    #   Sprout::Sprout.get_executable('sprout-flex2sdk-tool', 'bin/mxmlc')
+    # * +version+ Optional parameter to specify a particular gem version for this executable
+    def self.get_executable(name, archive_path=nil, version=nil)
+      target = self.sprout(name, version)
+      if(archive_path)
+        # If caller sent in a relative path to an executable (e.g., bin/mxmlc), use it
+        exe = File.join(target.installed_path, archive_path)
+        if(User.new.is_a?(WinUser) && !archive_path.match(/.exe$/))
+          # If we're on Win (even Cygwin), add .exe to support custom binaries (see sprout-flex2sdk-tool)
+          exe << '.exe'
+        end
+      elsif(target.url)
+        # Otherwise, use the default path to an executable if the RemoteFileTarget has a url prop
+        exe = File.join(target.installed_path, target.archive_path)
+      else
+        # Otherwise attempt to run the feature from the system path
+        exe = target.archive_path
       end
+      
+      if(File.exists?(exe) && File.stat(exe).mode != 33261)
+        File.chmod 0755, exe
+      end
+      
+      return exe
     end
 
-    ##
-    # Take the array of string dependency names
-    # load each dependency YAML file, and replace
-    # the array with resolved Sprout instances
-    # Tell each dependency to load it's own
-    # dependencies
-    def load_dependencies(loaded_deps=nil)
-      loaded_deps = (loaded_deps.nil?) ? [name] : loaded_deps # Don't reload deps have already been loaded
-      deps = []
-
-      if(dependencies)
-        dependencies.each do |dep|
-          dep.values.each do |name|
-            if(!loaded_deps.index(name))
-              dep = Sprout.load(name)
-              loaded_deps << name
-              deps << dep
-            end
-          end
-        end
+    # Allows us to easily download and install RubyGem sprouts by name and 
+    # version. 
+    # Returns a RubyGem Gem Spec[http://rubygems.org/read/chapter/20]
+    # when installation is complete. If the installed gem has a Ruby file
+    # configured to 'autorequire', that file will also be required by this
+    # method so that any provided Ruby functionality will be immediately 
+    # available to client scripts. If the installed gem contains a 
+    # 'sprout.spec' file, any RemoteFileTargets will be resolved synchronously
+    # and those files will be available in the Sprout::Sprout.cache.
+    #
+    def self.sprout(name, version=nil)
+      name = sprout_to_gem_name(name)
+      gem_spec = self.find_gem_spec(name, version)
+      sprout_spec_path = File.join(gem_spec.full_gem_path, @@spec)
+      
+      if(gem_spec.autorequire)
+        $:.push(File.join(gem_spec.full_gem_path, 'lib'))
+        require gem_spec.autorequire
+      end
+      if(File.exists?(sprout_spec_path))
+        # Ensure the requisite files get downloaded and unpacked
+        Builder.build(sprout_spec_path, gem_file_cache(gem_spec.name, gem_spec.version))
+      else
+        return gem_spec
       end
-      @dependencies = deps
-    end
-    
-    ##
-    # Insert search locations (Array) 'base paths' for Sprout.load operations
-    def Sprout.insert_locations(locations)
-      @@base_urls = Sprout.clean_locations(locations) + @@base_urls
-    end
-    
-    # TODO: Be smart about added a trailing '/'
-    # Try to ensure that only valid URLs get
-    # added to the list of locations - throw
-    # something informative if needed.
-    def Sprout.clean_locations(locations)
-      return locations
     end
     
-    ##
-    # The system-specific home folder for Sprout application data
-    # e.g., On OS X, /Users/you/Library/Sprouts
-    # e.g., On Win, C:\Documents And Settings\you\Local Settings\Application Data\Sprouts
-    def Sprout.home
-      if(@@home.nil?)
-        @@home = User.new().application_home(:sprouts)
+    # Return sprout-#{name}-bundle for any name that does not begin with 'sprout-'. This was used early on in development
+    # but should possibly be removed as we move forward and try to support arbitrary RubyGems.
+    def self.sprout_to_gem_name(name)
+      if(!name.match(/^sprout-/))
+        name = "sprout-#{name}-bundle"
       end
+      return name
+    end
+
+    # Return the home directory for this Sprout installation
+    def self.home
       return @@home
     end
     
-    ##
-    # The nearest valid project path or current working directory
-    # if no rakefile was found in parent paths
-    def Sprout.project_path(path=nil)
-      if(@@project_path.nil?)
-        path = (path.nil?) ? Dir.pwd : path;
-        path = Sprout.get_project_path(path)
-        if(path.nil?)
-          path = Dir.pwd
-        end
-        @@project_path = path
-      end
-      return @@project_path
+    # Return the location on disk where this installation of Sprouts stores it's cached files.
+    # If the currently installed version of Sprouts were 0.7 and your system username were 'foo'
+    # this would return the following locations:
+    # * +OSX+ /Users/foo/Library/Sprouts/cache/0.7
+    # * +Windows+ C:/Documents And Settings/foo/Local Settings/Application Data/Sprouts/cache/0.7
+    # * +Linux+ ~/.sprouts/cache/0.7
+    def self.sprout_cache
+      home = User.application_home(@@name)
+      return File.join(home, @@cache, "#{VERSION::MAJOR}.#{VERSION::MINOR}")
     end
     
-    def Sprout.project_path=(path)
-      @@project_path = path
+    # Return the +sprout_cache+ combined with the passed in +name+ and +version+ so that you will get
+    # a cache location for a specific gem.
+    def self.gem_file_cache(name, version)
+      return File.join(sprout_cache, "#{name}-#{version}")
     end
     
-    def Sprout.get_project_path(path)
-      if(path.nil? || path == '/' || path.match(/[A-Z]\:\//))
-        return nil
+    # Retrieve the RubyGems gem spec for a particular gem +name+ that meets the provided +requirements+.
+    # +requirements+ are provided as a string value like:
+    #   '>= 0.0.1'
+    # or
+    #   '0.0.1'
+    # This method will actually download and install the provided gem by +name+ and +requirements+ if
+    # it is not found locally on the system.
+    def self.find_gem_spec(name, requirements=nil, recursed=false)
+      specs = Gem::cache.search(/.*#{name}$/)
+      requirement = nil
+      if(requirements)
+        requirement = Gem::Requirement.new(requirements)
       end
-      @@default_rakefiles.each do |file|
-        if(File.exists?(File.join(path, file)))
-          return path
+      specs.each do |spec|
+        if(requirements)
+          if(requirement.satisfied_by?(spec.version))
+            return spec
+          end
+        else
+          return spec
         end
       end
-      return Sprout.get_project_path(File.dirname(path))
-    end
-    
-    ##
-    # Offline storage location for network entities like
-    # Sprout definitions, tasks and archives
-    def Sprout.cache
-      if(@@cache.nil?)
-        @@cache = File.join(Sprout.home, 'cache')
-      end
-      return @@cache
-    end
-    
-    def Sprout.config_cache
-      if(@@config_cache.nil?)
-        @@config_cache = File.join(Sprout.cache, 'sprouts')
+
+      if(recursed)
+        raise SproutError.new("Gem Spec not found for #{name} #{requirements}")
+      else
+        msg = ">> Loading gem [#{name}]"
+        msg << " #{requirements}" if requirements
+        msg << " from #{gem_sources.join(', ')} with it's dependencies"
+        Log.puts msg
+        parts = []
+        parts << "ins"
+        parts << "-r"
+        parts << name
+        # This url should be removed once released, released gems should be hosted from the rubyforge
+        # project, and development gems will be hosted on our domain.
+        parts << "--source #{gem_sources.join(' --source ')}" if(Log.debug || name.index('sprout-'))
+        parts << "-v #{requirements}" unless requirements.nil?
+
+        self.load_gem(parts.join(" "))
+        Gem::cache.refresh!
+        return find_gem_spec(name, requirements, true)
       end
-      return @@config_cache
     end
     
-    ##
-    # List of potential rakefile names for project_path searching
-    def Sprout.default_rakefiles
-      return @@default_rakefiles
+    def self.load_gem(args)
+      # This must use a 'system' call because RubyGems
+      # sends an 'exit'?
+      system("#{get_gem_preamble} #{args}")
     end
     
-    def Sprout.rakefile
-      @@default_rakefiles.each do |name|
-        file = File.join(Sprout.project_path, name)
-        if(File.exists?(file))
-          return file
-        end
-      end
-      return nil
-    end
-    
-    ##
-    # Reset static values for test purposes
-    def Sprout.init_values
-      User.init_values
-      @@project_path = nil
-      @@config_cache = nil
-      @@cache = nil
-      @@home = nil
-    end
-
     ##
     # List of files to ignore when copying project templates
     # These files will not be copied
     @@COPY_IGNORE_FILES = ['.', '..', '.svn', '.DS_Store', 'CVS', '.cvs' 'Thumbs.db', '__MACOSX', '.Trashes', 'Desktop DB', 'Desktop DF']
     # Do not copy files found in the ignore_files list
-    def Sprout.ignore_file? file
+    def self.ignore_file? file
       @@COPY_IGNORE_FILES.each do |name|
         if(name == file)
           return true
@@ -281,84 +369,88 @@ module PatternPark
       return false
     end
     
-    ## 
-    # The project name as entered in the sprout shell command
-    def Sprout.project_name=(name)
-      @@project_name = name
-    end
-    
-    def Sprout.project_name
-      return @@project_name
-    end
-    
-    def get_platform_target
-      usr = User.new
-      @target = nil
-      if(targets)
-        universal_target = nil
-        platform = usr.platform.to_s
-#        puts "platform: #{platform}"
-        targets.each do |t|
-          if(t.platform == platform)
-            @target = t
-          elsif(t.platform == @@universal)
-            universal_target = t
-          end
-        end
-        if(target.nil? && universal_target)
-          @target = universal_target
-        end
+    def self.gem_sources=(sources) # :nodoc:
+      if(sources.is_a?(String))
+        # TODO: Clean up the string that is sent in,
+        # maybe even split space or comma-delimited?
+        sources = [sources]
       end
-      return @target
+      @@gem_sources = sources
     end
     
-    ##
-    # The first FileTarget that is applicable for this
-    # client operating system
-    def target
-      return @target
+    # TODO: Should be updated after release so that all gems are 
+    # loaded form rubyforge instead of projectsprouts, only development
+    # gems will continue to be hosted at this default domain.
+    def self.gem_sources # :nodoc:
+      @@gem_sources ||= ['http://gems.rubyforge.org']
     end
 
-    def executable
-      return target.executable
+    def self.project_name=(name) # :nodoc:
+      @@project_name = name
     end
     
-    def archive_path
-      return File.join(install_path, target.archive_path)
+    # Return the current project_name assuming someone has already set it, otherwise return an empty string
+    def self.project_name
+      @@project_name ||= ''
     end
     
-    def install_path
-      target.install_path
+    def self.project_path=(path) # :nodoc:
+      @@project_rakefile = child_rakefile(path)
+      @@project_path = path
     end
     
-    def downloaded_path
-      target.downloaded_path
+    # project_path should step backward in the file system
+    # until it encounters a rakefile. The parent directory
+    # of that rakefile should be returned.
+    # If no rakefile is found, it should return Dir.pwd
+    def self.project_path
+      @@project_path ||= get_implicit_project_path(Dir.pwd)
     end
     
-    def config_path(name)
-      return Sprout.config_cache + name
+    # Return the rakefile in the current +project_path+
+    def self.project_rakefile
+      return @@project_rakefile ||= nil
+    end
+
+    private
+
+    # Look in the provided +dir+ for files that meet the criteria to be a valid Rakefile.
+    def self.child_rakefile(dir)
+      @@default_rakefiles.each do |file|
+        rake_path = File.join(dir, file)
+        if(File.exists?(rake_path))
+          return rake_path
+        end
+      end
+      return nil
     end
+
+    def self.get_implicit_project_path(path)
+      # We have recursed to the root of the filesystem, return nil
+      if(path.nil? || path == '/' || path.match(/[A-Z]\:\//))
+        return Dir.pwd
+      end
+      # Look for a rakefile as a child of the current path
+      if(child_rakefile(path))
+        return path
+      end
+      # No rakefile and no root found, check in parent dir
+      return Sprout.get_implicit_project_path(File.dirname(path))
+    end
+
   end
+end
 
-  require 'singleton'
-  require 'progress_bar'
-  require 'process_runner'
-  require 'template_resolver'
-  require 'platform'
-  require 'user'
-  require 'project'
-  require 'library'
-  require 'template'
-  require 'task'
-  require 'command'
-  require 'tool'
-  require 'remote_file_loader'
-  require 'file_target'
-  require 'remote_file_target'
-  
-  require 'project_model'
-  require 'generate'
+# Set an array of URLs to use as gem repositories when loading Sprout gems.
+# Any rakefile that requires the sprout gem can use this method as follows:
+#
+#   set_sources ['http://gems.yourdomain.com']
+#
+def set_sources(sources)
+  Sprout::Sprout.gem_sources = sources
 end
 
-cache = File.join(PatternPark::Sprout.cache)
-$:.push(cache)
+# Helper method that will download and install remote sprouts by name and version
+def sprout(name, version=nil)
+  Sprout::Sprout.sprout(name, version)
+end