detroit 0.3.0 → 0.4.0

data/lib/detroit/toolchain/script.rb

@@ -0,0 +1,248 @@
+module Detroit
+
+  module Toolchain
+
+    # Assembly::Script models an *Assembly file* with it's collection of 
+    # tool configurations.
+    #
+    class Script
+
+      # Load Assembly file.
+      def self.load(input, project=nil)
+        new(:file=>input,:project=>project)
+      end
+
+      # Project instance.
+      attr :project
+
+      # Hash table of tool configuration.
+      attr :tools
+
+    private
+
+      #
+      def initialize(options={}, &block)
+        @project = options[:project]
+
+        @tools = {}
+
+        if options[:file]
+          initialize_file(options[:file])
+        end
+
+        if block
+          instance_eval(&block)
+        end
+      end
+
+      # Inititalize from assembly file.
+      #
+      def initialize_file(file)
+        @file = (String === file ? File.new(file) : file)
+
+        case File.extname(@file.path)
+        when '.rb'
+          instance_eval(@file.read, @file.path)
+        when '.yml', '.yaml'
+          @tools = YAML.load(erb(@file.read))
+        else
+          text = @file.read
+          if /^---/ =~ text
+            @tools = YAML.load(erb(text))
+          else
+            instance_eval(text, @file.path)
+          end
+        end
+      end
+
+    public
+
+      # Ecapsulate a set of tools within a specific track.
+      #  
+      def track(name, &block)
+        @_track = name
+        instance_eval(&block)
+        @_track = nil
+      end
+
+      # Configure a tool.
+      #
+      def tool(name, settings={}, &block)
+        settings[:track] = @_track if @_track
+        if block
+          block_context = BlockContext.new(&block)
+          settings.update(block_context.settings)
+        end
+        @tools[name.to_s] = settings.rekey(&:to_s)
+      end
+
+      # Define a custom tool. A custom tool has no tool class.
+      # Instead, the configuration itself defines the procedure.
+      #
+      def custom(name, &block)
+        context  = CustomContext.new(&block)
+        settings = context.settings
+        @tools[name.to_s] = settings.rekey(&:to_s)
+      end
+
+      # Access to project metadata.
+      #
+      # FIXME: Use factory method
+      def project
+        @project ||= Project.new
+      end
+
+    private
+
+      # Capitalized tool names called as methods
+      # can also define a tool.
+      def method_missing(sym, *args, &block)
+        tool_class = sym.to_s
+        case tool_class
+        when /^[A-Z]/
+          if Hash === args.last
+            args.last[:tool] = tool_class
+          else
+            args << {:tool=>tool_class}
+          end
+          case args.first
+          when String, Symbol
+            name = args.first
+          else
+            name = tool_class.to_s.downcase
+          end
+          tool(name, *args, &block)
+        else
+          super(sym, *args, &block)
+        end
+      end
+
+      # Process Routine document via ERB.
+      def erb(text)
+        context = ERBContext.new(project)
+        ERB.new(text).result(context.__binding__)
+      end
+
+      # ERBContext provides the clean context to process a Routine
+      # as an ERB template.
+      class ERBContext
+        #
+        def initialize(project)
+          @project = project
+        end
+
+        # Access to a clean binding.
+        def __binding__
+          binding
+        end
+
+        # Provide access to project data.
+        def project
+          @project
+        end
+
+        #
+        def method_missing(name, *args)
+          if project.respond_to?(name)
+            project.__send__(name, *args)
+          elsif project.metadata.respond_to?(name)
+            project.metadata.__send__(name, *args)
+          else
+            super(name, *args)
+          end
+        end
+      end
+
+      #
+      class BlockContext
+        #
+        attr :settings
+
+        #
+        def initialize(&b)
+          @settings = {}
+          b.arity == 1 ? b.call(self) : instance_eval(&b)
+        end
+
+        #
+        def set(name, value=nil, &block)
+          if block
+            block_context = BlockContext.new
+            block.call(block_context)
+            @settings[name.to_s] = block_context.settings
+          else
+            @settings[name.to_s] = value
+          end
+        end
+
+        #
+        def method_missing(symbol, value=nil, *args)
+          case name = symbol.to_s
+          when /=$/
+            @settings[name.chomp('=')] = value
+          else
+            return super(symbol, value, *args) unless args.empty?
+            if value
+              @settings[name.to_s] = value
+            else
+              @settings[name.to_s]
+            end
+          end
+        end
+      end
+
+      #
+      class CustomContext
+        #
+        attr :settings
+        #
+        def initialize(&b)
+          @settings = {}
+          b.arity == 0 ? instance_eval(&b) : b.call(self)
+        end
+        #
+        def method_missing(s,a=nil,*x,&b)
+          case s.to_s
+          when /=$/
+            @settings[s.to_s.chomp('=').to_sym] = b ? b : a
+          else
+            return @settings[s] unless a
+            @settings[s] = b ? b : a
+          end
+        end
+        def respond_to?(s)
+          @settings.key?(s.to_sym)
+        end
+      end
+
+    end
+
+    # NOTE: This is problematic, because an Assembly file should know from
+    # what file it was derived.
+
+    #
+    DOMAIN = "rubyworks.github.com/detroit,2011-05-27"
+
+    # TODO: If using Psych rather than Syck, then define a domain type.
+
+    #if defined?(Psych) #RUBY_VERSION >= '1.9'
+    #  YAML::add_domain_type(DOMAIN, "assembly") do |type, hash|
+    #    Assembly.load(hash)
+    #  end
+    #else
+      YAML::add_builtin_type("assembly") do |type, value|
+        value
+        #case value
+        #when String
+        #  Assembly.eval(value)
+        #when Hash
+        #  Assembly.new(value)
+        #else
+        #  raise "ERROR: Invalid Assembly"
+        #end
+      end
+    #end
+
+  end
+
+end

