chrysalis 0.1.0

data/lib/chrysalis/manifest.rb

@@ -0,0 +1,193 @@
+require 'singleton'
+require 'chrysalis/project'
+require 'chrysalis/vcs'
+require 'chrysalis/errors'
+require 'chrysalis/core_ext/string'
+
+
+module Chrysalis
+  
+  META_DIRECTORY  = '.chrysalis'.freeze
+  META_CACHE_FILE = '.chrysalis/cache.yml'.freeze
+  
+  class << self
+    def boot
+      Chrysalis::Loader.instance
+      Chrysalis::Cache.instance
+    end
+    
+    #--
+    # TODO: A proper solution for configuration options needs to be implemented.
+    def options
+      @options ||= OpenStruct.new :prefix => './lib'
+    end
+  end
+  
+  
+  # Contains an entry for each project included as a component of larger
+  # application or library.
+  class Manifest
+    include Singleton
+    
+    def initialize  # :nodoc:
+      @projects = {}
+    end
+    
+    # Returns a Project if +key+ is a url.  Returns a URL if +key+ is a Project.
+    #
+    # The Manifest functions as a two-way hash, where either a URL or a Project
+    # can be used as a key, returning its associated value.
+    def [](key)
+      return @projects.invert[key] if key.is_a?(Project)
+      @projects[key]
+    end
+    
+    def <<(proj)  # :nodoc:
+      key = Chrysalis::Loader.instance.loading
+      
+      raise ManifestError, "Project already exists in manifest. (URL: #{key})" if @projects[key]
+      @projects[key] = proj
+    end
+    
+  end
+  
+  # Stores the results of retrieving a working copy from a repository.
+  #--
+  # The cache is implemented as hash, where each URL-based key serves as an
+  # index to another hash.  The entire structure is serialized to the cache file.
+  # When deserializing, the structure is used to instantiate WorkingCopy
+  # instances, effectively recovering the state of previously retrieved working
+  # copies.
+  class Cache
+    include Singleton
+    
+    def initialize  # :nodoc:
+      @hash = {}
+      load
+    end
+    
+    def [](url)
+      @hash[url]
+    end
+    
+    def []=(url, working_copy)
+      @hash[url] = working_copy.to_hash
+      serialize
+    end
+    
+    private
+      def load
+        return if (!File.exist?(META_CACHE_FILE))
+      
+        File.open(META_CACHE_FILE) do |input|
+          @hash = YAML.load(input)
+          @hash = {} if @hash.nil?
+        end
+      
+        expired = @hash.reject do |url, value|
+          working_copy = WorkingCopy.create(value)
+          if working_copy.nil?
+            false
+          else
+            if !working_copy.exist?
+              false
+            else
+              Chrysalis::Loader.instance.load(url, working_copy)
+              true
+            end
+          end
+        end
+      
+        expired.each { |key, value| @hash.delete(key) }
+        serialize
+      end
+    
+      def serialize
+        FileUtils.mkdir_p(META_DIRECTORY) if (!File.exist?(META_DIRECTORY))
+        
+        File.open(META_CACHE_FILE, 'w') do |out|
+          YAML.dump(@hash, out)
+        end
+      end
+    
+  end
+  
+  
+  # Manages tasks synthesized by Chrysalis.
+  #
+  # Chrysalis synthesizes any tasks into an <em>all:</em> namespace.  When
+  # executing a task in this namespace, Chrysalis will retrieve any required
+  # dependencies and execute the task on them.
+  #
+  # Graph algorithms are used to ensure that task execution is done in the
+  # correct order.  Tasks are guaranteed to be executed on dependencies before
+  # being executed on any dependents.
+  #
+  # For example, if a <tt>build</tt> task is declared, then an <tt>all:build</tt>
+  # task will be synthesized.  Executing <em>rake all:build</em> will first
+  # retrieve dependencies, execute build upon them, and then invoke the main
+  # project's build task.
+  
+  module TaskManager
+    @@tasks = []
+    
+    # Synthesizes a task into the <em>all:</em> namespace.
+    def self.synthesize_task(name, comment)
+      # Don't synthesize tasks "all:*", "project:*", or "retrieve" tasks.  These
+      # tasks are specific to Chrysalis, and only useful in the context of the
+      # main project. 
+      if name.begin?('all:') || name.begin?('project:') || name.eql?('retrieve')
+        return
+      end
+      
+      if !@@tasks.include?(name)
+        
+        rake_namespace :all do
+          rake_task name => "^retrieve"
+          
+          rake_desc "Invoke #{name} task, including dependencies."
+          rake_task name do
+          
+            order = Chrysalis::Manifest.instance[:main].task_exec_order
+            order.delete(:main)
+          
+            order.each do |url|
+              proj = Chrysalis::Manifest.instance[url]
+              if proj.task?(name)
+                cur_dir = FileUtils.pwd
+                FileUtils.cd(proj.working_copy.path)
+              
+                puts ""
+                puts "Invoking #{name} in #{proj.working_copy.path}"
+              
+                cmd = "rake #{name}"
+                cmd << " --trace" if Rake.application.options.trace
+              
+                # This is a work-around for funky handling of processes on
+                # Windows.  If not done, rake will always fail with the following
+                # message:
+                # > rake aborted!
+                # > undefined method `exitstatus' for nil:NilClass
+                cmd << " 2>&1" if RUBY_PLATFORM.match(/mswin/)
+              
+                sh cmd
+              
+                FileUtils.cd(cur_dir)
+              end
+            end
+            
+            if Chrysalis::Manifest.instance[:main].task?(name)
+              puts ""
+              puts "Invoking #{name}"
+              Rake.application[name].invoke
+            end
+          end
+        end
+        
+        @@tasks << name
+      end
+    end
+    
+  end
+  
+end

