rscons 1.7.0 → 1.8.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    Njg4YWQzOTg0NTU4OTRiYjBmZWJhYzY3ZjE0MDI4MWE1NGViZDc4Yg==
-  data.tar.gz: !binary |-
-    YzUyYWZiZjM5MjdmMDhkOTU2MjUzMTAwZmQ3NzY1ODkyOTljNmZjMA==
+SHA1:
+  metadata.gz: 73ee962711592bf9731373cf08ae929d64143511
+  data.tar.gz: 466f6cfd67e4179e000d20bd3ab7fba11299a754
 SHA512:
-  metadata.gz: !binary |-
-    ZDNiNTlmZDU5YTNmM2M3OWJmYThhNGIyNjg2NjE4NzljMTRlZTlhMWNhMzVl
-    MjQ5YWZmMjViYzZmNWVmZWQyNjM3YmNkZjBjMDJmMzhlMzMzYjcwMDlhOTdj
-    OWVjYTg4NDA1Zjg4Y2U2ODgwNjNlZjA5MzA4ZTkyOWQ2OTBhMWQ=
-  data.tar.gz: !binary |-
-    ODQ2MjEwOTYwMjQ3YTA5Y2U0MjA1MGZlMzM3Zjg2ODE2ZWRkM2ZlMWVhYTg4
-    NTE0Mzg3YzgwM2Y0YjNlZjcwZDliYzVjNTE5ZTI1NGQzYTRhMWFkYjZkODgx
-    YzM4ZTZiYzZjYmI5NTQ1OTVlY2ExOTg5ZTRiYWIyODkxZTNiZGY=
+  metadata.gz: 8e4828bfc224834dd5cf866964f4f9be9c7b24961b368dd10c3fbbe9324fa6a9c8686e28b679205a1522136fdbaa8dfdc4c13e3b2ccfbc2b447d9093cb34e9f6
+  data.tar.gz: cfa0f57a698be0db5b7513ef8d75bac39af2313cb1426056ee4c36ca150884789e152f5bf3eb3ab3faa3d68672e083c364cc38f0388379a06766252d4aa4e5aa

data/lib/rscons.rb

@@ -6,18 +6,21 @@ require_relative "rscons/varset"
 require_relative "rscons/version"
 
 # default builders
+require_relative "rscons/builders/command"
 require_relative "rscons/builders/cfile"
 require_relative "rscons/builders/disassemble"
 require_relative "rscons/builders/library"
 require_relative "rscons/builders/object"
 require_relative "rscons/builders/preprocess"
 require_relative "rscons/builders/program"
