rubu 0.0.1 → 0.0.2

data/doc/top-level-namespace.html

@@ -105,7 +105,7 @@
 </div>
 
     <div id="footer">
-  Generated on Fri Jun 29 10:04:07 2018 by
+  Generated on Sun Jul  1 17:48:17 2018 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-2.3.3).
 </div>

data/example/bin/rubu_example

@@ -13,7 +13,7 @@ Spec.command( 'rubu_example', 'Tero Isannainen', '2018',
         [ :opt_multi, 'conf',    '-c', "Configuration option." ],
         [ :switch,    'verbose', '-v', "Verbose." ],
         [ :switch,    'serial',  '-s', "Serial execution." ],
-        [ :default,    nil,       nil, "Flow(s) to execute." ],
+        [ :default,    nil,       nil, "Trail(s) to execute." ],
     ] )
 
 
@@ -21,7 +21,7 @@ Spec.command( 'rubu_example', 'Tero Isannainen', '2018',
 # ------------------------------------------------------------
 # Build specific definitions:
 
-# Set flow related options.
+# Set trail related options.
 Var[ :bin_dir ]    = 'bin'
 Var[ :source_dir ] = 'src'
 Var[ :build_dir ]  = 'build'
@@ -36,7 +36,31 @@ if Opt['verbose'].given
 end
 
 # Read setup files and apply Como command line arguments to Var space.
-Flow.setup( :como => 'conf' )
+Trail.setup( :como => 'conf' )
+
+
+# ------------------------------------------------------------
+# Collect sources and create targets:
+
+# Generator file and the target.
+gen_file      = Mark.path( "#{Var[:bin_dir]}/gen_world" )
+gen_cee_file  = Mark.path( "#{Var[:build_dir]}/world.c" )
+
+# Collect "normal" C files.
+cee_files     = Mark.glob( "#{Var[:source_dir]}/*.c" )
+
+# Create complete list of all C files.
+all_cee_files = [ gen_cee_file ] + cee_files
+
+# Convert C files to corresponding Object files.
+obj_files     = all_cee_files.peer( Var[ :build_dir ], '.o' )
+
+# Specify executable file.
+exe_file      = Mark.path( Var[ :exe_name ] )
+
+
+# Generate execution time information to Info. Used by CleanObjects.
+Info[ :gen_files ] = [ gen_cee_file ]
 
 
 
@@ -44,15 +68,15 @@ Flow.setup( :como => 'conf' )
 # Build Commands:
 
 # Code generator with generated file dependency.
-class GenWorld < MarkBuild
-    def build
+class GenWorld < Step
+    def step
         shrun "bin/gen_world"
     end
 end
 
 
 # Typical C compilation with GCC, from source to object.
-class GccCompileFile < DateBuild
+class GccCompileFile < StepAged
 
     def setup
         @cmd = "gcc -Wall -I #{Var[:source_dir]} -c #{source.rpath} -o #{target.rpath}"
@@ -65,36 +89,36 @@ class GccCompileFile < DateBuild
         end
     end
 
-    def build
+    def step
         shrun @cmd
     end
 end
 
 
 # GCC linking.
-class GccLinkExe < DateBuild
+class GccLinkExe < StepAged
 
     def setup
         @cmd  = "gcc #{sources.rpath} -o #{target.rpath}"
     end
 
-    def build
+    def step
         shrun @cmd
     end
 end
 
 
 # Cleaning.
-class CleanObjects < Build
+class CleanObjects < Step
 
-    def build
+    def step
         # Multiple jobs are grouped with walk (serial execution).
         walk do
-            shdef "rm -f #{Info[ :gen_files ].rpath}"
-            shdef "rm -f #{Var[ :build_dir ]}/*.o"
+            shuse "rm -f #{Info[ :gen_files ].rpath}"
+            shuse "rm -f #{Var[ :build_dir ]}/*.o"
 
             # Use Ruby for deleting the exe as an example.
-            rbdef "rm -f #{Var[ :exe_name ]}" do
+            rbuse "rm -f #{Var[ :exe_name ]}" do
                 FileUtils.rm_f Var[ :exe_name ]
             end
         end
@@ -102,36 +126,10 @@ class CleanObjects < Build
 end
 
 
-
-# ------------------------------------------------------------
-# Collect sources and create targets:
-
-# Generator file and the target.
-gen_file      = Mark.path( "#{Var[:bin_dir]}/gen_world" )
-gen_cee_file  = Mark.path( "#{Var[:build_dir]}/world.c" )
-
-# Collect "normal" C files.
-cee_files     = Mark.glob( "#{Var[:source_dir]}/*.c" )
-
-# Create list of all C files.
-all_cee_files = [ gen_cee_file ] + cee_files
-
-# Convert C files to corresponding Object files.
-obj_files     = all_cee_files.peer( Var[ :build_dir ], '.o' )
-
-# Specify executable file.
-exe_file      = Mark.path( Var[ :exe_name ] )
-
-
-# Generate execution time information to Info. Used by CleanObjects.
-Info[ :gen_files ] = [ gen_cee_file ]
-
-
-
 # ------------------------------------------------------------
-# Define flows:
+# Define trails:
 
-# Serial flow for code generation.
+# Serial trail for code generation.
 Walk.form 'gen-cee' do
     # Create GenWorld build and register it to 'gen-cee'.
     GenWorld.use( gen_file, gen_cee_file )
@@ -144,17 +142,17 @@ Fork.form 'compile-cee' do
     GccCompileFile.usezip( all_cee_files, obj_files )
 end
 
-# Default flow, i.e. generate, compile, link to executable.
+# Default trail, i.e. generate, compile, link to executable.
 Walk.form 'default' do
-    # Reference 'gen-cee' flow.
+    # Reference 'gen-cee' trail.
     pick 'gen-cee'
-    # Reference 'compile-cee' flow.
+    # Reference 'compile-cee' trail.
     pick 'compile-cee'
     # Create GCC link build and register it.
     GccLinkExe.use( obj_files, exe_file )
 end
 
-# Cleaner flow.
+# Cleaner trail.
 Walk.form 'clean' do
     CleanObjects.use
 end
@@ -162,17 +160,17 @@ end
 
 
 # ------------------------------------------------------------
-# Run selected flows:
+# Run selected trails:
 
-flows = nil
+trails = nil
 if Opt[ nil ].given
-    flows = Opt[ nil ].value
+    trails = Opt[ nil ].value
 else
-    flows = [ 'default' ]
+    trails = [ 'default' ]
 end
 
 if Opt[ 'serial' ].given
     Order[ :serial ] = true
 end
 
-Flow.run( flows )
+Trail.run( trails )

data/example/build/world.c

@@ -0,0 +1,6 @@
+#include <stdio.h>
+
+void print_world( void )
+{
+    printf( "World" );
+}

data/lib/rubu.rb

@@ -5,27 +5,39 @@ require 'digest/md5'
 
 module Rubu
 
+    # Persistent state of Rubu.
+    #
+    # State maintains YAML based state file (if in use). The file
+    # include MD5 checksums of file content.
     class State
 
         @@md5 = {}
         @@state_file = ".rubu_state.yml"
 
+        # Save state.
         def State.save
             if @@md5.any?
                 IO.write( @@state_file, YAML.dump( @@md5 ) )
             end
         end
 
+        # Load state.
         def State.load
             if File.exist?( @@state_file )
                 @@md5 = YAML.load_file( @@state_file )
             end
         end
 
+        # Generate MD5 checksum for file.
+        #
+        # @param file File.
         def State.md5_gen( file )
             Digest::MD5.hexdigest( File.read( file ) )
         end
 
+        # Check for existing checksum and update it if needed.
+        #
+        # @param file File.
         def State.md5_check_and_update?( file )
             if @@md5[ file ]
                 md5 = State.md5_gen( file )
@@ -43,8 +55,8 @@ module Rubu
     end
 
 
-    # Build activity.
-    class Action
+    # Move is the action in Step.
+    class Move
 
         @@host = []
 
@@ -68,23 +80,18 @@ module Rubu
             @subs = []
         end
 
-        # Register Action to host (upper level).
+        # Register Move to host (upper level).
         def use
             host.subs.push( self ) if host
             self
         end
 
-        # Take flow into use.
-        def pick( flow )
-            Flow[ flow ].use
-        end
-
-        # Push host.
+        # Push host as current to host stack.
         def host_in
             @@host.push self
         end
 
-        # Pop host.
+        # Pop host from host stack.
         def host_out
             @@host.pop
         end
@@ -110,13 +117,14 @@ module Rubu
 
 
     # Shell based command.
-    class ShellCommand < Action
+    class ShellCommand < Move
 
         def initialize( cmd )
             super()
             @cmd = cmd
         end
 
+        # Execution content.
         def run
             begin
                 stdout, stderr, status = Open3.capture3( @cmd )
@@ -145,7 +153,7 @@ module Rubu
 
 
     # Ruby based command.
-    class RubyCommand < Action
+    class RubyCommand < Move
 
         def initialize( desc = nil, &cmd )
             super()
@@ -153,6 +161,7 @@ module Rubu
             @cmd = cmd
         end
 
+        # Execution content.
         def run
             begin
                 ret = instance_eval( &@cmd )
@@ -170,9 +179,10 @@ module Rubu
     end
 
 
-    # Flow execution methods.
-    module FlowRun
+    # Trail/Step execution styles.
+    module MoveStyles
 
+        # Run @subs in sequence.
         def serial_run
             @subs.each do |sub|
                 sub.run
@@ -186,6 +196,7 @@ module Rubu
             self
         end
 
+        # Run @subs in parallel (unless serial is forced).
         def parallel_run
 
             if Order[ :serial ]
@@ -252,11 +263,27 @@ module Rubu
     end
 
 
-    # Source or Target file for build commands. Rubu handles only
+    # Source or Target file for Step commands. Rubu handles only
     # Marks, and hence bare file names are not usable.
+    #
+    # Mark includes both relative and absolute paths for the file.
     class Mark
 
+        # Convert file path to Mark.
+        #
+        # @param file_path Relative or absolute path of file.
+        def Mark.path( file_path )
+            path = File.absolute_path( file_path )
+            dir = File.dirname( path ).split( '/' )
+            rdir = dir - Dir.pwd.split( '/' )
+            ext = File.extname( path )
+            base = File.basename( path, ext )
+            Mark.new( rdir, base, ext )
+        end
+
         # Convert a list of file names to Marks.
+        #
+        # @param files List of files to convert to Marks.
         def Mark.list( files )
             unless files.kind_of? Array
                 files = [ files ]
@@ -264,21 +291,14 @@ module Rubu
             files.map{ |file| Mark.path( file ) }
         end
 
-        # Convert a list of file names matched with pattern to Marks.
+        # Convert a list of file names matched with glob pattern to
+        # Marks.
+        #
+        # @param pattern Glob pattern.
         def Mark.glob( pattern )
             Mark.list( Dir.glob( pattern ) )
         end
 
-        # Convert file path to Mark.
-        def Mark.path( file_path )
-            path = File.absolute_path( file_path )
-            dir = File.dirname( path ).split( '/' )
-            rdir = dir - Dir.pwd.split( '/' )
-            ext = File.extname( path )
-            base = File.basename( path, ext )
-            Mark.new( rdir, base, ext )
-        end
-
 
         # Absolute directory.
         attr_reader :dir
@@ -292,10 +312,15 @@ module Rubu
         # File extension.
         attr_reader :ext
 
-        # Skip file.
+        # Skip file in Step.
         attr_accessor :skip
 
 
+        # Create Mark object.
+        #
+        # @param rdir Relative file path.
+        # @param base Basename of file.
+        # @param ext  File extension (suffix).
         def initialize( rdir, base, ext )
             if rdir.kind_of? Array
                 @dir = File.absolute_path( rdir.join( '/' ) ).split( '/' )
@@ -310,35 +335,41 @@ module Rubu
             @skip = false
         end
 
-        # Get options.
+        # Get options with key.
         def []( key )
             @opt[ key ]
         end
 
-        # Set options.
+        # Set option.
         def []=( key, val )
             @opt[ key ] = val
         end
 
-        # Set options.
+        # Set option.
         def set_opt( key, val )
             @opt[ key ] = val
             self
         end
 
         # Return absolute path.
-        def path( ext = nil )
-            ext ||= @ext
+        #
+        # @param ext Use this extensions instead, if given.
+        def path( ext = @ext )
             "#{@dir.join('/')}/#{@base}#{ext}"
         end
 
         # Return relative path.
-        def rpath( ext = nil )
-            ext ||= @ext
+        #
+        # @param ext Use this extensions instead, if given.
+        def rpath( ext = @ext )
             "#{@rdir.join('/')}/#{@base}#{ext}"
         end
 
         # Return peer of Mark.
+        #
+        # @param rdir Relative path of peer.
+        # @param ext  Extension of peer.
+        # @param base Optional basename of peer (use original if not given).
         def peer( rdir, ext, base = nil )
             base ||= @base
             Mark.new( rdir, base, ext )
@@ -349,7 +380,7 @@ module Rubu
             File.exist?( path )
         end
 
-        # Mark creation time.
+        # Mark update time.
         def time
             File.stat( path ).mtime
         end
@@ -362,10 +393,12 @@ module Rubu
 
         @@order = {}
 
+        # Set Order entry value.
         def Order.[]=( key, val )
             @@order[ key ] = val
         end
 
+        # Get Order entry value.
         def Order.[]( key )
             @@order[ key ]
         end
@@ -373,7 +406,7 @@ module Rubu
 
         # Order defaults:
 
-        # Force serial flow.
+        # Force serial trail.
         Order[ :serial ] = false
 
         # Maximun parallel runs (0 for no limit).
@@ -390,10 +423,12 @@ module Rubu
 
         @@var = {}
 
+        # Set Var entry value.
         def Var.[]=( key, val )
             @@var[ key ] = val
         end
 
+        # Get Var entry value.
         def Var.[]( key )
             @@var[ key ]
         end
@@ -406,10 +441,12 @@ module Rubu
 
         @@info = {}
 
+        # Set Info entry value.
         def Info.[]=( key, val )
             @@info[ key ] = val
         end
 
+        # Get Info entry value.
         def Info.[]( key )
             @@info[ key ]
         end
@@ -417,18 +454,24 @@ module Rubu
     end
 
 
-    # Build Action. Build Action takes one or more sources, and turns
+    # Step in Trail. Step takes one or more sources, and turns
     # them into one or more targets.
-    class Build < Action
+    class Step < Move
 
-        include FlowRun
+        include MoveStyles
 
-        # Create Action and register.
+        # Create Move and register.
+        #
+        # @param sources One or more sources.
+        # @param targets One or more targets.
         def self.use( sources = [], targets = [] )
             self.new( sources, targets ).use
         end
 
         # Combine list of sources and targets to source/target pairs.
+        #
+        # @param sources List of sources.
+        # @param targets List of targets.
         def self.zip( sources, targets )
             sources.zip( targets ).map do |pair|
                 self.new( *pair )
@@ -437,6 +480,9 @@ module Rubu
 
         # Combine list of sources and targets to source/target pairs
         # and register.
+        #
+        # @param sources List of sources.
+        # @param targets List of targets.
         def self.usezip( sources, targets )
             sources.zip( targets ).map do |pair|
                 self.new( *pair ).use
@@ -447,6 +493,10 @@ module Rubu
         attr_reader :sources
         attr_reader :targets
 
+        # Create Step object.
+        #
+        # @param sources One or more sources.
+        # @param targets One or more targets.
         def initialize( sources = [], targets = [] )
             super()
 
@@ -466,15 +516,16 @@ module Rubu
         end
 
 
-        # Defined by users.
+        # Setup variables for Step. Should be defined again in derived
+        # classes.
         def setup
         end
 
 
-        # Run Build Action and capture status.
+        # Run Step and capture status.
         def run
             if update?
-                build
+                step
             else
                 @status = :success
             end
@@ -482,7 +533,7 @@ module Rubu
         end
 
 
-        # Default update.
+        # Default update. Should be defined again in derived classes.
         def update?
             true
         end
@@ -532,7 +583,7 @@ module Rubu
 
             old_verbose = Order[ :verbose ]
             Order[ :verbose ] = false
-            build
+            step
             Order[ :verbose ] = old_verbose
 
             unless target.exist?
@@ -549,12 +600,12 @@ module Rubu
         end
 
 
-        # Main (first) source file.
+        # Main/only (first) source file.
         def source
             @sources[0]
         end
 
-        # Main (first) target file.
+        # Main/only (first) target file.
         def target
             @targets[0]
         end
@@ -565,23 +616,27 @@ module Rubu
         end
 
         # Define and register Shell command.
-        def shdef( cmd )
+        def shuse( cmd )
             sh = ShellCommand.new( cmd )
             sh.use
         end
 
         # Define and run Ruby command.
+        #
+        # @param desc Optional description for :verbose mode.
         def rbrun( desc = nil, &cmd )
             RubyCommand.new( desc, &cmd ).run
         end
 
         # Define and register Ruby command.
-        def rbdef( desc = nil, &cmd )
+        #
+        # @param desc Optional description for :verbose mode.
+        def rbuse( desc = nil, &cmd )
             rb = RubyCommand.new( desc, &cmd )
             rb.use
         end
 
-        # Execute commands (in block) in parallel.
+        # Execute commands (from block) in parallel.
         def fork( &blk )
             host_in
             instance_eval &blk
@@ -589,7 +644,7 @@ module Rubu
             parallel_run
         end
 
-        # Execute commands (in block) in series.
+        # Execute commands (from block) in sequence.
         def walk( &blk )
             host_in
             instance_eval &blk
@@ -599,54 +654,59 @@ module Rubu
     end
 
 
-    # Uncondition build.
-    class AlwaysBuild < Build
+    # Unconditional Step.
+    class StepAlways < Step
+        # Update without conditions.
         def update?
             true
         end
     end
 
 
-    # Date based build.
-    class DateBuild < Build
+    # Date based Step.
+    class StepAged < Step
+        # Update if Step source is newer than target.
         def update?
             date_update?
         end
     end
 
 
-    # Mark based build.
-    class MarkBuild < Build
+    # Mark (checksum) based Step.
+    class StepMark < Step
+        # Update if target generated from Step source is different
+        # from old target.
         def update?
             mark_update?
         end
     end
 
 
-    # Action Flow with name. Action Flow is a collection of build
-    # steps.
-    class Flow < Action
+    # Trail with name. Trail is a collection of Steps and/or Trails.
+    class Trail < Move
 
-        include FlowRun
+        include MoveStyles
 
-        # Flow hash.
-        @@flows = {}
+        # Trail hash.
+        @@trails = {}
 
 
-        # Replacement for new method.
+        # Replacement (alias) for new method.
         def self.form( name = nil, &blk )
             self.new( name, &blk )
         end
 
 
-        # Reference Flow by name.
+        # Reference Trail by name.
         def self.[]( name )
-            @@flows[ name ]
+            @@trails[ name ]
         end
 
 
         attr_reader :name
 
+        # Create Trail object. Named Trails are registered and can be
+        # referenced later.
         def initialize( name = nil, &blk )
             super()
             @name = name
@@ -654,20 +714,28 @@ module Rubu
             instance_eval &blk
             host_out
             if @name
-                @@flows[ @name ] = self
+                @@trails[ @name ] = self
             end
         end
 
-        # Default run style for Flow.
+
+        # Take trail into use.
+        def pick( trail )
+            Trail[ trail ].use
+        end
+
+
+        # Default run style for Trail.
         def run
             serial_run
         end
 
-        def Flow.load_setup( setup )
+        # Load a setup file.
+        def Trail.load_setup( setup_file )
 
-            if File.exist? setup
+            if File.exist? setup_file
 
-                conf = YAML.load_file( setup )
+                conf = YAML.load_file( setup_file )
 
                 conf.each do |k,v|
 
@@ -686,12 +754,16 @@ module Rubu
             end
         end
 
-        # Apply configuration options if any.
-        def Flow.setup( spec )
 
-            load_setup( "#{ENV['HOME']}/.rubu.yml" )
-            load_setup( ENV['RUBU_CONF'] ) if ENV['RUBU_CONF']
-            load_setup( ".rubu.yml" )
+        # Apply configuration options and command parameters, if any,
+        # to Rubu.
+        #
+        # @param spec Hash of options for setup.
+        def Trail.setup( spec )
+
+            Trail.load_setup( "#{ENV['HOME']}/.rubu.yml" )
+            Trail.load_setup( ENV['RUBU_CONF'] ) if ENV['RUBU_CONF']
+            Trail.load_setup( ".rubu.yml" )
 
             State.load
 
@@ -713,14 +785,20 @@ module Rubu
 
         end
 
-        # Run selected flow(s).
-        def Flow.run( flows )
+        # Run selected trail(s).
+        #
+        # @param trails List of Trails to run.
+        def Trail.run( trails = 'default' )
+
+            unless trails.kind_of? Array
+                trails = [ trails ]
+            end
 
-            flows.each do |name|
+            trails.each do |name|
 
                 begin
 
-                    ret = Flow[ name ].run
+                    ret = Trail[ name ].run
                     if ret.status == :error
                         STDERR.puts "Rubu FAILURE..."
                         exit false
@@ -728,7 +806,7 @@ module Rubu
 
                 rescue
 
-                    STDERR.puts "Broken flow: \"#{name}\"..."
+                    STDERR.puts "Broken trail: \"#{name}\"..."
                     exit false
 
                 end
@@ -743,12 +821,12 @@ module Rubu
     end
 
 
-    # Serial Flow.
-    class Walk < Flow; end
+    # Serial Trail.
+    class Walk < Trail; end
 
 
-    # Parallel Flow.
-    class Fork < Flow
+    # Parallel Trail.
+    class Fork < Trail
         def run
             parallel_run
         end
@@ -760,12 +838,14 @@ end
 # Array class extension to support common Mark operations.
 class Array
 
+    # Array version of Move#use.
     def use
         self.each do |item|
             item.use
         end
     end
 
+    # Array version of Mark#set_opt.
     def set_opt( key, val )
         self.each do |item|
             item.set_opt( key, val )
@@ -773,16 +853,19 @@ class Array
         self
     end
 
+    # Array version of Mark#peer.
     def peer( rdir, ext, base = nil )
         self.map do |item|
             item.peer( rdir, ext, base )
         end
     end
 
+    # Array version of Mark#path.
     def path( joiner = ' ' )
         self.map{ |item| item.path }.join( joiner )
     end
 
+    # Array version of Mark#rpath.
     def rpath( joiner = ' ' )
         self.map{ |item| item.rpath }.join( joiner )
     end