data/lib/chrysalis/project.rb

@@ -0,0 +1,129 @@
+require 'pathname'
+require 'gratr'
+require 'gratr/dot'
+require 'chrysalis/repository'
+require 'chrysalis/core_ext/string'
+
+
+module Chrysalis
+  
+  # Represents a software development project, typically an application or
+  # library.
+  class Project
+    attr_accessor :name
+    attr_accessor :version
+    attr_accessor :working_copy
+    
+    def initialize
+      Chrysalis::Manifest.instance << self
+      
+      @working_copy = nil
+      @tasks = {}
+      @dependencies = []
+      yield self if block_given?
+    end
+    
+    def url
+      Chrysalis::Manifest.instance[self]
+    end
+    
+    # Add a dependency, located at +url+, to the project.
+    def dependency(url, params = {})
+      @dependencies << [url, params]
+    end
+    alias_method :dependency=, :dependency
+    
+    
+    def task(name, comment)
+      desc = (@tasks.has_key?(name) ? @tasks[name] : '')
+      desc.concat_sep(comment, " / ")
+      @tasks[name] = desc
+    end
+    
+    def task?(name)
+      @tasks.has_key? name
+    end
+    
+    # Retrieve all dependencies required by the project.
+    def retrieve
+      # A project can be declared as a dependency multiple times, which is a
+      # common occurance for shared libraries.  After the initial retrieval, the
+      # retrieved flag is set.  Subsequent retrievals are unnessesary.
+      return if @retrieved
+      @retrieved = true
+      
+      FileUtils.mkdir_p(Chrysalis.options.prefix)
+      
+      # Retrieve each direct dependency from its repository, and load it into
+      # the manifest.
+      @dependencies.each do |url, params|
+        # If the URL of the project is already in the manifest, it has already
+        # been loaded.
+        if !Chrysalis::Manifest.instance[url]
+          working_copy = Repository.retrieve(url, Chrysalis.options.prefix, params)
+          Chrysalis::Loader.instance.load(url, working_copy)
+        end
+      end
+      
+      # Transitively retrieve dependencies.
+      @dependencies.each do |url, params|
+        Chrysalis::Manifest.instance[url].retrieve
+      end
+    end
+    
+    def info
+      n = (@name ? @name : "<Unknown Name>")
+      v = (@version ? "(#{@version})" : "")
+      
+      printf "- %s %s\n", n, v
+      puts   "  #{self.url}" if self.url.is_a?(String)
+
+      if Rake.application.options.trace
+        @tasks.each do |name, comment|
+          printf "     %-18s # %s\n", name, comment
+        end
+      end
+    end
+    
+    def graph(g = GRATR::Digraph.new)
+      @dependencies.each do |url, params|
+        raise "Illegal declaration of dependency on self." if self.url == url
+        
+        # If an arc has already been connected between a project and a
+        # dependency, a cycle has been induced.  This needs to be detected to
+        # prevent this function from looping indefinately.
+        #
+        # For example:
+        #  libone ---depends-on--> libtwo
+        #  libtwo ---depends-on--> libone
+        #
+        # Would graph as follows:
+        #  libone --> libtwo
+        #    ^           |
+        #    '-----------'
+        #
+        # If not prevented this will keep adding edges from libone -> libtwo ->
+        # libone -> libtwo -> libone, and on and on and on, ad infinitum.
+        if !g.edge?(self.url, url)
+          g.add_edge!(self.url, url)
+          
+          # Build the graph recursively, by telling the dependency to construct
+          # its portion.
+          dep = Chrysalis::Manifest.instance[url]
+          dep.graph(g) if !dep.nil?
+        end
+      end
+      
+      return g.add_vertex!(self.url)
+    end
+    
+    def task_exec_order
+      g = graph
+      raise "Cyclic dependency detected." if g.cyclic?
+      
+      g.topsort.reverse
+    end
+    
+  end
+  
+end

