sprout 0.7.246 → 1.0.0.pre

data/lib/sprout/ruby_feature.rb

@@ -0,0 +1,167 @@
+
+module Sprout
+
+  ##
+  # This class represents a Feature that is written in
+  # Ruby code that exists on the other side of the
+  # Ruby load path.
+  #
+  # The idea here, is that one can +include+ the Sprout::RubyFeature
+  # module into their concrete class, and then accept
+  # requests to +register+ and +load+ from clients that
+  # are interested in pluggable features.
+  #
+  # An example is as follows:
+  #
+  #     require 'sprout'
+  #
+  #     class MyClass
+  #       include Sprout::RubyFeature
+  #     end
+  #
+  # In some other Ruby file:
+  #
+  #     MyClass.load :other, 'other_gem', '>= 1.0pre'
+  #
+  # In the desired Ruby file:
+  #
+  #     class OtherClass
+  #       include Sprout::Executable
+  #
+  #       set :name, :other
+  #       set :pkg_name, 'other_gem'
+  #       set :pkg_version, '1.0.pre'
+  #
+  #       # do something...
+  #     end
+  #
+  #     MyClass.register OtherClass.new
+  #
+  module RubyFeature
+
+    extend Concern
+
+    module ClassMethods
+
+      ##
+      # Register a new feature for future lookups
+      def register entity
+        validate_registration entity
+        registered_entities.unshift entity
+        entity
+      end
+
+      ##
+      # Load a feature by name.
+      def load name_or_names, pkg_name=nil, version_requirement=nil
+        entity = entity_for name_or_names, pkg_name, version_requirement
+        if(entity.nil?)
+          # Try to require the pkg_name:
+          require_ruby_package pkg_name unless pkg_name.nil?
+          # Update any entities that registered from our require:
+          update_registered_entities
+          # search for the requested entity:
+          entity = entity_for name_or_names, pkg_name, version_requirement
+        end
+
+        if(entity.nil?)
+          message = "The requested entity: (#{name_or_names}) with pkg_name: (#{pkg_name}) and version: "
+          message << "(#{version_requirement}) does not appear to be loaded."
+          message << "\n"
+          message << "We did find (#{registered_entities.size}) registered entities in that package:\n\n"
+          registered_entities.each do |other|
+            message << ">> name: (#{other.name}) pkg_name: (#{other.pkg_name}) pkg_version: (#{other.pkg_version})\n"
+          end
+          message << "\n\nYou may need to update your Gemfile and run 'bundle install' "
+          message << "to update your local gems.\n\n"
+          raise Sprout::Errors::LoadError.new message
+        end
+        entity
+      end
+
+      def clear_entities!
+        @registered_entities = []
+      end
+
+      protected
+
+      def validate_registration entity
+        if(!entity.respond_to?(:name) || entity.name.nil?)
+          raise Sprout::Errors::UsageError.new "Cannot register a RubyFeature without a 'name' getter"
+        end
+      end
+
+      ##
+      # Used by the Generator::Base to update inputs from 
+      # empty class definitions to instances..
+      def update_registered_entities
+      end
+
+      def entity_for name_or_names, pkg_name, version_requirement
+        #puts "+++++++++++++++++++++++++++"
+        #puts ">> entity_for #{name} pkg_name: #{pkg_name} version: #{version_requirement}"
+        #registered_entities.each do |entity|
+          #puts ">> entity: #{entity.name} pkg_name: #{entity.pkg_name} version: #{entity.pkg_version}"
+        #end
+        registered_entities.select do |entity|
+            satisfies_name?(entity, name_or_names) && 
+            satisfies_platform?(entity) &&
+            satisfies_pkg_name?(entity, pkg_name) &&
+            satisfies_version?(entity, version_requirement)
+        end.first
+      end
+      def satisfies_environment? entity, environment
+        #puts ">> env: #{entity.environment} vs. #{environment}"
+        environment.nil? || !entity.respond_to?(:environment) || entity.environment.to_s == environment.to_s
+      end
+
+      def satisfies_pkg_name? entity, expected
+        #puts ">> pkg_name: #{entity.pkg_name} vs. #{expected}"
+        expected.nil? || !entity.respond_to?(:pkg_name) || entity.pkg_name.to_s == expected.to_s
+      end
+
+      def satisfies_name? entity, expected
+        #puts ">> name: #{entity.name} vs. #{expected}"
+        return true if expected.nil? || !entity.respond_to?(:name)
+        if expected.is_a?(Array)
+          return expected.include? entity.name
+        end
+        return expected.to_s == entity.name.to_s
+      end
+
+      def satisfies_platform? entity
+        #puts">> satisfies platform?"
+        return true if !entity.respond_to?(:platform) || entity.platform.nil?
+        #puts ">> platform: #{entity.platform}"
+        Sprout.current_system.can_execute?(entity.platform)
+      end
+
+      def satisfies_version? entity, version_requirement=nil
+        return true if version_requirement.nil?
+        req_version = Gem::Requirement.create version_requirement
+        req_version.satisfied_by?(Gem::Version.create(entity.pkg_version))
+      end
+
+      def require_ruby_package name
+        begin
+          require name
+        rescue LoadError => e
+          raise Sprout::Errors::LoadError.new "Could not load the required file (#{name}) - Maybe you need to run 'gem install #{name}' or maybe 'bundle install'?"
+        end
+      end
+
+      ##
+      # An entity has the following parameters:
+      # name
+      # pkg_name
+      # pkg_version
+      # platform
+      #
+      def registered_entities
+        @registered_entities ||= []
+      end
+    end
+
+  end
+end
+