data/lib/detroit/toolchain/worker.rb

@@ -0,0 +1,84 @@
+module Detroit
+
+  module Toolchain
+
+    # TODO: Need to work on how to limit a service's groups per-assembly.
+
+    ##
+    # Service class wraps a Tool instance when it is made part of an assembly.
+    #
+    # TODO: Perhpas a better name would be `Link`, as in "chain link"?
+    #
+    class Worker
+
+      attr :key
+      attr :track
+      attr :priority
+      attr :active
+      attr :tool
+      #attr :options
+
+      # Set the priority. Priority determines the order which
+      # services on the same stop are run.
+      #
+      def priority=(integer)
+        @priority = integer.to_i
+      end
+
+      # Set the tracks a service will be available on.
+      #
+      def track=(list)
+        @track = list.to_list
+      end
+
+      #
+      def active=(boolean)
+        @active = !!boolean
+      end
+
+      # Create new wrapper.
+      #
+      def initialize(key, tool_class, options)
+        @key = key
+
+        ## set defaults
+        @track    = nil
+        @priority = 0
+        @active   = true
+
+        self.active   = options.delete('active')   if !options['active'].nil?
+        self.track    = options.delete('track')    if options.key?('track')
+        self.priority = options.delete('priority') if options.key?('priority')
+
+        @tool = tool_class.new(options)
+      end
+
+      # Does the tool handle the given assembly station?
+      #
+      # If `true` is returned than the station is handled by a method
+      # in the tool with the same name.
+      #
+      # If a symbol is returned then the station is handled, but via
+      # the method named by the returned symbol.
+      #
+      # @return [Boolean,Symbol]
+      def stop?(station, stop=nil)
+        @tool.assemble?(station.to_sym, :destination=>stop.to_sym)
+      end
+
+      # Run the service assembly station procedure.
+      #
+      def invoke(station, stop=nil)
+        @tool.assemble(station.to_sym, :destination=>stop.to_sym)
+      end
+
+      #
+      def inspect
+        "<#{self.class}:#{object_id} @key='#{key}'>"
+      end
+
+    end
+
+  end
+
+end

data/man/detroit.1