data/lib/chrysalis/rake_ext/intercept.rb

@@ -0,0 +1,90 @@
+require 'rake'
+require 'chrysalis/loader'
+
+
+# Intercept Rake's methods for declaring tasks.
+#
+# Task interception is used to construct internal tables, and synthesize
+# tasks in the <em>all:</em> namespace.
+#
+# Tasks declared in the course of loading a dependency are intercepted
+# completely, and are unknown to Rake.  This prevents dependencies from
+# polluting the task space of their dependents.
+#
+# Tasks declared by the main rakefile are forwarded to Rake's original methods,
+# ensuring that the system remains consistent.
+
+class Object
+  
+  alias_method :rake_task, :task
+  def task(args, &block)
+    task_name, deps = Rake.application.resolve_args(args)
+    Chrysalis::Loader.instance.task_intercept(task_name) { rake_task(args, &block) }
+  end
+
+  alias_method :rake_file, :file
+  def file(args, &block)
+    task_name, deps = Rake.application.resolve_args(args)
+    Chrysalis::Loader.instance.file_task_intercept(task_name) { rake_file(args, &block) }
+  end
+
+  alias_method :rake_file_create, :file_create
+  def file_create(args, &block)
+    task_name, deps = Rake.application.resolve_args(args)
+    Chrysalis::Loader.instance.file_task_intercept(task_name) { rake_file_create(args, &block) }
+  end
+
+  #--
+  # NOTE: Intercepting directory tasks is unnecessary, because Rake itself
+  #       implements them as a set of file_create tasks.  Thus, the interception
+  #       of file_create is sufficient.
+  #alias_method :rake_directory, :directory
+  #def directory(dir)
+  #end
+
+  alias_method :rake_multitask, :multitask
+  def multitask(args, &block)
+    task_name, deps = Rake.application.resolve_args(args)
+    Chrysalis::Loader.instance.task_intercept(task_name) { rake_multitask(args, &block) }
+  end
+
+  alias_method :rake_namespace, :namespace
+  def namespace(name=nil, &block)
+    Chrysalis::Loader.instance.namespace_intercept(name, block) { rake_namespace(name, &block) }
+  end
+
+  alias_method :rake_rule, :rule
+  def rule(args, &block)
+    Chrysalis::Loader.instance.rule_intercept { rake_rule(args, &block) }
+  end
+
+  alias_method :rake_desc, :desc
+  def desc(comment)
+    Chrysalis::Loader.instance.desc_intercept(comment) { rake_desc(comment) }
+  end
+
+end
+
+
+module Rake
+  
+  class Application
+  
+    alias_method :rake_top_level, :top_level
+    
+    # Invoked after the main rakefile has been loaded, but before any tasks are
+    # executed.
+    #
+    # Chrysalis reimplements this method for the purpose of hooking into the
+    # loader and seeding the <em>all:</em> namespace with tasks, prior to
+    # retrieval of dependencies.
+    #
+    # After invoking the hook, execution proceeds with Rake's original method.
+    def top_level
+      Chrysalis.post :rakefile_loaded
+      rake_top_level
+    end
+  
+  end
+  
+end