data/lib/sprout/specification.rb

@@ -0,0 +1,197 @@
+
+module Sprout
+
+  ##
+  # Sprouts provides us with the ability to distribute source files, 
+  # precompiled libraries, and remote executables. It does all of 
+  # this by (ab)using RubyGems.
+  #
+  # RubyGems gives us the ability to version-manage, and distribute 
+  # arbitrary text and binary payloads.
+  #
+  # In order to support Flash development, we have one major problem
+  # that RubyGems does not solve for us. This is the fact that 
+  # many elements of our executable chain are not open-source, and we do
+  # not have the rights to directly distribute them.
+  #
+  # This restriction means that many of our tools and dependencies cannot be 
+  # packaged and distributed _directly_ within a RubyGem (or from
+  # any server other than Adobe's as a matter of fact).
+  #
+  # In order to overcome this restriction, we have introduced
+  # a Sprout::Specification. This is a regular Ruby file with regular
+  # Ruby code in it. The main idea behind this file, is that it
+  # needs to be given a name and available in your load path.
+  #
+  # Whenever a rake build task (Sprout::Executable) or library task,
+  # (Sprout::Library) is encountered, it will call
+  # Sprout::Executable.load or Sprout::Library.load (respectively).
+  #
+  # These methods will attempt to +require+ the provided
+  # specification and - if it's in your load path - the specification
+  # will be loaded, and any relevant file targets will be returned.
+  #
+  # There are many ways to get Ruby code into your load path.
+  # One of the easiest to package it up in a RubyGem and
+  # configure the +require_paths+ parameter of  your Gem::Specification.
+  #
+  # http://docs.rubygems.org/read/chapter/20#require_paths
+  #
+  # To learn more about packaging RubyGems:
+  #
+  # http://docs.rubygems.org/read/chapter/20#page85
+  # http://rubygems.rubyforge.org/rdoc/Gem/Specification.html
+  #
+  # To learn more about published RubyGems:
+  # 
+  # http://rubygems.org/pages/gem_docs
+  #
+  # To package a SWC library into a Sprout RubyGem, you would create a file (usually)
+  # named [project_name.spec] in the root of the project.
+  #
+  # This is your Gem::Specification.
+  #
+  # You would also create a file named [projet_name.rb] and put that
+  # into the root of the project or some other folder that you have added to 
+  # the Gem::Specification.require_paths parameter.
+  #
+  # == Example: Include a file directly in the RubyGem
+  #
+  # In the case of AsUnit, this file would be named asunit4.rb and it's contents
+  # are as follows:
+  #
+  #    :include:../../test/fixtures/specification/asunit4.rb
+  #
+  # == Example: Refer to files that are not in the RubyGem
+  #
+  # For projects like the Flex SDK, we can't distribute many of the required files,
+  # so we can refer to these files in our Sprout::Specification as +remote_file_targets+.
+  #
+  #    :include:../../test/fixtures/specification/flex4sdk.rb
+  #
+  # == Example: Create custom downloads for each supported platform
+  #
+  # For projects like the Flash Player itself, we need to refer to different 
+  # downloadable content for each supported platform.
+  #
+  #    :include:../../test/fixtures/specification/flashplayer.rb
+  #
+  # == Packaging and Sharing
+  #
+  # Public RubyGems are hosted at http://rubygems.org. 
+  class Specification
+
+    attr_accessor :name
+    attr_accessor :version
+
+    attr_reader :file_targets
+    attr_reader :load_path
+
+    ##
+    # Create a new Sprout::Specification.
+    #
+    # This method will yield the new Sprout::Specification to the provided block,
+    # and delegate most configuration parameters to a {Gem::Specification}[http://rubygems.rubyforge.org/rdoc/Gem/Specification.html].
+    #
+    # To learn more about what parameters are available and/or required, please
+    # check out RubyGems documentation for their {Gem::Specification}[http://rubygems.rubyforge.org/rdoc/Gem/Specification.html].
+    #
+    def initialize
+      filename   = Sprout.file_from_caller caller.first
+      @load_path = File.dirname filename
+      @name      = File.basename(filename).gsub('.rb', '')
+      yield self if block_given?
+    end
+
+    ##
+    # Add a remote file target to this RubyGem so that when it
+    # is loaded, Sprouts will go fetch this file from the network.
+    #
+    # Each time this method is called, a new Sprout::RemoteFiletarget instance will be yielded to
+    # the provided block and resolved after the block completes.
+    #
+    # After this block is evaluated, Sprouts will first check the collection
+    # of env_names to see if the expected paths are available. If a valid
+    # env_name is found, Sprouts will return the path to the requested
+    # executable from the environment variable.
+    #
+    # If no env_names are set, or the requested executable is not found within
+    # any that are identified, Sprouts will check to see if the archive
+    # has already been unpacked into the expected location:
+    # 
+    #     #{SPROUT_HOME}/cache/#{SPROUT_VERSION}/flex4sdk/#{md5}/4.0.pre
+    #
+    # If the archive been unpacked, Sprouts will return the path to the 
+    # requested executable.
+    #
+    # If the archive has not been unpacked, Sprouts will check to see if the
+    # archive has been downloaded to:
+    #
+    #     #{SPROUT_HOME}/cache/#{SPROUT_VERSION}/flex4sdk/#{md5}.zip
+    #
+    # If the archive has been downloaded, it will be unpacked and the path
+    # to the requested executable will be returned.
+    #
+    # If the archive has not been downloaded, it will be downloaded, unpacked
+    # and the path to the requested executable will be returned.
+    def add_remote_file_target &block
+      target = RemoteFileTarget.new do |t|
+        configure_target t, &block
+      end
+      target.resolve
+      register_file_target target
+    end
+
+    # Add a file to the RubyGem itself. This is a great way to package smallish libraries in either
+    # source or already-packaged form. For example, one might add a SWC to a RubyGem library.
+    # 
+    # Each time this method is called, a new Sprout::FileTarget instance will be yielded to the
+    # provided block, and added to a collection for packaging.
+    #
+    #     Sprout::Specification.new do |s|
+    #        ...
+    #        s.add_file_target do |t|
+    #           t.platform = :universal
+    #           t.add_executable :asdoc, 'bin/asdoc'
+    #        end
+    #     end
+    #
+    def add_file_target &block
+      target = FileTarget.new do |t|
+        configure_target t, &block
+      end
+      register_file_target target
+    end
+
+    private
+
+    def configure_target t, &block
+      t.load_path   = load_path
+      t.pkg_name    = name
+      t.pkg_version = version
+      yield t if block_given?
+    end
+
+    def register_file_target target
+      register_items target.executables, Sprout::Executable, target
+      # Reversing the libraries makes it so that definitions like:
+      #
+      #   target.add_library :swc, 'abcd'
+      #   target.add_library :src, 'efgh'
+      # 
+      # When loading, if no name is specified, the :swc will be
+      # returned to clients.
+      register_items target.libraries.reverse, Sprout::Library, target
+    end
+
+    def register_items collection, source, target
+      collection.each do |item|
+        item.pkg_name    = target.pkg_name
+        item.pkg_version = target.pkg_version
+        source.register item
+      end
+    end
+
+  end
+end
+