@@ -0,0 +1,116 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "DETROIT" "1" "January 2014" "" "Detroit"
+.
+.SH "NAME"
+\fBdetroit\fR \- a life\-cycle build tool
+.
+.SH "DESCRIPTION"
+Detroit is a software production management aid\. Detroit utilizes a life\-cycle methodology to help developers prepare and release software in a clear, repeatable, linear fashion\. While programmed in and well suited to Ruby projects, Detroit can utilized for any build requirements\.
+.
+.SH "USAGE"
+To utilize Detroit add a \fBToolchain\fR file to your project\'s root directory\. In this file add instantiation of tools, configured to your projects build requirements\. Toolchain files can be written in YAML or Ruby\.
+.
+.P
+For example to generate RDoc\'s for a project, a tool might be defined:
+.
+.IP "" 4
+.
+.nf
+
+rdoc:
+  tool: rdoc
+  files:
+    \- lib
+    \- \'[A\-Z]*\.*\'
+  main: README\.md
+.
+.fi
+.
+.IP "" 0
+.
+.P
+See the online User Guide \fIhttp://wiki\.rubyworks\.github\.com/detroit\fR for more details on creating toolchain files\.
+.
+.P
+Once a toolchain file is in place, the \fBdetroit\fR command line tool can be used to invoke the tools\. For example, to generate documentation:
+.
+.IP "" 4
+.
+.nf
+
+$ detroit document
+.
+.fi
+.
+.IP "" 0
+.
+.P
+This will run through all standard stations up to and including \fBdocument\fR\. Since the RDoc tool we configured above defines a document job, it would be run in due course\.
+.
+.SH "OPTIONS"
+These are the available options for the \fBdetroit\fR command line tool\.
+.
+.IP "\(bu" 4
+\fB\-m\fR, \fB\-\-multitask\fR Run work elements in parallel\.
+.
+.IP "\(bu" 4
+\fB\-S\fR, \fB\-\-skip=SERVICE\fR Skip a service\.
+.
+.IP "\(bu" 4
+\fB\-s\fR, \fB\-\-system=NAME\fR Select assembly system\. Default is \'standard\'\.
+.
+.IP "\(bu" 4
+\fB\-t\fR, \fB\-\-toolchain=FILE\fR Use specific toolchain file(s)\.
+.
+.IP "\(bu" 4
+\fB\-F\fR, \fB\-\-force\fR Force operations\.
+.
+.IP "\(bu" 4
+\fB\-\-trace\fR Run in TRACE mode\.
+.
+.IP "\(bu" 4
+\fB\-\-trial\fR Run in TRIAL mode (no disk writes)\.
+.
+.IP "\(bu" 4
+\fB\-\-verbose\fR Provide extra output\.
+.
+.IP "\(bu" 4
+\fB\-q\fR, \fB\-\-quiet\fR Run silently\.
+.
+.IP "\(bu" 4
+\fB\-I=PATH\fR Add directory to $LOAD_PATH
+.
+.IP "\(bu" 4
+\fB\-\-debug\fR Run with $DEBUG set to true\.
+.
+.IP "\(bu" 4
+\fB\-\-warn\fR Run with $VERBOSE set to true\.
+.
+.IP "\(bu" 4
+\fB\-\-help [TOOL]\fR Display this help message\.
+.
+.IP "\(bu" 4
+\fB\-c\fR, \fB\-\-config=TOOL\fR Produce a configuration template\.
+.
+.IP "" 0
+.
+.SH "RESOURCES"
+.
+.IP "\(bu" 4
+Homepage \fIhttp://rubyworks\.github\.com/detroit\fR
+.
+.IP "\(bu" 4
+Development \fIhttp://github\.com/rubyworks/detroit\fR
+.
+.IP "\(bu" 4
+Mailing List \fIhttp://googlegroups\.com/group/rubyworks\-mailinglist\fR
+.
+.IP "" 0
+.
+.SH "COPYRIGHT"
+Copyright (c) 2011 Rubyworks
+.
+.P
+Detroit is distributable in accordance with the terms of the GPL v3 license\.

data/man/detroit.1.html