data/lib/chrysalis/repository.rb

@@ -0,0 +1,142 @@
+require 'pathname'
+require 'chrysalis/errors'
+
+
+module Chrysalis
+
+  # Represents a repository from which dependencies can be retrieved.
+  #
+  # This class is intended to be subclassed in order to implement support for
+  # concrete types of repositories.
+  class Repository
+    @@repositories = []
+    
+    def self.inherited(repository)  # :nodoc:
+      @@repositories << repository
+    end
+    
+    # Retrieves a WorkingCopy from the repository located at +url+.  The working
+    # copy is placed at the path +to+, which defaults to the current directory.
+    # An optional set of parameters can be specified in +params+.
+    #
+    # Returns a WorkingCopy.
+    #
+    # Using the factory design pattern, this method locates a subclass of
+    # Repository that implements support for the given URL.  That subclass will
+    # be instructed to retrieve a working copy from the repository.
+    #
+    # If the working copy has already been retrieved, it will be found in the
+    # cache and returned directly.
+    #
+    # If support for the given URL is not implemented, a RepositoryError will be
+    # raised.
+    def self.retrieve(url, to = '.', params = {})
+      cached = WorkingCopy.create(Chrysalis::Cache.instance[url])
+      return cached if cached
+      
+      @@repositories.reverse.each { |repository|
+        if repository.retrieves?(url, params)
+          working_copy = repository.new(url, params).retrieve(to)
+          Chrysalis::Cache.instance[url] = working_copy
+          return working_copy
+        end
+      }
+      raise RepositoryError, "Unknown version control system. (URL: #{url})"
+    end
+    
+    
+    # Returns +true+ if this class implements support for +url+.  Otherwise,
+    # returns +false+.
+    #
+    # Because this class is abstract, +false+ is returned unconditionally.
+    # Subclasses are expected to provide an implementation.
+    def self.retrieves?(url, params = {})
+      false
+    end
+    
+    def initialize(url, params = {})
+    end
+    
+    # Retrieves a working copy from the repository.
+    #
+    # Because this class is abstract, always raises an UnimplementedError.
+    # Subclasses are expected to provide an implementation.
+    def retrieve(to = '.')
+      raise UnimplementedError, "Repository#retrieve not implemented"
+    end
+    
+  end
+
+
+  # Represents a working copy that has been retrieved from a repository.
+  #
+  # This class implements support for a file system-based working copy stored in
+  # a directory.
+  #
+  # Subclasses can provide implementation for working copies with additional
+  # functionality, such as those retrieved from a version control system.
+  class WorkingCopy
+    @@working_copies = [self]
+    
+    def self.inherited(working_copies)  # :nodoc:
+      @@working_copies << working_copies
+    end
+    
+    # Returns a WorkingCopy constructed with +params+.
+    #
+    # Using the factory design pattern, this method instantiates a new instance
+    # of WorkingCopy based on the key <tt>:type</tt> in the +params+ hash.
+    #
+    # If <tt>:type</tt> is not supported, +nil+ is returned.
+    #
+    # This method is intended to be used for the purpose of instantiating a
+    # working copies directly from the cache, to obviate the need for retrieval
+    # when the working copy already exists on the system.
+    def self.create(params)
+      return nil if params.nil?
+      type = params[:type]
+      
+      @@working_copies.each do |working_copy|
+        return working_copy.new(params) if working_copy.type == type
+      end
+      nil
+    end
+    
+    
+    attr_reader :url
+    attr_reader :path
+
+    def self.type
+      :directory
+    end
+
+    def initialize(params = {})
+      @url = params[:url]
+      @path = params[:path]
+    end
+    
+    # Returns +true+ if the working copy exists on disk.  Otherwise, returns
+    # +false+.
+    #
+    # Typically, if the working copy no longer exits on disk, it has been
+    # explicitly removed by a developer.
+    def exist?
+      Pathname.new(@path).exist?
+    end
+    
+    # Returns a hash which will be serialized to the cache.
+    #
+    # At a minimum, a <tt>:type</tt> key must be present in the hash.  This key
+    # is used when loading the cache, to instantiate working copies that have
+    # previously been retrieved.
+    #
+    # Subclasses can add any additional keys and values to the hash, and utilize
+    # them for purposes of deserialization.
+    def to_hash
+      { :type => self.class.type,
+        :url => @url,
+        :path => @path }
+    end
+  end
+
+end