data/lib/sprout/string.rb

@@ -0,0 +1,19 @@
+
+class String
+
+   # "FooBar".snake_case #=> "foo_bar"
+   def snake_case
+     gsub(/\B[A-Z]/, '_\&').downcase
+   end
+
+   # "foo_bar".camel_case #=> "FooBar"
+   def camel_case
+     str = gsub(/^[a-z]|_+[a-z]/) { |a| a.upcase }
+     str.gsub(/_/, '')
+   end
+
+   def dash_case
+     self.snake_case.gsub('_', '-')
+   end
+end
+

data/lib/sprout/system.rb

@@ -0,0 +1,35 @@
+require 'sprout/system/base_system'
+require 'sprout/system/unix_system'
+require 'sprout/system/java_system'
+require 'sprout/system/osx_system'
+require 'sprout/system/win_system'
+require 'sprout/system/win_nix_system'
+require 'sprout/system/vista_system'
+
+module Sprout
+
+  module System
+
+    # This is the factory that one should
+    # generally be used to create new, concrete
+    # System objects.
+    #
+    # A typical example follows:
+    #
+    #     system = System.create
+    #     Dir.chdir system.home
+    #     system.execute "pwd" # /home/yourusername
+    #
+    def self.create
+      p = Sprout::Platform.new
+      return VistaSystem.new  if p.vista?
+      return WinNixSystem.new if p.windows_nix?
+      return WinSystem.new    if p.windows?
+      return JavaSystem.new   if p.java?
+      return OSXSystem.new    if p.mac?
+      return UnixSystem.new 
+    end
+
+  end
+end
+