@@ -0,0 +1,171 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv='content-type' value='text/html;charset=utf8'>
+  <meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'>
+  <title>detroit(1) - a life-cycle build tool</title>
+  <style type='text/css' media='all'>
+  /* style: man */
+  body#manpage {margin:0}
+  .mp {max-width:100ex;padding:0 9ex 1ex 4ex}
+  .mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
+  .mp h2 {margin:10px 0 0 0}
+  .mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
+  .mp h3 {margin:0 0 0 4ex}
+  .mp dt {margin:0;clear:left}
+  .mp dt.flush {float:left;width:8ex}
+  .mp dd {margin:0 0 0 9ex}
+  .mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
+  .mp pre {margin-bottom:20px}
+  .mp pre+h2,.mp pre+h3 {margin-top:22px}
+  .mp h2+pre,.mp h3+pre {margin-top:5px}
+  .mp img {display:block;margin:auto}
+  .mp h1.man-title {display:none}
+  .mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
+  .mp h2 {font-size:16px;line-height:1.25}
+  .mp h1 {font-size:20px;line-height:2}
+  .mp {text-align:justify;background:#fff}
+  .mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
+  .mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
+  .mp u {text-decoration:underline}
+  .mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
+  .mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
+  .mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
+  .mp b.man-ref {font-weight:normal;color:#434241}
+  .mp pre {padding:0 4ex}
+  .mp pre code {font-weight:normal;color:#434241}
+  .mp h2+pre,h3+pre {padding-left:0}
+  ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
+  ol.man-decor {width:100%}
+  ol.man-decor li.tl {text-align:left}
+  ol.man-decor li.tc {text-align:center;letter-spacing:4px}
+  ol.man-decor li.tr {text-align:right;float:right}
+  </style>
+</head>
+<!--
+  The following styles are deprecated and will be removed at some point:
+  div#man, div#man ol.man, div#man ol.head, div#man ol.man.
+
+  The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
+  .man-navigation should be used instead.
+-->
+<body id='manpage'>
+  <div class='mp' id='man'>
+
+  <div class='man-navigation' style='display:none'>
+    <a href="#NAME">NAME</a>
+    <a href="#DESCRIPTION">DESCRIPTION</a>
+    <a href="#USAGE">USAGE</a>
+    <a href="#OPTIONS">OPTIONS</a>
+    <a href="#RESOURCES">RESOURCES</a>
+    <a href="#COPYRIGHT">COPYRIGHT</a>
+  </div>
+
+  <ol class='man-decor man-head man head'>
+    <li class='tl'>detroit(1)</li>
+    <li class='tc'>Detroit</li>
+    <li class='tr'>detroit(1)</li>
+  </ol>
+
+  <h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>detroit</code> - <span class="man-whatis">a life-cycle build tool</span>
+</p>
+
+<h2 id="DESCRIPTION">DESCRIPTION</h2>
+
+<p>Detroit is a software production management aid. Detroit utilizes a
+life-cycle methodology to help developers prepare and release software
+in a clear, repeatable, linear fashion. While programmed in and well
+suited to Ruby projects, Detroit can utilized for any build requirements.</p>
+
+<h2 id="USAGE">USAGE</h2>
+
+<p>To utilize Detroit add a <code>Toolchain</code> file to your project's root directory.
+In this file add instantiation of tools, configured to your projects build
+requirements. Toolchain files can be written in YAML or Ruby.</p>
+
+<p>For example to generate RDoc's for a project, a tool might be defined:</p>
+
+<pre><code>rdoc:
+  tool: rdoc
+  files:
+    - lib
+    - '[A-Z]*.*'
+  main: README.md
+</code></pre>
+
+<p>See the online <a href="http://wiki.rubyworks.github.com/detroit">User Guide</a> for
+more details on creating toolchain files.</p>
+
+<p>Once a toolchain file is in place, the <code>detroit</code> command line tool can be used
+to invoke the tools. For example, to generate documentation:</p>
+
+<pre><code>$ detroit document
+</code></pre>
+
+<p>This will run through all standard stations up to and including <code>document</code>.
+Since the RDoc tool we configured above defines a document job, it would be
+run in due course.</p>
+
+<h2 id="OPTIONS">OPTIONS</h2>
+
+<p>These are the available options for the <code>detroit</code> command line tool.</p>
+
+<ul>
+<li><p><code>-m</code>, <code>--multitask</code>
+ Run work elements in parallel.</p></li>
+<li><p><code>-S</code>, <code>--skip=SERVICE</code>
+ Skip a service.</p></li>
+<li><p><code>-s</code>, <code>--system=NAME</code>
+ Select assembly system. Default is 'standard'.</p></li>
+<li><p><code>-t</code>, <code>--toolchain=FILE</code>
+ Use specific toolchain file(s).</p></li>
+<li><p><code>-F</code>, <code>--force</code>
+ Force operations.</p></li>
+<li><p><code>--trace</code>
+ Run in TRACE mode.</p></li>
+<li><p><code>--trial</code>
+ Run in TRIAL mode (no disk writes).</p></li>
+<li><p><code>--verbose</code>
+ Provide extra output.</p></li>
+<li><p><code>-q</code>, <code>--quiet</code>
+ Run silently.</p></li>
+<li><p><code>-I=PATH</code>
+Add directory to $LOAD_PATH</p></li>
+<li><p><code>--debug</code>
+ Run with $DEBUG set to true.</p></li>
+<li><p><code>--warn</code>
+ Run with $VERBOSE set to true.</p></li>
+<li><p><code>--help [TOOL]</code>
+ Display this help message.</p></li>
+<li><p><code>-c</code>, <code>--config=TOOL</code>
+ Produce a configuration template.</p></li>
+</ul>
+
+
+<h2 id="RESOURCES">RESOURCES</h2>
+
+<ul>
+<li><a href="http://rubyworks.github.com/detroit">Homepage</a></li>
+<li><a href="http://github.com/rubyworks/detroit">Development</a></li>
+<li><a href="http://googlegroups.com/group/rubyworks-mailinglist">Mailing List</a></li>
+</ul>
+
+
+<h2 id="COPYRIGHT">COPYRIGHT</h2>
+
+<p>Copyright (c) 2011 Rubyworks</p>
+
+<p>Detroit is distributable in accordance with the terms of the GPL v3 license.</p>
+
+
+  <ol class='man-decor man-foot man foot'>
+    <li class='tl'></li>
+    <li class='tc'>January 2014</li>
+    <li class='tr'>detroit(1)</li>
+  </ol>
+
+  </div>
+</body>
+</html>