data/lib/chrysalis/task.rb

@@ -0,0 +1,78 @@
+require 'rake'
+require 'rake/tasklib'
+require 'chrysalis/manifest'
+
+
+module Rake
+  
+  class ChrysalisTask < TaskLib
+    
+    def initialize()
+      yield self if block_given?
+      define
+    end
+    
+    def define
+      namespace :project do
+        
+        desc "Show project information."
+        task :info do
+          raise "No project has been defined." if Chrysalis::Manifest.instance[:main].nil?
+        
+          puts ""
+          puts "Project information: "
+
+          main = Chrysalis::Manifest.instance[:main]
+          main.graph.topsort.each do |url|
+            p = Chrysalis::Manifest.instance[url]
+            if p.nil?
+              puts "* #{url} [Not Loaded]"
+            else
+              p.info
+            end
+          end
+          
+        end
+      
+        desc "Display task execution order."
+        task :order do
+          raise "No project has been defined." if Chrysalis::Manifest.instance[:main].nil?
+        
+          order = Chrysalis::Manifest.instance[:main].task_exec_order
+        
+          puts ""
+          puts "Tasks execution order: "
+          order.each { |url| puts "- #{url}" }
+        end
+      
+        desc "Draw dependency graph."
+        task :graph do
+          raise "No project has been defined." if Chrysalis::Manifest.instance[:main].nil?
+          
+          g = Chrysalis::Manifest.instance[:main].graph
+        
+          name = Chrysalis::Manifest.instance[:main].name
+          file = (name ? name.downcase.concat("-graph") : "graph")
+        
+          dot = g.write_to_graphic_file('jpg', file)
+        
+          puts "Dependency graph saved to #{dot}"
+        end
+        
+      end
+      
+      desc "Retrieve dependencies."
+      task :retrieve do
+        raise "No project has been defined." if Chrysalis::Manifest.instance[:main].nil?
+        Chrysalis::Manifest.instance[:main].retrieve
+      end
+      
+      self
+    end
+    
+  end
+  
+end
+
+
+Chrysalis.boot

data/lib/chrysalis/vcs/file/repository.rb

@@ -0,0 +1,63 @@
+require 'uri'
+require 'pathname'
+require 'chrysalis/repository'
+require 'chrysalis/ar'
+
+
+module Chrysalis
+module VCS
+module File
+
+  # Implements support for copying dependencies from a file system.
+  #
+  # Repositories of this type are identified by <em>file://</em> URLs.
+  #
+  # Example:
+  #  - file:///Users/jaredhanson/Projects/libfoo
+  
+  class Repository < Chrysalis::Repository
+    
+    def self.retrieves?(url, params = {})
+      uri = URI::parse(url)
+      return uri.scheme == 'file'
+    end
+    
+    
+    def initialize(url, params = {})
+      @url = url
+      @params = params
+    end
+    
+    def retrieve(to = '.')
+      target = Pathname.new(to).join(copy_to)
+      raise IOError, "Refusing to overwrite existing path. (path: #{target})" if target.exist?
+    
+      unless @params[:noop]
+        puts ""
+        puts "Copying #{@url} ..."
+      
+        source = URI::parse(@url)
+        FileUtils.cp_r(source.path, target)
+      end
+      
+      extract_path = Archive.extract(target.to_s, to, @params)
+      WorkingCopy.new(:url => @url,
+                      :path => extract_path)
+    end
+    
+    private
+      def copy_to
+        return @params[:copy_to] if @params[:copy_to]
+        
+        uri = URI::parse(@url)
+        dir = uri.path.split('/')[-1]
+        
+        raise ParameterError, "Invalid URL. (URL: #{@url})" if dir.nil?
+        return dir
+      end
+    
+  end
+
+end
+end
+end

data/lib/chrysalis/vcs/file.rb

@@ -0,0 +1 @@
+require 'chrysalis/vcs/file/repository'