data/lib/sprout/system/base_system.rb

@@ -0,0 +1,225 @@
+
+module Sprout::System
+
+  # The abstract base class for all supported system/platform types.
+  # In general, users are created by calling the +create+ factory method
+  # on the +System+ module.
+  #     
+  #     System.create
+  #
+  # Assuming you call the create method, you should wind up with
+  # a concrete system that matches your system, and these concrete
+  # users will generally be derived from this base class.
+  #
+  class BaseSystem
+
+    ##
+    # Get the home path for a system on a particular operating system.
+    #
+    # This path will be different, depending on which system owns
+    # the curren process, and which operating system they are on.
+    #
+    def home
+      @home ||= find_home
+    end
+
+    ##
+    # Set the home path for a system on a particular operating system.
+    # 
+    # If you request the home path before setting it, we will
+    # attempt to determine the home path of the current system for
+    # the current operating system.
+    #
+    # This is just a simple way to override the default behavior.
+    #
+    def home=(home)
+      @home = home
+    end
+
+    ##
+    # Some operating systems (like OS X and Windows) have a 
+    # specific location where applications are expected to store
+    # files for a particular system. This location is generally
+    # a subdirectory of +home+.
+    # 
+    # The value of this location will usually be overridden in
+    # concrete System classes.
+    #
+    def library
+      return home
+    end
+
+    ##
+    # Instantiate and return a new Sprout::ProcessRunner so
+    # that we can execute it.
+    #
+    def get_process_runner
+      Sprout::ProcessRunner.new
+    end
+
+    def can_execute? platform
+      platform == :universal
+    end
+
+    ##
+    # Creates a new process, executes the command
+    # and returns whatever the process wrote to stdout, or stderr.
+    #
+    # Raises a +Sprout::Errors::ExecutionError+ if the process writes to stderr
+    #
+    def execute(tool, options='')
+      Sprout::Log.puts(">> Execute: #{tool} options: #{options}")
+      runner = get_and_execute_process_runner(tool, options)
+      error  = runner.read_err
+      result = runner.read
+
+      if(result.size > 0)
+        Sprout::Log.puts result
+      end
+
+      if(error.size > 0)
+        raise Sprout::Errors::ExecutionError.new("[ERROR] #{error}")
+      end
+
+      result || error
+    end
+
+    ##
+    # Creates and returns the process without
+    # attempting to read or write to the stream.
+    # This is useful for interacting with
+    # long-lived CLI processes like FCSH or FDB.
+    #
+    def execute_silent(tool, options='')
+      return get_and_execute_process_runner(tool, options)
+    end
+
+    ##
+    # Execute a new process in a separate thread.
+    # This can be useful for processes that take
+    # an especially long time to execute.
+    #
+    # Threads are complicated - use with caution...
+    #
+    def execute_thread(tool, options='')
+      if(Log.debug)
+         return ThreadMock.new
+      else
+        return Thread.new do
+          execute(tool, options)
+        end
+      end
+    end
+
+    ##
+    # Clean the provided +path+ String for the current
+    # operating system.
+    #
+    # Each operating system behaves differently when we
+    # attempt to execute a file with spaces in the +path+
+    # to the file.
+    # 
+    # Subclasses will generally override this method and
+    # clean the path appropriately for their operating 
+    # system.
+    #
+    def clean_path(path)
+    end
+
+    ##
+    # Different operating systems will store Application data
+    # different default locations.
+    #
+    # Subclasses will generally override this method and 
+    # return the appropriate location for their operating system.
+    #
+    # +name+ String value of the Application name for which we'd
+    # like to store data.
+    #
+    def application_home(name)
+      return File.join(library, format_application_name(name.to_s));
+    end
+
+    ##
+    # Template method that should be overridden by
+    # subclasses.
+    #
+    def format_application_name(name)
+      name
+    end
+
+    protected
+
+    def env_homedrive
+      ENV['HOMEDRIVE']
+    end
+
+    def env_homepath
+      ENV['HOMEPATH']
+    end
+
+    def env_homedrive_and_homepath
+      drive = env_homedrive
+      path = env_homepath
+      "#{drive}:#{path}" if drive && path
+    end
+
+    def env_userprofile
+      ENV['USERPROFILE']
+    end
+
+    def env_home
+      ENV['HOME']
+    end
+
+    def tilde_home
+      File.expand_path("~")
+    end
+
+    def alt_separator?
+      File::ALT_SEPARATOR
+    end
+
+    def worst_case_home
+      return "C:\\" if alt_separator?
+      return "/"
+    end
+
+    def find_home
+      [:env_userprofile, :env_home, :env_homedrive_and_homepath].each do |key|
+        value = self.send(key)
+        return value unless value.nil?
+      end
+
+      begin
+        return tilde_home
+      rescue StandardError
+        worst_case_home
+      end
+    end
+
+    protected
+
+    ##
+    # Get a process runner and execute the provided +executable+,
+    # with the provided +options+.
+    #
+    # +executable+ String path to the external executable file.
+    #
+    # +options+ String commandline options to send to the +executable+.
+    #
+    def get_and_execute_process_runner tool, options=nil
+      runner = get_process_runner
+      runner.execute_open4 clean_path(tool), options
+      runner
+    end
+
+  end
+
+  class ThreadMock # :nodoc:
+    def alive?
+      return false
+    end
+  end
+end
+