+require_relative "rscons/builders/simple_builder"
 
 # Namespace module for rscons classes
 module Rscons
   # Names of the default builders which will be added to all newly created
   # {Environment} objects.
   DEFAULT_BUILDERS = [
+    :Command,
     :CFile,
     :Disassemble,
     :Library,
@@ -30,6 +33,8 @@ module Rscons
   class BuildError < RuntimeError; end
 
   # Remove all generated files.
+  #
+  # @return [void]
   def self.clean
     cache = Cache.instance
     # remove all built files
@@ -118,6 +123,8 @@ module Rscons
   # Set the command executer array.
   #
   # @param val [Array<String>] Command used to execute commands.
+  #
+  # @return [Array<String>] Command used to execute commands.
   def self.command_executer=(val)
     @@command_executer = val
   end

data/lib/rscons/builder.rb

@@ -9,6 +9,8 @@ module Rscons
     # Return the name of the builder.
     #
     # If not overridden this defaults to the last component of the class name.
+    #
+    # @return [String] The name of the builder.
     def name
       self.class.name.split(":").last
     end
@@ -44,7 +46,7 @@ module Rscons
     # file name from a given source file name.
     #
     # @param target [String] The target file name.
-    # @param source [String, Array] The source file name(s).
+    # @param source [String] The source file name.
     # @param env [Environment] The Environment.
     #
     # @return [Boolean]
@@ -54,6 +56,20 @@ module Rscons
       false
     end
 
+    # Run the builder to produce a build target.
+    #
+    # @param target [String] Target file name.
+    # @param sources [Array<String>] Source file name(s).
+    # @param cache [Cache] The Cache object.
+    # @param env [Environment] The Environment executing the builder.
+    # @param vars [Hash,VarSet] Extra construction variables.
+    #
+    # @return [String,false]
+    #   Name of the target file on success or false on failure.
+    def run(target, sources, cache, env, vars)
+      raise "This method must be overridden in a subclass"
+    end
+
     # Check if the cache is up to date for the target and if not execute the
     # build command.
     #

data/lib/rscons/builders/command.rb

@@ -0,0 +1,32 @@
+module Rscons
+  module Builders
+    # Execute a command that will produce the given target based on the given
+    # sources.
+    #
+    # @since 1.8.0
+    #
+    # Example:
+    #   env.Command("docs.html", "docs.md",
+    #               CMD => %w[pandoc -fmarkdown -thtml -o${_TARGET} ${_SOURCES}])
+    class Command < Builder
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        vars = vars.merge({
+          "_TARGET" => target,
+          "_SOURCES" => sources,
+        })
+        command = env.build_command("${CMD}", vars)
+        standard_build("CMD #{target}", target, command, sources, env, cache)
+      end
+    end
+  end
+end

data/lib/rscons/builders/object.rb

@@ -62,7 +62,7 @@ module Rscons
       # file name from a given source file name.
       #
       # @param target [String] The target file name.
-      # @param source [String, Array] The source file name(s).
+      # @param source [String] The source file name.
       # @param env [Environment] The Environment.
       #
       # @return [Boolean]

data/lib/rscons/builders/simple_builder.rb

@@ -0,0 +1,39 @@
+module Rscons
+  module Builders
+    # A Generic builder class whose name and operation is defined at
+    # instantiation.
+    #
+    # @since 1.8.0
+    class SimpleBuilder < Builder
+      # @return [String] The name of this builder.
+      attr_reader :name
+
+      # Create a new builder with the given name and action.
+      #
+      # @param name  [String,Symbol] The name of the builder when registered.
+      # @param block [Block]
+      #   The action to perform when the builder is processed. The provided
+      #   block must return the target file on success or false on failure.
+      #   The provided block should have the same signature as {Builder#run}.
+      def initialize(name, &block)
+        @name  = name.to_s
+        @block = block
+      end
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        @block.call(target, sources, cache, env, vars)
+      end
+    end
+  end
+end
+

data/lib/rscons/cache.rb

@@ -63,17 +63,23 @@ module Rscons
     end
 
     # Remove the cache file.
+    #
+    # @return [void]
     def clear
       FileUtils.rm_f(CACHE_FILE)
       initialize!
     end
 
     # Clear the cached file checksums.
+    #
+    # @return [void]
     def clear_checksum_cache!
       @lookup_checksums = {}
     end
 
     # Write the cache to disk to be loaded next time.
+    #
+    # @return [void]
     def write
       if @dirty || (@cache["version"] != VERSION)
         @cache["version"] = VERSION
@@ -86,9 +92,14 @@ module Rscons
 
     # Check if target(s) are up to date.
     #
-    # @param targets [String, Array] The name(s) of the target file(s).
-    # @param command [String, Array] The command used to build the target.
-    # @param deps [Array] List of the target's dependency files.
+    # @param targets [String, Array<String>] The name(s) of the target file(s).
+    # @param command [String, Array, Hash]
+    #   The command used to build the target. The command parameter can
+    #   actually be a String, Array, or Hash and could contain information
+    #   other than just the actual command used to build the target. For the
+    #   purposes of the Cache, any difference in the command argument will
+    #   trigger a rebuild.
+    # @param deps [Array<String>] List of the target's dependency files.
     # @param env [Environment] The Rscons::Environment.
     # @param options [Hash] Optional options.
     # @option options [Boolean] :strict_deps
@@ -148,9 +159,14 @@ module Rscons
 
     # Store cache information about target(s) built by a builder.
     #
-    # @param targets [String, Array] The name of the target(s) built.
-    # @param command [String, Array] The command used to build the target.
-    # @param deps [Array] List of dependencies for the target.
+    # @param targets [String, Array<String>] The name of the target(s) built.
+    # @param command [String, Array, Hash]
+    #   The command used to build the target. The command parameter can
+    #   actually be a String, Array, or Hash and could contain information
+    #   other than just the actual command used to build the target. For the
+    #   purposes of the Cache, any difference in the command argument will
+    #   trigger a rebuild.
+    # @param deps [Array<String>] List of dependencies for the target.
     # @param env [Environment] The {Rscons::Environment}.
     #
     # @return [void]

data/lib/rscons/environment.rb

@@ -10,7 +10,7 @@ module Rscons
     # @return [Hash] Set of !{"builder_name" => builder_object} pairs.
     attr_reader :builders
 
-    # :command, :short, or :off
+    # @return [Symbol] :command, :short, or :off
     attr_accessor :echo
 
     # @return [String, nil] The build root.
@@ -79,7 +79,7 @@ module Rscons
     #
     # Any options that #initialize receives can also be specified here.
     #
-    # @return a new {Environment} object.
+    # @return [Environment] The newly created {Environment} object.
     def clone(options = {})
       clone = options[:clone] || Set[:variables, :builders]
       clone = Set[:variables, :builders, :build_root, :build_dirs, :build_hooks] if clone == :all
@@ -120,10 +120,32 @@ module Rscons
 
     # Add a {Builder} object to the Environment.
     #
-    # @param builder [Builder] The {Builder} object to add.
+    # @overload add_builder(builder)
+    #
+    #   Add the given builder to the Environment.
+    #
+    #   @param builder [Builder] An instance of the builder to register.
+    #
+    # @overload add_builder(builder,&action)
+    #
+    #   Create a new {Builders::SimpleBuilder} instance and add it to the
+    #   environment.
+    #
+    #   @since 1.8.0
+    #
+    #   @param builder [String,Symbol]
+    #     The name of the builder to add.
+    #
+    #   @param action [Block]
+    #     A block that will be called when the builder is executed to generate
+    #     a target file. The provided block should have the same prototype as
+    #     {Rscons::Builder#run}.
     #
     # @return [void]
-    def add_builder(builder)
+    def add_builder(builder, &action)
+      if not builder.is_a? Rscons::Builder
+        builder = Rscons::Builders::SimpleBuilder.new(builder, &action)
+      end
       @builders[builder.name] = builder
       var_defs = builder.default_variables(self)
       if var_defs
@@ -184,8 +206,13 @@ module Rscons
     #
     # Source files from src_dir will produce object files under obj_dir.
     #
-    # @param src_dir [String, Regexp] Path to the source directory.
-    # @param obj_dir [String] Path to the object directory.
+    # @param src_dir [String, Regexp]
+    #   Path to the source directory. If a Regexp is given, it will be matched
+    #   to source file names.
+    # @param obj_dir [String]
+    #   Path to the object directory. If a Regexp is given as src_dir, then
+    #   obj_dir can contain backreferences to groups matched from the source
+    #   file name.
     #
     # @return [void]
     def build_dir(src_dir, obj_dir)
@@ -223,25 +250,27 @@ module Rscons
       build_fname
     end
 
-    # Access a construction variable or environment option.
+    # Get a construction variable's value.
     #
     # @see VarSet#[]
     def [](*args)
       @varset.send(:[], *args)
     end
 
-    # Set a construction variable or environment option.
+    # Set a construction variable's value.
     #
     # @see VarSet#[]=
     def []=(*args)
       @varset.send(:[]=, *args)
     end
 
-    # Add a set of construction variables or environment options.
+    # Add a set of construction variables to the Environment.
     #
-    # @see VarSet#append
-    def append(*args)
-      @varset.append(*args)
+    # @param values [VarSet, Hash] New set of variables.
+    #
+    # @return [void]
+    def append(values)
+      @varset.append(values)
     end
 
     # Build all build targets specified in the Environment.
@@ -287,6 +316,8 @@ module Rscons
     end
 
     # Clear all targets registered for the Environment.
+    #
+    # @return [void]
     def clear_targets
       @targets = {}
     end
@@ -410,8 +441,9 @@ module Rscons
     #
     # This method is used internally by Rscons builders.
     #
-    # @param sources [Array] List of source files to build.
-    # @param suffixes [Array] List of suffixes to try to convert source files into.
+    # @param sources [Array<String>] List of source files to build.
+    # @param suffixes [Array<String>]
+    #   List of suffixes to try to convert source files into.
     # @param cache [Cache] The Cache.
     # @param vars [Hash] Extra variables to pass to the builder.
     #
@@ -440,7 +472,7 @@ module Rscons
     #
     # @param builder [Builder] The Builder to use.
     # @param target [String] The target output file.
-    # @param sources [Array] List of source files.
+    # @param sources [Array<String>] List of source files.
     # @param cache [Cache] The Cache.
     # @param vars [Hash] Extra variables to pass to the builder.
     #
@@ -506,10 +538,10 @@ module Rscons
     # Parse command-line flags for compilation/linking options into separate
     # construction variables.
     #
-    # The parsed construction variables are returned in a Hash instead of
-    # merging them directly to the Environment. They can be merged with
-    # {#merge_flags}. The {#parse_flags!} version immediately merges the parsed
-    # flags as well.
+    # For {#parse_flags}, the parsed construction variables are returned in a
+    # Hash instead of merging them directly to the Environment. They can be
+    # merged with {#merge_flags}. The {#parse_flags!} version immediately
+    # merges the parsed flags as well.
     #
     # Example:
     #   # Import FreeType build options
@@ -628,6 +660,13 @@ module Rscons
       end
     end
 
+    # Print the Environment's construction variables for debugging.
+    def dump
+      @varset.to_h.sort.each do |var, val|
+        puts "#{var} => #{val.inspect}"
+      end
+    end
+
     private
 
     # Expand target and source paths before invoking builders.

data/lib/rscons/varset.rb

@@ -58,7 +58,7 @@ module Rscons
     #
     # @param values [VarSet, Hash] New set of variables.
     #
-    # @return [self]
+    # @return [VarSet] Returns self.
     def append(values)
       coa!
       if values.is_a?(VarSet)
@@ -121,6 +121,26 @@ module Rscons
       end
     end
 
+    # Return a Hash containing all variables in the VarSet.
+    #
+    # @since 1.8.0
+    #
+    # This method is not terribly efficient. It is intended to be used only by
+    # debugging code to dump out a VarSet's variables.
+    #
+    # @return [Hash] All variables in the VarSet.
+    def to_h
+      result = deep_dup(@my_vars)
+      @coa_vars.reduce(result) do |result, coa_vars|
+        coa_vars.each_pair do |key, value|
+          unless result.include?(key)
+            result[key] = deep_dup(value)
+          end
+        end
+        result
+      end
+    end
+
     private
 
     # Move all VarSet variables into the copy-on-access list.

data/lib/rscons/version.rb

@@ -1,4 +1,4 @@
 module Rscons
   # gem version
-  VERSION = "1.7.0"
+  VERSION = "1.8.0"
 end

data/rscons.gemspec

@@ -24,5 +24,6 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "rake"
   gem.add_development_dependency "simplecov"
   gem.add_development_dependency "yard"
+  gem.add_development_dependency "rdoc"
   gem.add_development_dependency "redcarpet"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rscons
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Josh Holtrop
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-25 00:00:00.000000000 Z
+date: 2014-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -28,70 +28,84 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Software construction library inspired by SCons and implemented in Ruby.
@@ -106,11 +120,13 @@ files:
 - lib/rscons/build_target.rb
 - lib/rscons/builder.rb
 - lib/rscons/builders/cfile.rb
+- lib/rscons/builders/command.rb
 - lib/rscons/builders/disassemble.rb
 - lib/rscons/builders/library.rb
 - lib/rscons/builders/object.rb
 - lib/rscons/builders/preprocess.rb
 - lib/rscons/builders/program.rb
+- lib/rscons/builders/simple_builder.rb
 - lib/rscons/cache.rb
 - lib/rscons/environment.rb
 - lib/rscons/varset.rb
@@ -126,17 +142,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.3.0
+rubygems_version: 2.4.1
 signing_key: 
 specification_version: 4
 summary: Software construction library inspired by SCons and implemented in Ruby