v1.4.0

update README.md for v1.4.0 release notes
shortcut all of Environment#process if @targets is empty
2014-04-15 16:19:19 -04:00 · 2014-04-15 16:18:58 -04:00 · 2014-04-15 16:18:33 -04:00 · 2014-04-15 16:06:00 -04:00 · 2014-04-15 15:21:55 -04:00 · 2014-04-15 14:20:30 -04:00
22 changed files with 1200 additions and 367 deletions
@@ -12,7 +12,7 @@ Add this line to your application's Gemfile:

 And then execute:

-    $ bundle
+    $ bundle install

 Or install it yourself as:

@@ -27,7 +27,7 @@ called from your Rakefile.
 ### Example: Building a C Program

 ```ruby
-RScons::Environment.new do |env|
+Rscons::Environment.new do |env|
  env["CFLAGS"] << "-Wall"
  env.Program("program", Dir["**/*.c"])
 end
@@ -36,7 +36,7 @@ end
 ### Example: Building a D Program

 ```ruby
-RScons::Environment.new do |env|
+Rscons::Environment.new do |env|
  env["DFLAGS"] << "-Wall"
  env.Program("program", Dir["**/*.d"])
 end
@@ -45,7 +45,7 @@ end
 ### Example: Cloning an Environment

 ```ruby
-main_env = RScons::Environment.new do |env|
+main_env = Rscons::Environment.new do |env|
  # Store object files from sources under "src" in "build/main"
  env.build_dir("src", "build/main")
  env["CFLAGS"] = ["-DSOME_DEFINE", "-O3"]
@@ -64,23 +64,96 @@ end

 ### Example: Custom Builder

+Custom builders are implemented as classes which extend from `Rscons::Builder`.
+The builder must have a `run` method which is called to invoke the builder.
+The `run` method should return the name of the target built on success, and
+`false` on failure.
+
 ```ruby
 class GenerateFoo < Rscons::Builder
  def run(target, sources, cache, env, vars)
+    cache.mkdir_p(File.dirname(target))
    File.open(target, "w") do |fh|
      fh.puts <<EOF
 #define GENERATED 42
 EOF
    end
+    target
  end
 end

 Rscons::Environment.new do |env|
+  env.add_builder(GenerateFoo.new)
  env.GenerateFoo("foo.h", [])
  env.Program("a.out", Dir["*.c"])
 end
 ```

+### Example: Custom Builder That Only Regenerates When Necessary
+
+```ruby
+class CmdBuilder < Rscons::Builder
+  def run(target, sources, cache, env, vars)
+    cmd = ["cmd", "-i", sources.first, "-o", target]
+    unless cache.up_to_date?(target, cmd, sources, env)
+      cache.mkdir_p(File.dirname(target))
+      system(cmd)
+      cache.register_build(target, cmd, sources, env)
+    end
+    target
+  end
+end
+
+Rscons::Environment.new do |env|
+  env.add_builder(CmdBuilder.new)
+  env.CmdBuilder("foo.gen", "foo_gen.cfg")
+end
+```
+
+### Example: Custom Builder That Generates Multiple Output Files
+
+```ruby
+class CModuleGenerator < Rscons::Builder
+  def run(target, sources, cache, env, vars)
+    c_fname = target
+    h_fname = target.sub(/\.c$/, ".h")
+    cmd = ["generate_c_and_h", sources.first, c_fname, h_fname]
+    unless cache.up_to_date?([c_fname, h_fname], cmd, sources, env)
+      cache.mkdir_p(File.dirname(target))
+      system(cmd)
+      cache.register_build([c_fname, h_fname], cmd, sources, env)
+    end
+    target
+  end
+end
+
+Rscons::Environment.new do |env|
+  env.add_builder(CModuleGenerator.new)
+  env.CModuleGenerator("build/foo.c", "foo_gen.cfg")
+end
+```
+
+### Example: Custom Builder Using Builder#standard_build()
+
+The `standard_build` method from the `Rscons::Builder` base class can be used
+when the builder needs to execute a system command to produce the target file.
+The `standard_build` method will return the correct value so its return value
+can be used as the return value from the `run` method.
+
+```ruby
+class CmdBuilder < Rscons::Builder
+  def run(target, sources, cache, env, vars)
+    cmd = ["cmd", "-i", sources.first, "-o", target]
+    standard_build("CmdBld #{target}", target, cmd, sources, env, cache)
+  end
+end
+
+Rscons::Environment.new do |env|
+  env.add_builder(CmdBuilder.new)
+  env.CmdBuilder("foo.gen", "foo_gen.cfg")
+end
+```
+
 ### Example: Using different compilation flags for some sources

 ```ruby
@@ -96,6 +169,22 @@ Rscons::Environment.new do |env|
 end
 ```

+Each build hook block will be invoked for every build operation, so the block
+should test the target or sources if its action should only apply to some
+subset of build targets or source files.
+
+The `build_op` parameter to the build hook block is a Hash describing the
+build operation with the following keys:
+* `:builder` - `Builder` instance in use
+* `:env` - `Environment` calling the build hook; note that this may be
+  different from the Environment that the build hook was added to in the case
+  that the original Environment was cloned with build hooks!
+* `:target` - `String` name of the target file
+* `:sources` - `Array` of the source files
+* `:vars` - `Rscons::VarSet` containing the construction variables to use.
+  The build hook can overwrite entries in `build_op[:vars]` to alter the
+  construction variables in use for this specific build operation.
+
 ### Example: Creating a static library

 ```ruby
@@ -104,18 +193,95 @@ Rscons::Environment.new do |env|
 end
 ```

+### Example: Creating a C++ parser source from a Yacc/Bison input file
+
+```ruby
+Rscons::Environment.new do |env|
+  env.CFile("#{env.build_root}/parser.tab.cc", "parser.yy")
+end
+```
+
 ## Details

-### Default Builders
+### Builders

-Rscons ships with a number of default builders:
+Rscons ships with a number of builders:

+* CFile, which builds a C or C++ source file from a lex or yacc input file
+* Disassemble, which disassembles an object file to a disassembly listing
 * Library, which collects object files into a static library archive file
 * Object, which compiles source files to produce an object file
+* Preprocess, which invokes the C/C++ preprocessor on a source file
 * Program, which links object files to produce an executable

-If you want to create an Environment that does not contain any (or select)
-builders, you can use the `exclude_builders` key to the Environment constructor.
+If you want to create an Environment that does not contain any builders,
+you can use the `exclude_builders` key to the Environment constructor.
+
+#### CFile
+
+```ruby
+env.CFile(target, source)
+# Example
+env.CFile("parser.c", "parser.y")
+```
+
+The CFile builder will generate a C or C++ source file from a lex (.l, .ll)
+or yacc (.y, .yy) input file.
+
+#### Disassemble
+
+```ruby
+env.Disassemble(target, source)
+# Example
+env.Disassemble("module.dis", "module.o")
+```
+
+The Disassemble builder generates a disassembly listing using objdump from
+and object file.
+
+#### Library
+
+```ruby
+env.Library(target, sources)
+# Example
+env.Library("lib.a", Dir["src/**/*.c"])
+```
+
+The Library builder creates a static library archive from the given source
+files.
+
+#### Object
+
+```ruby
+env.Object(target, sources)
+# Example
+env.Object("module.o", "module.c")
+```
+
+The Object builder compiles the given sources to an object file.
+
+#### Preprocess
+
+```ruby
+env.Preprocess(target, source)
+# Example
+env.Preprocess("module-preprocessed.cc", "module.cc")
+```
+
+The Preprocess builder invokes either ${CC} or ${CXX} (depending on if the
+source contains an extension in ${CXXSUFFIX} or not) and writes the
+preprocessed output to the target file.
+
+#### Program
+
+```ruby
+env.Program(target, sources)
+# Example
+env.Program("myprog", Dir["src/**/*.cc"])
+```
+
+The Program builder compiles and links the given sources to an executable file.
+Object files or source files can be given as `sources`.

 ### Managing Environments

@@ -123,14 +289,22 @@ An Rscons::Environment consists of:

 * a collection of construction variables
 * a collection of builders
-* a mapping of build directories
+* a mapping of build directories from source directories
+* a default build root to apply if no build directories are matched
 * a collection of targets to build
 * a collection of build hooks

-When cloning an environment, the construction variables and builders are
-cloned, but the new environment does not inherit any of the targets, build
+When cloning an environment, by default the construction variables and builders
+are cloned, but the new environment does not inherit any of the targets, build
 hooks, build directories, or the build root from the source environment.

+The set of environment attributes that are cloned is controllable via the
+`:clone` option to the `#clone` method.
+For example, `env.clone(clone: :all)` will include construction variables,
+builders, build hooks, build directories, and the build root.
+
+The set of pending targets is never cloned.
+
 Cloned environments contain "deep copies" of construction variables.
 For example, in:

@@ -143,12 +317,49 @@ cloned_env["CPPPATH"] << "three"

 `base_env["CPPPATH"]` will not include "three".

-### Construction Variables
+### Construction Variable Naming

-The default construction variables that Rscons uses are named using uppercase
-strings.
-Rscons options are lowercase symbols.
-Lowercase strings are reserved as user-defined construction variables.
+* uppercase strings - the default construction variables that Rscons uses
+* symbols, lowercase strings - reserved as user-defined construction variables
+
+### API documentation
+
+Documentation for the complete Rscons API can be found at
+http://rubydoc.info/github/holtrop/rscons/frames.
+
+## Release Notes
+
+### v1.4.0
+
+- add CFile builder
+- add Disassemble builder
+- add Preprocess builder
+- pass the Environment object to build hooks in the :env key of the build_op parameter
+- expand target/source paths beginning with "^/" to be relative to the Environment's build root
+- many performance improvements, including:
+  - use JSON instead of YAML for the cache to improve loading speed (Issue #7)
+  - store a hash of the build command instead of the full command contents in the cache
+  - implement copy-on-write semantics for construction variables when cloning Environments
+  - only load the cache once instead of on each Environment#process
+  - only write the cache when something has changed
+- fix Cache#mkdir_p to handle relative paths (Issue #5)
+- flush the cache to disk if a builder raises an exception (Issue #4)
+
+### v1.3.0
+
+- change Environment#execute() options parameter to accept the following options keys:
+  - :env to pass an environment Hash to Kernel#system
+  - :options to pass an options Hash to Kernel#system
+
+### v1.2.0
+
+- add :clone option to Environment#clone to control exactly which Environment attributes are cloned
+- allow nil to be passed in to Environment#build_root=
+
+### v1.1.0
+
+- Change Cache#up_to_date?() and #register_build() to accept a single target
+  file or an array of target file names

 ## Contributing

@@ -1,31 +1,33 @@
-require "rscons/builder"
-require "rscons/cache"
-require "rscons/environment"
-require "rscons/varset"
-require "rscons/version"
-
-require "rscons/monkey/module"
-require "rscons/monkey/string"
+require_relative "rscons/builder"
+require_relative "rscons/cache"
+require_relative "rscons/environment"
+require_relative "rscons/varset"
+require_relative "rscons/version"

 # default builders
-require "rscons/builders/library"
-require "rscons/builders/object"
-require "rscons/builders/program"
+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"

 # Namespace module for rscons classes
 module Rscons
  DEFAULT_BUILDERS = [
-    Library,
-    Object,
-    Program,
+    :CFile,
+    :Disassemble,
+    :Library,
+    :Object,
+    :Preprocess,
+    :Program,
  ]

-  class BuildError < Exception
-  end
+  class BuildError < RuntimeError; end

  # Remove all generated files
  def self.clean
-    cache = Cache.new
+    cache = Cache.instance
    # remove all built files
    cache.targets.each do |target|
      FileUtils.rm_f(target)
@@ -37,6 +39,19 @@ module Rscons
        Dir.rmdir(directory) rescue nil
      end
    end
-    Cache.clear
+    cache.clear
+  end
+
+  # Return whether the given path is an absolute filesystem path or not
+  # @param path [String] the path to examine
+  def self.absolute_path?(path)
+    path =~ %r{^(/|\w:[\\/])}
+  end
+
+  # Return a new path by changing the suffix in path to suffix.
+  # @param path [String] the path to alter
+  # @param suffix [String] the new filename suffix
+  def self.set_suffix(path, suffix)
+    path.sub(/\.[^.]*$/, suffix)
  end
 end
@@ -1,8 +1,17 @@
 require "fileutils"

 module Rscons
+  # Namespace module in which to store builders for convenient grouping
+  module Builders; end
+
  # Class to hold an object that knows how to build a certain type of file.
  class Builder
+    # Return the name of the builder.
+    # If not overridden this defaults to the last component of the class name.
+    def name
+      self.class.name.split(":").last
+    end
+
    # Return a set of default variable values for the Environment to use
    # unless the user overrides any.
    # @param env [Environment] The Environment.
@@ -23,11 +32,11 @@ module Rscons
    # build command.
    # Return the name of the target or false on failure.
    def standard_build(short_cmd_string, target, command, sources, env, cache)
-      unless cache.up_to_date?(target, command, sources)
+      unless cache.up_to_date?(target, command, sources, env)
        cache.mkdir_p(File.dirname(target))
        FileUtils.rm_f(target)
        return false unless env.execute(short_cmd_string, command)
-        cache.register_build(target, command, sources)
+        cache.register_build(target, command, sources, env)
      end
      target
    end
@@ -0,0 +1,40 @@
+module Rscons
+  module Builders
+    # Build a C or C++ source file given a lex (.l, .ll) or yacc (.y, .yy)
+    # input file.
+    #
+    # Examples::
+    #   env.CFile("parser.tab.cc", "parser.yy")
+    #   env.CFile("lex.yy.cc", "parser.ll")
+    class CFile < Builder
+      def default_variables(env)
+        {
+          "YACC" => "bison",
+          "YACC_FLAGS" => ["-d"],
+          "YACC_CMD" => ["${YACC}", "${YACC_FLAGS}", "-o", "${_TARGET}", "${_SOURCES}"],
+          "LEX" => "flex",
+          "LEX_FLAGS" => [],
+          "LEX_CMD" => ["${LEX}", "${LEX_FLAGS}", "-o", "${_TARGET}", "${_SOURCES}"],
+        }
+      end
+
+      def run(target, sources, cache, env, vars)
+        vars = vars.merge({
+          "_TARGET" => target,
+          "_SOURCES" => sources,
+        })
+        cmd =
+          case
+          when sources.first.end_with?(".l", ".ll")
+            "LEX"
+          when sources.first.end_with?(".y", ".yy")
+            "YACC"
+          else
+            raise "Unknown source file #{sources.first.inspect} for CFile builder"
+          end
+        command = env.build_command(env["#{cmd}_CMD"], vars)
+        standard_build("#{cmd} #{target}", target, command, sources, env, cache)
+      end
+    end
+  end
+end
@@ -0,0 +1,25 @@
+module Rscons
+  module Builders
+    # The Disassemble builder produces a disassembly listing of a source file.
+    class Disassemble < Builder
+      def default_variables(env)
+        {
+          "OBJDUMP" => "objdump",
+          "DISASM_CMD" => ["${OBJDUMP}", "${DISASM_FLAGS}", "${_SOURCES}"],
+          "DISASM_FLAGS" => ["--disassemble", "--source"],
+        }
+      end
+
+      def run(target, sources, cache, env, vars)
+        vars = vars.merge("_SOURCES" => sources)
+        command = env.build_command(env["DISASM_CMD"], vars)
+        unless cache.up_to_date?(target, command, sources, env)
+          cache.mkdir_p(File.dirname(target))
+          return false unless env.execute("Disassemble #{target}", command, options: {out: target})
+          cache.register_build(target, command, sources, env)
+        end
+        target
+      end
+    end
+  end
+end
@@ -1,7 +1,6 @@
-require 'fileutils'
-
 module Rscons
-  # A default RScons builder that produces a static library archive.
+  module Builders
+    # A default Rscons builder that produces a static library archive.
    class Library < Builder
      def default_variables(env)
        {
@@ -12,7 +11,7 @@ module Rscons
        }
      end

-    def run(target, sources, cache, env, vars = {})
+      def run(target, sources, cache, env, vars)
        # build sources to linkable objects
        objects = env.build_sources(sources, [env['OBJSUFFIX'], env['LIBSUFFIX']].flatten, cache, vars)
        if objects
@@ -26,3 +25,4 @@ module Rscons
      end
    end
  end
+end
@@ -1,5 +1,6 @@
 module Rscons
-  # A default RScons builder which knows how to produce an object file from
+  module Builders
+    # A default Rscons builder which knows how to produce an object file from
    # various types of source files.
    class Object < Builder
      KNOWN_SUFFIXES = {
@@ -45,24 +46,24 @@ module Rscons
      end

      def produces?(target, source, env)
-      target.has_suffix?(env['OBJSUFFIX']) and KNOWN_SUFFIXES.find do |compiler, suffix_var|
-        source.has_suffix?(env[suffix_var])
+        target.end_with?(*env['OBJSUFFIX']) and KNOWN_SUFFIXES.find do |compiler, suffix_var|
+          source.end_with?(*env[suffix_var])
        end
      end

-    def run(target, sources, cache, env, vars = {})
+      def run(target, sources, cache, env, vars)
        vars = vars.merge({
          '_TARGET' => target,
          '_SOURCES' => sources,
-        '_DEPFILE' => target.set_suffix('.mf'),
+          '_DEPFILE' => Rscons.set_suffix(target, '.mf'),
        })
        com_prefix = KNOWN_SUFFIXES.find do |compiler, suffix_var|
-        sources.first.has_suffix?(env[suffix_var])
+          sources.first.end_with?(*env[suffix_var])
        end.tap do |v|
          v.nil? and raise "Error: unknown input file type: #{sources.first.inspect}"
        end.first
        command = env.build_command(env["#{com_prefix}CMD"], vars)
-      unless cache.up_to_date?(target, command, sources)
+        unless cache.up_to_date?(target, command, sources, env)
          cache.mkdir_p(File.dirname(target))
          FileUtils.rm_f(target)
          return false unless env.execute("#{com_prefix} #{target}", command)
@@ -71,9 +72,10 @@ module Rscons
            deps += Environment.parse_makefile_deps(vars['_DEPFILE'], target)
            FileUtils.rm_f(vars['_DEPFILE'])
          end
-        cache.register_build(target, command, deps.uniq)
+          cache.register_build(target, command, deps.uniq, env)
        end
        target
      end
    end
  end
+end
@@ -0,0 +1,25 @@
+module Rscons
+  module Builders
+    # The Preprocess builder invokes the C preprocessor
+    class Preprocess < Builder
+      def default_variables(env)
+        {
+          "CPP_CMD" => ["${_PREPROCESS_CC}", "-E", "-o", "${_TARGET}", "-I${CPPPATH}", "${CPPFLAGS}", "${CFLAGS}", "${_SOURCES}"],
+        }
+      end
+
+      def run(target, sources, cache, env, vars)
+        pp_cc = if sources.find {|s| s.end_with?(*env["CXXSUFFIX"])}
+                  env["CXX"]
+                else
+                  env["CC"]
+                end
+        vars = vars.merge("_PREPROCESS_CC" => pp_cc,
+                          "_TARGET" => target,
+                          "_SOURCES" => sources)
+        command = env.build_command(env["CPP_CMD"], vars)
+        standard_build("Preprocess #{target}", target, command, sources, env, cache)
+      end
+    end
+  end
+end
@@ -1,5 +1,6 @@
 module Rscons
-  # A default RScons builder that knows how to link object files into an
+  module Builders
+    # A default Rscons builder that knows how to link object files into an
    # executable program.
    class Program < Builder
      def default_variables(env)
@@ -14,14 +15,15 @@ module Rscons
        }
      end

-    def run(target, sources, cache, env, vars = {})
+      def run(target, sources, cache, env, vars)
        # build sources to linkable objects
        objects = env.build_sources(sources, [env['OBJSUFFIX'], env['LIBSUFFIX']].flatten, cache, vars)
+        return false unless objects
        ld = if env["LD"]
               env["LD"]
-           elsif sources.find {|s| s.has_suffix?(env["DSUFFIX"])}
+             elsif sources.find {|s| s.end_with?(*env["DSUFFIX"])}
               env["DC"]
-           elsif sources.find {|s| s.has_suffix?(env["CXXSUFFIX"])}
+             elsif sources.find {|s| s.end_with?(*env["CXXSUFFIX"])}
               env["CXX"]
             else
               env["CC"]
@@ -36,3 +38,4 @@ module Rscons
      end
    end
  end
+end
@@ -1,92 +1,101 @@
-require 'yaml'
-require 'fileutils'
-require 'digest/md5'
-require 'set'
-require 'rscons/version'
+require "digest/md5"
+require "fileutils"
+require "json"
+require "set"
+require "singleton"
+require "rscons/version"

 module Rscons
  # The Cache class keeps track of file checksums, build target commands and
-  # dependencies in a YAML file which persists from one invocation to the next.
+  # dependencies in a JSON file which persists from one invocation to the next.
  # Example cache:
  #   {
-  #     version: '1.2.3',
-  #     targets: {
-  #       'program' => {
-  #         'checksum' => 'A1B2C3D4',
-  #         'command' => ['gcc', '-o', 'program', 'program.o'],
-  #         'deps' => [
+  #     "version" => "1.2.3",
+  #     "targets" => {
+  #       "program" => {
+  #         "checksum" => "A1B2C3D4",
+  #         "command" => "13543518FE",
+  #         "deps" => [
  #           {
-  #             'fname' => 'program.o',
-  #             'checksum' => '87654321',
-  #           }
+  #             "fname" => "program.o",
+  #             "checksum" => "87654321",
+  #           },
  #         ],
-  #       }
-  #       'program.o' => {
-  #         'checksum' => '87654321',
-  #         'command' => ['gcc', '-c', '-o', 'program.o', 'program.c'],
-  #         'deps' => [
+  #         "user_deps" => [
  #           {
-  #             'fname' => 'program.c',
-  #             'checksum' => '456789ABC',
+  #             "fname" => "lscript.ld",
+  #             "checksum" => "77551133",
+  #           },
+  #         ],
+  #       },
+  #       "program.o" => {
+  #         "checksum" => "87654321",
+  #         "command" => "98765ABCD",
+  #         "deps" => [
+  #           {
+  #             "fname" => "program.c",
+  #             "checksum" => "456789ABC",
  #           },
  #           {
-  #             'fname' => 'program.h',
-  #             'checksum' => '7979764643',
-  #           }
-  #         ]
-  #       }
-  #     }
-  #     directories: {
-  #       'build' => true,
-  #       'build/one' => true,
-  #       'build/two' => true,
+  #             "fname" => "program.h",
+  #             "checksum" => "7979764643",
+  #           },
+  #         ],
+  #         "user_deps" => [],
  #       }
+  #     },
+  #     "directories" => {
+  #       "build" => true,
+  #       "build/one" => true,
+  #       "build/two" => true,
+  #     },
  #   }
  class Cache
-    #### Constants
+    include Singleton

    # Name of the file to store cache information in
-    CACHE_FILE = '.rsconscache'
-
-    #### Class Methods
-
-    # Remove the cache file
-    def self.clear
-      FileUtils.rm_f(CACHE_FILE)
-    end
-
-    #### Instance Methods
+    CACHE_FILE = ".rsconscache"

    # Create a Cache object and load in the previous contents from the cache
    # file.
    def initialize
-      @cache = YAML.load(File.read(CACHE_FILE)) rescue {}
-      unless @cache.is_a?(Hash)
-        $stderr.puts "Warning: #{CACHE_FILE} was corrupt. Contents:\n#{@cache.inspect}"
-        @cache = {}
+      initialize!
    end
-      @cache[:targets] ||= {}
-      @cache[:directories] ||= {}
+
+    # Remove the cache file.
+    def clear
+      FileUtils.rm_f(CACHE_FILE)
+      initialize!
+    end
+
+    # Clear the cached file checksums.
+    def clear_checksum_cache!
      @lookup_checksums = {}
    end

    # Write the cache to disk to be loaded next time.
    def write
-      @cache[:version] = VERSION
-      File.open(CACHE_FILE, 'w') do |fh|
-        fh.puts(YAML.dump(@cache))
+      if @dirty || (@cache["version"] != VERSION)
+        @cache["version"] = VERSION
+        File.open(CACHE_FILE, "w") do |fh|
+          fh.puts(JSON.dump(@cache))
        end
      end
+      @dirty = false
+    end

-    # Check if a target is up to date
-    # @param target [String] The name of the target file.
-    # @param command [Array] The command used to build the target.
+    # 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 options [Hash] Optional options. Can contain the following keys:
-    #   :strict_deps::
+    # @param env [Environment] The Rscons::Environment.
+    # @param options [Hash] Optional options.
+    # @option options [Boolean] :strict_deps
    #   Only consider a target up to date if its list of dependencies is
    #   exactly equal (including order) to the cached list of dependencies
-    # @return true value if the target is up to date, meaning that:
+    # @return [Boolean]
+    #   True value if the targets are all up to date, meaning that,
+    #   for each target:
    #   - the target exists on disk
    #   - the cache has information for the target
    #   - the target's checksum matches its checksum when it was last built
@@ -96,79 +105,113 @@ module Rscons
    #     exactly equal to those cached
    #   - each cached dependency file's current checksum matches the checksum
    #     stored in the cache file
-    def up_to_date?(target, command, deps, options = {})
+    def up_to_date?(targets, command, deps, env, options = {})
+      Array(targets).each do |target|
        # target file must exist on disk
        return false unless File.exists?(target)

        # target must be registered in the cache
-      return false unless @cache[:targets].has_key?(target)
+        return false unless @cache["targets"].has_key?(target)

        # target must have the same checksum as when it was built last
-      return false unless @cache[:targets][target][:checksum] == lookup_checksum(target)
+        return false unless @cache["targets"][target]["checksum"] == lookup_checksum(target)

        # command used to build target must be identical
-      return false unless @cache[:targets][target][:command] == command
+        return false unless @cache["targets"][target]["command"] == Digest::MD5.hexdigest(command.inspect)

-      cached_deps = @cache[:targets][target][:deps].map { |dc| dc[:fname] }
+        cached_deps = @cache["targets"][target]["deps"] || []
+        cached_deps_fnames = cached_deps.map { |dc| dc["fname"] }
        if options[:strict_deps]
          # depedencies passed in must exactly equal those in the cache
-        return false unless deps == cached_deps
+          return false unless deps == cached_deps_fnames
        else
          # all dependencies passed in must exist in cache (but cache may have more)
-        return false unless (Set.new(deps) - Set.new(cached_deps)).empty?
+          return false unless (Set.new(deps) - Set.new(cached_deps_fnames)).empty?
        end

+        # set of user dependencies must match
+        user_deps = env.get_user_deps(target) || []
+        cached_user_deps = @cache["targets"][target]["user_deps"] || []
+        cached_user_deps_fnames = cached_user_deps.map { |dc| dc["fname"] }
+        return false unless user_deps == cached_user_deps_fnames
+
        # all cached dependencies must have their checksums match
-      @cache[:targets][target][:deps].each do |dep_cache|
-        return false unless dep_cache[:checksum] == lookup_checksum(dep_cache[:fname])
+        (cached_deps + cached_user_deps).each do |dep_cache|
+          return false unless dep_cache["checksum"] == lookup_checksum(dep_cache["fname"])
+        end
      end

      true
    end

-    # Store cache information about a target built by a builder
-    # @param target [String] The name of the target.
-    # @param command [Array] The command used to build the target.
+    # 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.
-    def register_build(target, command, deps)
-      @cache[:targets][target.encode(__ENCODING__)] = {
-        command: command,
-        checksum: calculate_checksum(target),
-        deps: deps.map do |dep|
+    # @param env [Environment] The {Rscons::Environment}.
+    def register_build(targets, command, deps, env)
+      Array(targets).each do |target|
+        @cache["targets"][target] = {
+          "command" => Digest::MD5.hexdigest(command.inspect),
+          "checksum" => calculate_checksum(target),
+          "deps" => deps.map do |dep|
            {
-            fname: dep.encode(__ENCODING__),
-            checksum: lookup_checksum(dep),
+              "fname" => dep,
+              "checksum" => lookup_checksum(dep),
            }
+          end,
+          "user_deps" => (env.get_user_deps(target) || []).map do |dep|
+            {
+              "fname" => dep,
+              "checksum" => lookup_checksum(dep),
+            }
+          end,
+        }
+        @dirty = true
      end
-      }
    end

    # Return a list of targets that have been built
    def targets
-      @cache[:targets].keys
+      @cache["targets"].keys
    end

    # Make any needed directories and record the ones that are created for
    # removal upon a "clean" operation.
    def mkdir_p(path)
      parts = path.split(/[\\\/]/)
-      (0..parts.size-1).each do |i|
-        subpath = File.join(*parts[0, i + 1]).encode(__ENCODING__)
+      parts.each_index do |i|
+        next if parts[i] == ""
+        subpath = File.join(*parts[0, i + 1])
        unless File.exists?(subpath)
          FileUtils.mkdir(subpath)
-          @cache[:directories][subpath] = true
+          @cache["directories"][subpath] = true
+          @dirty = true
        end
      end
    end

    # Return a list of directories which were created as a part of the build
    def directories
-      @cache[:directories].keys
+      @cache["directories"].keys
    end

-    # Private Instance Methods
    private

+    # Create a Cache object and load in the previous contents from the cache
+    # file.
+    def initialize!
+      @cache = JSON.load(File.read(CACHE_FILE)) rescue {}
+      unless @cache.is_a?(Hash)
+        $stderr.puts "Warning: #{CACHE_FILE} was corrupt. Contents:\n#{@cache.inspect}"
+        @cache = {}
+      end
+      @cache["targets"] ||= {}
+      @cache["directories"] ||= {}
+      @lookup_checksums = {}
+      @dirty = false
+    end
+
    # Return a file's checksum, or the previously calculated checksum for
    # the same file
    # @param file [String] The file name.
@@ -179,7 +222,7 @@ module Rscons
    # Calculate and return a file's checksum
    # @param file [String] The file name.
    def calculate_checksum(file)
-      @lookup_checksums[file] = Digest::MD5.hexdigest(File.read(file, mode: 'rb')).encode(__ENCODING__) rescue ''
+      @lookup_checksums[file] = Digest::MD5.hexdigest(File.read(file, mode: "rb")) rescue ""
    end
  end
 end
@@ -2,40 +2,47 @@ require 'set'
 require 'fileutils'

 module Rscons
-  # The Environment class is the main programmatic interface to RScons. It
+  # The Environment class is the main programmatic interface to Rscons. It
  # contains a collection of construction variables, options, builders, and
  # rules for building targets.
  class Environment
    # Hash of +{"builder_name" => builder_object}+ pairs.
    attr_reader :builders

+    # :command, :short, or :off
+    attr_accessor :echo
+
    # String or +nil+
-    attr_accessor :build_root
+    attr_reader :build_root
+    def build_root=(build_root)
+      @build_root = build_root
+      @build_root.gsub!('\\', '/') if @build_root
+    end

    # Create an Environment object.
-    # @param variables [Hash]
-    #   The variables hash can contain construction variables, which are
-    #   uppercase strings (such as "CC" or "LDFLAGS"), user variables, which
-    #   are lowercase strings (such as "sources"), and RScons options, which
-    #   are lowercase symbols (such as :echo).
+    # @param options [Hash]
+    # Possible options keys:
+    #   :echo => :command, :short, or :off (default :short)
+    #   :build_root => String specifying build root directory (default nil)
+    #   :exclude_builders => true to omit adding default builders (default false)
    # If a block is given, the Environment object is yielded to the block and
    # when the block returns, the {#process} method is automatically called.
-    def initialize(variables = {})
-      @varset = VarSet.new(variables)
+    def initialize(options = {})
+      @varset = VarSet.new
      @targets = {}
+      @user_deps = {}
      @builders = {}
      @build_dirs = []
      @build_hooks = []
-      @varset[:exclude_builders] ||= []
-      unless @varset[:exclude_builders] == :all
-        exclude_builders = Set.new(@varset[:exclude_builders] || [])
-        DEFAULT_BUILDERS.each do |builder_class|
-          unless exclude_builders.include?(builder_class.short_name)
+      unless options[:exclude_builders]
+        DEFAULT_BUILDERS.each do |builder_class_name|
+          builder_class = Builders.const_get(builder_class_name)
+          builder_class or raise "Could not find builder class #{builder_class_name}"
          add_builder(builder_class.new)
        end
      end
-      end
-      @varset[:echo] ||= :short
+      @echo = options[:echo] || :short
+      @build_root = options[:build_root]

      if block_given?
        yield self
@@ -44,18 +51,53 @@ module Rscons
    end

    # Make a copy of the Environment object.
-    # The cloned environment will contain a copy of all environment options,
-    # construction variables, and builders. It will not contain a copy of the
-    # targets, build hooks, build directories, or the build root.  If a block
-    # is given, the Environment object is yielded to the block and when the
-    # block returns, the {#process} method is automatically called.
-    def clone(variables = {})
-      env = Environment.new()
+    #
+    # By default, a cloned environment will contain a copy of all environment
+    # options, construction variables, and builders, but not a copy of the
+    # targets, build hooks, build directories, or the build root.
+    #
+    # Exactly which items are cloned are controllable via the optional :clone
+    # parameter, which can be :none, :all, or a set or array of any of the
+    # following:
+    # - :variables to clone construction variables (on by default)
+    # - :builders to clone the builders (on by default)
+    # - :build_root to clone the build root (off by default)
+    # - :build_dirs to clone the build directories (off by default)
+    # - :build_hooks to clone the build hooks (off by default)
+    #
+    # If a block is given, the Environment object is yielded to the block and
+    # when the block returns, the {#process} method is automatically called.
+    #
+    # Any options that #initialize receives can also be specified here.
+    #
+    # @return a new {Environment} object.
+    def clone(options = {})
+      clone = options[:clone] || Set[:variables, :builders]
+      clone = Set[:variables, :builders, :build_root, :build_dirs, :build_hooks] if clone == :all
+      clone = Set[] if clone == :none
+      clone = Set.new(clone) if clone.is_a?(Array)
+      clone.delete(:builders) if options[:exclude_builders]
+      env = self.class.new(
+        echo: options[:echo] || @echo,
+        build_root: options[:build_root],
+        exclude_builders: true)
+      if clone.include?(:builders)
        @builders.each do |builder_name, builder|
          env.add_builder(builder)
        end
-      env.append(@varset.clone)
-      env.append(variables)
+      end
+      env.append(@varset) if clone.include?(:variables)
+      env.build_root = @build_root if clone.include?(:build_root)
+      if clone.include?(:build_dirs)
+        @build_dirs.each do |src_dir, obj_dir|
+          env.build_dir(src_dir, obj_dir)
+        end
+      end
+      if clone.include?(:build_hooks)
+        @build_hooks.each do |build_hook_block|
+          env.add_build_hook(&build_hook_block)
+        end
+      end

      if block_given?
        yield env
@@ -66,7 +108,7 @@ module Rscons

    # Add a {Builder} object to the Environment.
    def add_builder(builder)
-      @builders[builder.class.short_name] = builder
+      @builders[builder.name] = builder
      var_defs = builder.default_variables(self)
      if var_defs
        var_defs.each_pair do |var, val|
@@ -90,7 +132,7 @@ module Rscons
    # Return the file name to be built from source_fname with suffix suffix.
    # This method takes into account the Environment's build directories.
    def get_build_fname(source_fname, suffix)
-      build_fname = source_fname.set_suffix(suffix).gsub('\\', '/')
+      build_fname = Rscons.set_suffix(source_fname, suffix).gsub('\\', '/')
      found_match = @build_dirs.find do |src_dir, obj_dir|
        if src_dir.is_a?(Regexp)
          build_fname.sub!(src_dir, obj_dir)
@@ -99,7 +141,7 @@ module Rscons
        end
      end
      if @build_root and not found_match
-        unless source_fname.start_with?('/') or source_fname =~ %r{^\w:[\\/]}
+        unless Rscons.absolute_path?(source_fname) or build_fname.start_with?("#{@build_root}/")
          build_fname = "#{@build_root}/#{build_fname}"
        end
      end
@@ -122,39 +164,50 @@ module Rscons
    # Add a set of construction variables or environment options.
    # @see VarSet#append
    def append(*args)
-      @varset.send(:append, *args)
+      @varset.append(*args)
    end

    # Build all target specified in the Environment.
    # When a block is passed to Environment.new, this method is automatically
    # called after the block returns.
    def process
-      cache = Cache.new
+      unless @targets.empty?
+        clean_target_paths!
+        cache = Cache.instance
+        cache.clear_checksum_cache!
        targets_processed = {}
        process_target = proc do |target|
          targets_processed[target] ||= begin
-          @targets[target][:source].each do |src|
+            @targets[target][:sources].each do |src|
              if @targets.include?(src) and not targets_processed.include?(src)
                process_target.call(src)
              end
            end
            result = run_builder(@targets[target][:builder],
                                 target,
-                               @targets[target][:source],
+                                 @targets[target][:sources],
                                 cache,
                                 @targets[target][:vars] || {})
            unless result
-            cache.write
              raise BuildError.new("Failed to build #{target}")
            end
            result
          end
        end
-      @targets.each do |target, info|
+        begin
+          @targets.each do |target, target_params|
            process_target.call(target)
          end
+        ensure
          cache.write
        end
+      end
+    end
+
+    # Clear all targets registered for the Environment.
+    def clear_targets
+      @targets = {}
+    end

    # Build a command line from the given template, resolving references to
    # variables using the Environment's construction variables and any extra
@@ -168,58 +221,83 @@ module Rscons
      @varset.merge(extra_vars).expand_varref(command_template)
    end

+    # Expand a construction variable reference (String or Array)
+    def expand_varref(varref)
+      @varset.expand_varref(varref)
+    end
+
    # Execute a builder command
-    # @param short_desc [String] Message to print if the Environment's :echo
+    # @param short_desc [String] Message to print if the Environment's echo
    #   mode is set to :short
    # @param command [Array] The command to execute.
-    # @param options [Hash] Optional options to pass to Kernel#system.
+    # @param options [Hash] Optional options, possible keys:
+    #   - :env - environment Hash to pass to Kernel#system.
+    #   - :options - options Hash to pass to Kernel#system.
    def execute(short_desc, command, options = {})
      print_command = proc do
        puts command.map { |c| c =~ /\s/ ? "'#{c}'" : c }.join(' ')
      end
-      if @varset[:echo] == :command
+      if @echo == :command
        print_command.call
-      elsif @varset[:echo] == :short
+      elsif @echo == :short
        puts short_desc
      end
-      system(*command, options).tap do |result|
-        unless result or @varset[:echo] == :command
+      env_args = options[:env] ? [options[:env]] : []
+      options_args = options[:options] ? [options[:options]] : []
+      system(*env_args, *command, *options_args).tap do |result|
+        unless result or @echo == :command
          $stdout.write "Failed command was: "
          print_command.call
        end
      end
    end

-    alias_method :orig_method_missing, :method_missing
    def method_missing(method, *args)
      if @builders.has_key?(method.to_s)
-        target, source, vars, *rest = args
+        target, sources, vars, *rest = args
        unless vars.nil? or vars.is_a?(Hash) or vars.is_a?(VarSet)
          raise "Unexpected construction variable set: #{vars.inspect}"
        end
-        source = [source] unless source.is_a?(Array)
-        @targets[target] = {
-          builder: @builders[method.to_s],
-          source: source,
-          vars: vars,
-          args: rest,
-        }
+        sources = [sources] unless sources.is_a?(Array)
+        add_target(target, @builders[method.to_s], sources, vars, rest)
      else
-        orig_method_missing(method, *args)
+        super
      end
    end

+    def add_target(target, builder, sources, vars, args)
+      @targets[target] = {
+        builder: builder,
+        sources: sources,
+        vars: vars,
+        args: args,
+      }
+    end
+
+    # Manually record a given target as depending on the specified
+    # dependency files.
+    def depends(target, *user_deps)
+      @user_deps[target] ||= []
+      @user_deps[target] = (@user_deps[target] + user_deps).uniq
+    end
+
+    # Return the list of user dependencies for a given target, or +nil+ for
+    # none.
+    def get_user_deps(target)
+      @user_deps[target]
+    end
+
    # Build a list of source files into files containing one of the suffixes
    # given by suffixes.
-    # This method is used internally by RScons builders.
+    # 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 cache [Cache] The Cache.
    # @param vars [Hash] Extra variables to pass to the builder.
    # Return a list of the converted file names.
-    def build_sources(sources, suffixes, cache, vars = {})
+    def build_sources(sources, suffixes, cache, vars)
      sources.map do |source|
-        if source.has_suffix?(suffixes)
+        if source.end_with?(*suffixes)
          source
        else
          converted = nil
@@ -252,14 +330,36 @@ module Rscons
          target: target,
          sources: sources,
          vars: vars,
+          env: self,
        }
        build_hook_block.call(build_operation)
      end
      builder.run(target, sources, cache, self, vars)
    end

+    private
+
+    # Expand all target paths that begin with ^/ to be relative to the
+    # Environment's build root, if present
+    def clean_target_paths!
+      if @build_root
+        expand = lambda do |path|
+          path.sub(%r{^\^(?=[\\/])}, @build_root)
+        end
+
+        new_targets = {}
+        @targets.each_pair do |target, target_params|
+          target_params[:sources].map! do |source|
+            expand[source]
+          end
+          new_targets[expand[target]] = target_params
+        end
+        @targets = new_targets
+      end
+    end
+
    # Parse dependencies for a given target from a Makefile.
-    # This method is used internally by RScons builders.
+    # This method is used internally by Rscons builders.
    # @param mf_fname [String] File name of the Makefile to read.
    # @param target [String] Name of the target to gather dependencies for.
    def self.parse_makefile_deps(mf_fname, target)
@@ -1,7 +0,0 @@
-# Standard Ruby Module class.
-class Module
-  # @return the base module name (not the fully qualified name)
-  def short_name
-    name.split(':').last
-  end
-end
@@ -1,20 +0,0 @@
-# Standard Ruby String class.
-class String
-  # Check if the given string ends with any of the supplied suffixes
-  # @param suffix [String, Array] The suffix to look for.
-  # @return a true value if the string ends with one of the suffixes given.
-  def has_suffix?(suffix)
-    if suffix
-      suffix = [suffix] if suffix.is_a?(String)
-      suffix = suffix.flatten
-      suffix.find {|s| self.end_with?(s)}
-    end
-  end
-
-  # Return a new string with the suffix (dot character and extension) changed
-  # to the given suffix.
-  # @param suffix [String] The new suffix.
-  def set_suffix(suffix = '')
-    sub(/\.[^.]*$/, suffix)
-  end
-end
@@ -1,57 +1,73 @@
 module Rscons
  # This class represents a collection of variables which can be accessed
-  # as certain types
+  # as certain types.
+  # Only nil, strings, arrays, and hashes should be stored in a VarSet.
  class VarSet
-    # The underlying hash
-    attr_reader :vars
-
-    # Create a VarSet
+    # Create a VarSet.
    # @param vars [Hash] Optional initial variables.
    def initialize(vars = {})
-      if vars.is_a?(VarSet)
-        @vars = vars.clone.vars
-      else
-        @vars = vars
-      end
+      @my_vars = {}
+      @coa_vars = []
+      append(vars)
    end

    # Access the value of variable as a particular type
    # @param key [String, Symbol] The variable name.
-    # @param type [Symbol, nil] Optional specification of the type desired.
-    #   If the variable is a String and type is :array, a 1-element array with
-    #   the variable value will be returned. If the variable is an Array and
-    #   type is :string, the first element from the variable value will be
-    #   returned.
-    def [](key, type = nil)
-      val = @vars[key]
-      if type == :array and not val.is_a?(Array)
-        [val]
-      elsif type == :scalar and val.is_a?(Array)
-        val.first
+    # @return [Object] The variable's value.
+    def [](key)
+      if @my_vars.include?(key)
+        @my_vars[key]
      else
-        val
+        @coa_vars.each do |coa_vars|
+          if coa_vars.include?(key)
+            @my_vars[key] = deep_dup(coa_vars[key])
+            return @my_vars[key]
+          end
+        end
+        nil
      end
    end

    # Assign a value to a variable.
    # @param key [String, Symbol] The variable name.
-    # @param val [Object] The value.
+    # @param val [Object] The value to set.
    def []=(key, val)
-      @vars[key] = val
+      @my_vars[key] = val
+    end
+
+    # Check if the VarSet contains a variable.
+    # @param key [String, Symbol] The variable name.
+    # @return [true, false] Whether the VarSet contains a variable.
+    def include?(key)
+      if @my_vars.include?(key)
+        true
+      else
+        @coa_vars.find do |coa_vars|
+          coa_vars.include?(key)
+        end
+      end
    end

    # Add or overwrite a set of variables
    # @param values [VarSet, Hash] New set of variables.
    def append(values)
-      values = values.vars if values.is_a?(VarSet)
-      @vars.merge!(Marshal.load(Marshal.dump(values)))
+      coa!
+      if values.is_a?(VarSet)
+        values.send(:coa!)
+        @coa_vars = values.instance_variable_get(:@coa_vars) + @coa_vars
+      else
+        @my_vars = deep_dup(values)
+      end
      self
    end

    # Create a new VarSet object based on the first merged with other.
    # @param other [VarSet, Hash] Other variables to add or overwrite.
    def merge(other = {})
-      VarSet.new(Marshal.load(Marshal.dump(@vars))).append(other)
+      coa!
+      varset = self.class.new
+      varset.instance_variable_set(:@coa_vars, @coa_vars.dup)
+      varset.append(other)
    end
    alias_method :clone, :merge

@@ -66,18 +82,47 @@ module Rscons
      else
        if varref =~ /^(.*)\$\{([^}]+)\}(.*)$/
          prefix, varname, suffix = $1, $2, $3
-          varval = expand_varref(@vars[varname])
+          varval = expand_varref(self[varname])
          if varval.is_a?(String)
            expand_varref("#{prefix}#{varval}#{suffix}")
          elsif varval.is_a?(Array)
            varval.map {|vv| expand_varref("#{prefix}#{vv}#{suffix}")}.flatten
          else
-            raise "I do not know how to expand a variable reference to a #{varval.class.name}"
+            raise "I do not know how to expand a variable reference to a #{varval.class.name} (from #{varname.inspect} => #{self[varname].inspect})"
          end
        else
          varref
        end
      end
    end
+
+    private
+
+    # Move all VarSet variables into the copy-on-access list.
+    def coa!
+      unless @my_vars.empty?
+        @coa_vars.unshift(@my_vars)
+        @my_vars = {}
+      end
+    end
+
+    # Create a deep copy of an object.
+    # @param obj [nil, String, Array, Hash] Object to deep copy.
+    # @return [nil, String, Array, Hash] Deep copied value.
+    def deep_dup(obj)
+      obj_class = obj.class
+      if obj_class == Hash
+        obj.reduce({}) do |result, (k, v)|
+          result[k] = deep_dup(v)
+          result
+        end
+      elsif obj_class == Array
+        obj.map { |v| deep_dup(v) }
+      elsif obj_class == String
+        obj.dup
+      else
+        obj
+      end
+    end
  end
 end
@@ -1,4 +1,4 @@
 module Rscons
  # gem version
-  VERSION = "0.2.0"
+  VERSION = "1.4.0"
 end
@@ -1,5 +1,14 @@
 require 'fileutils'

+class Dir
+  class << self
+    alias_method :orig_bracket, :[]
+  end
+  def self.[](*args)
+    orig_bracket(*args).sort
+  end
+end
+
 describe Rscons do
  BUILD_TEST_RUN_DIR = "build_test_run"

@@ -180,6 +189,23 @@ describe Rscons do
    lines.should == ["CC build_root/src/one/one.o", "CC build_root/src/two/two.o", "LD build_dir"]
  end

+  it "expands target and source paths starting with ^/ to be relative to the build root" do
+    test_dir('build_dir')
+    Rscons::Environment.new(echo: :command) do |env|
+      env.append('CPPPATH' => Dir['src/**/*/'])
+      env.build_root = "build_root"
+      FileUtils.mkdir_p(env.build_root)
+      FileUtils.mv("src/one/one.c", "build_root")
+      env.Object("^/one.o", "^/one.c")
+      env.Program('build_dir', Dir['src/**/*.c'] + ["^/one.o"])
+    end
+    lines.should == [
+      %q{gcc -c -o build_root/one.o -MMD -MF build_root/one.mf -Isrc/one/ -Isrc/two/ build_root/one.c},
+      %q{gcc -c -o build_root/src/two/two.o -MMD -MF build_root/src/two/two.mf -Isrc/one/ -Isrc/two/ src/two/two.c},
+      %q{gcc -o build_dir build_root/src/two/two.o build_root/one.o},
+    ]
+  end
+
  it 'cleans built files' do
    test_dir('build_dir')
    Rscons::Environment.new do |env|
@@ -220,7 +246,7 @@ describe Rscons do
  it 'allows Ruby classes as custom builders to be used to construct files' do
    test_dir('custom_builder')
    class MySource < Rscons::Builder
-      def run(target, sources, cache, env, vars = {})
+      def run(target, sources, cache, env, vars)
        File.open(target, 'w') do |fh|
          fh.puts <<EOF
    #define THE_VALUE 5678
@@ -241,6 +267,39 @@ EOF
    `./program`.should == "The value is 5678\n"
  end

+  it 'supports custom builders with multiple targets' do
+    test_dir('custom_builder')
+    class CHGen < Rscons::Builder
+      def run(target, sources, cache, env, vars)
+        c_fname = target
+        h_fname = target.sub(/\.c$/, ".h")
+        unless cache.up_to_date?([c_fname, h_fname], "", sources, env)
+          puts "CHGen #{c_fname}"
+          File.open(c_fname, "w") {|fh| fh.puts "int THE_VALUE = 42;"}
+          File.open(h_fname, "w") {|fh| fh.puts "extern int THE_VALUE;"}
+          cache.register_build([c_fname, h_fname], "", sources, env)
+        end
+        target
+      end
+    end
+
+    env = Rscons::Environment.new do |env|
+      env.add_builder(CHGen.new)
+      env.CHGen("inc.c", ["program.c"])
+      env.Program("program", Dir["*.c"] + ["inc.c"])
+    end
+
+    lines.should == ["CHGen inc.c", "CC program.o", "CC inc.o", "LD program"]
+    File.exists?("inc.c").should be_true
+    File.exists?("inc.h").should be_true
+    `./program`.should == "The value is 42\n"
+
+    File.open("inc.c", "w") {|fh| fh.puts "int THE_VALUE = 33;"}
+    env.process
+    lines.should == ["CHGen inc.c"]
+    `./program`.should == "The value is 42\n"
+  end
+
  it 'allows cloning Environment objects' do
    test_dir('clone_env')

@@ -251,7 +310,8 @@ EOF
      env.Program('program-debug', Dir['src/*.c'])
    end

-    release = debug.clone('CPPFLAGS' => '-DSTRING="Release Version"') do |env|
+    release = debug.clone do |env|
+      env["CPPFLAGS"] = '-DSTRING="Release Version"'
      env.build_dir('src', 'release')
      env.Program('program-release', Dir['src/*.c'])
    end
@@ -264,6 +324,29 @@ EOF
    ]
  end

+  it 'allows cloning all attributes of an Environment object' do
+    test_dir('clone_env')
+
+    env1 = Rscons::Environment.new(echo: :command) do |env|
+      env.build_dir('src', 'build')
+      env['CFLAGS'] = '-O2'
+      env.add_build_hook do |build_op|
+        build_op[:vars]['CPPFLAGS'] = '-DSTRING="Hello"'
+      end
+      env.Program('program', Dir['src/*.c'])
+    end
+
+    env2 = env1.clone(clone: :all) do |env|
+      env.Program('program2', Dir['src/*.c'])
+    end
+
+    lines.should == [
+      %q{gcc -c -o build/program.o -MMD -MF build/program.mf -DSTRING="Hello" -O2 src/program.c},
+      %q{gcc -o program build/program.o},
+      %q{gcc -o program2 build/program.o},
+    ]
+  end
+
  it 'builds a C++ program with one source file' do
    test_dir('simple_cc')
    Rscons::Environment.new do |env|
@@ -327,6 +410,37 @@ EOF
    ]
  end

+  it 'rebuilds when user-specified dependencies change' do
+    test_dir('simple')
+    Rscons::Environment.new do |env|
+      env.Program('simple', Dir['*.c'])
+      File.open("file.ld", "w") do |fh|
+        fh.puts("foo")
+      end
+      env.depends('simple', 'file.ld')
+    end
+    lines.should == ["CC simple.o", "LD simple"]
+    File.exists?('simple.o').should be_true
+    `./simple`.should == "This is a simple C program\n"
+    Rscons::Environment.new do |env|
+      env.Program('simple', Dir['*.c'])
+      File.open("file.ld", "w") do |fh|
+        fh.puts("bar")
+      end
+      env.depends('simple', 'file.ld')
+    end
+    lines.should == ["LD simple"]
+    Rscons::Environment.new do |env|
+      env.Program('simple', Dir['*.c'])
+      File.unlink("file.ld")
+    end
+    lines.should == ["LD simple"]
+    Rscons::Environment.new do |env|
+      env.Program('simple', Dir['*.c'])
+    end
+    lines.should == []
+  end
+
  unless ENV["omit_gdc_tests"]
    it "supports building D sources" do
      test_dir("d")
@@ -340,4 +454,34 @@ EOF
      `./hello-d`.rstrip.should == "Hello from D!"
    end
  end
+
+  it "supports disassembling object files" do
+    test_dir("simple")
+    Rscons::Environment.new do |env|
+      env.Object("simple.o", "simple.c")
+      env.Disassemble("simple.txt", "simple.o")
+    end
+    File.exists?("simple.txt").should be_true
+    File.read("simple.txt").should =~ /Disassembly of section .text:/
+  end
+
+  it "supports preprocessing C sources" do
+    test_dir("simple")
+    Rscons::Environment.new do |env|
+      env.Preprocess("simplepp.c", "simple.c")
+      env.Program("simple", "simplepp.c")
+    end
+    File.read("simplepp.c").should =~ /# \d+ "simple.c"/
+    `./simple`.should == "This is a simple C program\n"
+  end
+
+  it "supports preprocessing C++ sources" do
+    test_dir("simple_cc")
+    Rscons::Environment.new do |env|
+      env.Preprocess("simplepp.cc", "simple.cc")
+      env.Program("simple", "simplepp.cc")
+    end
+    File.read("simplepp.cc").should =~ /# \d+ "simple.cc"/
+    `./simple`.should == "This is a simple C++ program\n"
+  end
 end
@@ -0,0 +1,23 @@
+module Rscons
+  module Builders
+    describe CFile do
+      let(:env) {Environment.new}
+      subject {CFile.new}
+
+      it "invokes bison to create a .c file from a .y file" do
+        subject.should_receive(:standard_build).with("YACC parser.c", "parser.c", ["bison", "-d", "-o", "parser.c", "parser.y"], ["parser.y"], env, :cache)
+        subject.run("parser.c", ["parser.y"], :cache, env, {})
+      end
+
+      it "invokes a custom lexer to create a .cc file from a .ll file" do
+        env["LEX"] = "custom_lex"
+        subject.should_receive(:standard_build).with("LEX lexer.cc", "lexer.cc", ["custom_lex", "-o", "lexer.cc", "parser.ll"], ["parser.ll"], env, :cache)
+        subject.run("lexer.cc", ["parser.ll"], :cache, env, {})
+      end
+
+      it "raises an error when an unknown source file is specified" do
+        expect {subject.run("file.c", ["foo.bar"], :cache, env, {})}.to raise_error /Unknown source file .foo.bar. for CFile builder/
+      end
+    end
+  end
+end
@@ -5,123 +5,174 @@ module Rscons
    end

    def build_from(cache)
-      YAML.should_receive(:load).and_return(cache)
-      Cache.new
+      JSON.stub(:load) do
+        cache
      end
-
-    describe ".clear" do
-      it "removes the cache file" do
-        FileUtils.should_receive(:rm_f).with(Cache::CACHE_FILE)
-        Cache.clear
+      Cache.instance.tap do |cache|
+        cache.send(:initialize!)
      end
    end

    describe "#initialize" do
      context "when corrupt" do
        it "prints a warning and defaults to an empty hash" do
-          YAML.should_receive(:load).and_return("string")
+          JSON.should_receive(:load).and_return("string")
          $stderr.should_receive(:puts).with(/Warning:.*was.corrupt/)
-          Cache.new.instance_variable_get(:@cache).is_a?(Hash).should be_true
+          c = Cache.instance
+          c.send(:initialize!)
+          c.instance_variable_get(:@cache).is_a?(Hash).should be_true
        end
      end
    end

+    describe "#clear" do
+      it "removes the cache file" do
+        FileUtils.should_receive(:rm_f).with(Cache::CACHE_FILE)
+        JSON.stub(:load) {{}}
+        Cache.instance.clear
+      end
+    end
+
    describe "#write" do
-      it "should fill in :version and write to file" do
+      it "should fill in 'version' and write to file" do
        cache = {}
        fh = $stdout
        fh.should_receive(:puts)
        File.should_receive(:open).and_yield(fh)
        build_from(cache).write
-        cache[:version].should == Rscons::VERSION
+        cache["version"].should == Rscons::VERSION
      end
    end

    describe "#up_to_date?" do
+      empty_env = "env"
+      before do
+        empty_env.stub(:get_user_deps) { nil }
+      end
+
      it "returns false when target file does not exist" do
        File.should_receive(:exists?).with("target").and_return(false)
-        build_from({}).up_to_date?("target", "command", []).should be_false
+        build_from({}).up_to_date?("target", "command", [], empty_env).should be_false
      end

      it "returns false when target is not registered in the cache" do
        File.should_receive(:exists?).with("target").and_return(true)
-        build_from({}).up_to_date?("target", "command", []).should be_false
+        build_from({}).up_to_date?("target", "command", [], empty_env).should be_false
      end

      it "returns false when the target's checksum does not match" do
-        _cache = {targets: {"target" => {checksum: "abc"}}}
+        _cache = {"targets" => {"target" => {"checksum" => "abc"}}}
        cache = build_from(_cache)
        File.should_receive(:exists?).with("target").and_return(true)
        cache.should_receive(:calculate_checksum).with("target").and_return("def")
-        cache.up_to_date?("target", "command", []).should be_false
+        cache.up_to_date?("target", "command", [], empty_env).should be_false
      end

      it "returns false when the build command has changed" do
-        _cache = {targets: {"target" => {checksum: "abc", command: "old command"}}}
+        _cache = {"targets" => {"target" => {"checksum" => "abc", "command" => Digest::MD5.hexdigest("old command".inspect)}}}
        cache = build_from(_cache)
        File.should_receive(:exists?).with("target").and_return(true)
        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
-        cache.up_to_date?("target", "command", []).should be_false
+        cache.up_to_date?("target", "command", [], empty_env).should be_false
      end

      it "returns false when there is a new dependency" do
-        _cache = {targets: {"target" => {checksum: "abc",
-                                         command: "command",
-                                         deps: [{fname: "dep.1"}]}}}
+        _cache = {"targets" => {"target" => {"checksum" => "abc",
+                                         "command" => Digest::MD5.hexdigest("command".inspect),
+                                         "deps" => [{"fname" => "dep.1"}]}}}
        cache = build_from(_cache)
        File.should_receive(:exists?).with("target").and_return(true)
        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
-        cache.up_to_date?("target", "command", ["dep.1", "dep.2"]).should be_false
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"], empty_env).should be_false
      end

      it "returns false when a dependency's checksum has changed" do
-        _cache = {targets: {"target" => {checksum: "abc",
-                                         command: "command",
-                                         deps: [{fname: "dep.1",
-                                                 checksum: "dep.1.chk"},
-                                                {fname: "dep.2",
-                                                 checksum: "dep.2.chk"},
-                                                {fname: "extra.dep",
-                                                 checksum: "extra.dep.chk"}]}}}
+        _cache = {"targets" => {"target" => {"checksum" => "abc",
+                                         "command" => Digest::MD5.hexdigest("command".inspect),
+                                         "deps" => [{"fname" => "dep.1",
+                                                 "checksum" => "dep.1.chk"},
+                                                {"fname" => "dep.2",
+                                                 "checksum" => "dep.2.chk"},
+                                                {"fname" => "extra.dep",
+                                                 "checksum" => "extra.dep.chk"}],
+                                         "user_deps" => []}}}
        cache = build_from(_cache)
        File.should_receive(:exists?).with("target").and_return(true)
        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
        cache.should_receive(:calculate_checksum).with("dep.1").and_return("dep.1.chk")
        cache.should_receive(:calculate_checksum).with("dep.2").and_return("dep.2.changed")
-        cache.up_to_date?("target", "command", ["dep.1", "dep.2"]).should be_false
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"], empty_env).should be_false
      end

      it "returns false with strict_deps=true when cache has an extra dependency" do
-        _cache = {targets: {"target" => {checksum: "abc",
-                                         command: "command",
-                                         deps: [{fname: "dep.1",
-                                                 checksum: "dep.1.chk"},
-                                                {fname: "dep.2",
-                                                 checksum: "dep.2.chk"},
-                                                {fname: "extra.dep",
-                                                 checksum: "extra.dep.chk"}]}}}
+        _cache = {"targets" => {"target" => {"checksum" => "abc",
+                                         "command" => Digest::MD5.hexdigest("command".inspect),
+                                         "deps" => [{"fname" => "dep.1",
+                                                 "checksum" => "dep.1.chk"},
+                                                {"fname" => "dep.2",
+                                                 "checksum" => "dep.2.chk"},
+                                                {"fname" => "extra.dep",
+                                                 "checksum" => "extra.dep.chk"}],
+                                         "user_deps" => []}}}
        cache = build_from(_cache)
        File.should_receive(:exists?).with("target").and_return(true)
        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
-        cache.up_to_date?("target", "command", ["dep.1", "dep.2"], strict_deps: true).should be_false
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"], empty_env, strict_deps: true).should be_false
+      end
+
+      it "returns false when there is a new user dependency" do
+        _cache = {"targets" => {"target" => {"checksum" => "abc",
+                                         "command" => Digest::MD5.hexdigest("command".inspect),
+                                         "deps" => [{"fname" => "dep.1"}],
+                                         "user_deps" => []}}}
+        cache = build_from(_cache)
+        env = "env"
+        env.should_receive(:get_user_deps).with("target").and_return(["file.ld"])
+        File.should_receive(:exists?).with("target").and_return(true)
+        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
+        cache.up_to_date?("target", "command", ["dep.1"], env).should be_false
+      end
+
+      it "returns false when a user dependency checksum has changed" do
+        _cache = {"targets" => {"target" => {"checksum" => "abc",
+                                         "command" => Digest::MD5.hexdigest("command".inspect),
+                                         "deps" => [{"fname" => "dep.1",
+                                                 "checksum" => "dep.1.chk"},
+                                                {"fname" => "dep.2",
+                                                 "checksum" => "dep.2.chk"},
+                                                {"fname" => "extra.dep",
+                                                 "checksum" => "extra.dep.chk"}],
+                                         "user_deps" => [{"fname" => "user.dep",
+                                                      "checksum" => "user.dep.chk"}]}}}
+        cache = build_from(_cache)
+        env = "env"
+        env.should_receive(:get_user_deps).with("target").and_return(["user.dep"])
+        File.should_receive(:exists?).with("target").and_return(true)
+        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
+        cache.should_receive(:calculate_checksum).with("dep.1").and_return("dep.1.chk")
+        cache.should_receive(:calculate_checksum).with("dep.2").and_return("dep.2.chk")
+        cache.should_receive(:calculate_checksum).with("extra.dep").and_return("extra.dep.chk")
+        cache.should_receive(:calculate_checksum).with("user.dep").and_return("INCORRECT")
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"], env).should be_false
      end

      it "returns true when no condition for false is met" do
-        _cache = {targets: {"target" => {checksum: "abc",
-                                         command: "command",
-                                         deps: [{fname: "dep.1",
-                                                 checksum: "dep.1.chk"},
-                                                {fname: "dep.2",
-                                                 checksum: "dep.2.chk"},
-                                                {fname: "extra.dep",
-                                                 checksum: "extra.dep.chk"}]}}}
+        _cache = {"targets" => {"target" => {"checksum" => "abc",
+                                         "command" => Digest::MD5.hexdigest("command".inspect),
+                                         "deps" => [{"fname" => "dep.1",
+                                                 "checksum" => "dep.1.chk"},
+                                                {"fname" => "dep.2",
+                                                 "checksum" => "dep.2.chk"},
+                                                {"fname" => "extra.dep",
+                                                 "checksum" => "extra.dep.chk"}],
+                                         "user_deps" => []}}}
        cache = build_from(_cache)
        File.should_receive(:exists?).with("target").and_return(true)
        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
        cache.should_receive(:calculate_checksum).with("dep.1").and_return("dep.1.chk")
        cache.should_receive(:calculate_checksum).with("dep.2").and_return("dep.2.chk")
        cache.should_receive(:calculate_checksum).with("extra.dep").and_return("extra.dep.chk")
-        cache.up_to_date?("target", "command", ["dep.1", "dep.2"]).should be_true
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"], empty_env).should be_true
      end
    end

@@ -129,24 +180,30 @@ module Rscons
      it "stores the given information in the cache" do
        _cache = {}
        cache = build_from(_cache)
+        env = "env"
+        env.should_receive(:get_user_deps).with("the target").and_return(["user.dep"])
        cache.should_receive(:calculate_checksum).with("the target").and_return("the checksum")
        cache.should_receive(:calculate_checksum).with("dep 1").and_return("dep 1 checksum")
        cache.should_receive(:calculate_checksum).with("dep 2").and_return("dep 2 checksum")
-        cache.register_build("the target", "the command", ["dep 1", "dep 2"])
-        cached_target = cache.instance_variable_get(:@cache)[:targets]["the target"]
+        cache.should_receive(:calculate_checksum).with("user.dep").and_return("user.dep checksum")
+        cache.register_build("the target", "the command", ["dep 1", "dep 2"], env)
+        cached_target = cache.instance_variable_get(:@cache)["targets"]["the target"]
        cached_target.should_not be_nil
-        cached_target[:command].should == "the command"
-        cached_target[:checksum].should == "the checksum"
-        cached_target[:deps].should == [
-          {fname: "dep 1", checksum: "dep 1 checksum"},
-          {fname: "dep 2", checksum: "dep 2 checksum"},
+        cached_target["command"].should == Digest::MD5.hexdigest("the command".inspect)
+        cached_target["checksum"].should == "the checksum"
+        cached_target["deps"].should == [
+          {"fname" => "dep 1", "checksum" => "dep 1 checksum"},
+          {"fname" => "dep 2", "checksum" => "dep 2 checksum"},
+        ]
+        cached_target["user_deps"].should == [
+          {"fname" => "user.dep", "checksum" => "user.dep checksum"},
        ]
      end
    end

    describe "#targets" do
      it "returns a list of targets that are cached" do
-        cache = {targets: {"t1" => {}, "t2" => {}, "t3" => {}}}
+        cache = {"targets" => {"t1" => {}, "t2" => {}, "t3" => {}}}
        build_from(cache).targets.should == ["t1", "t2", "t3"]
      end
    end
@@ -168,11 +225,21 @@ module Rscons
        cache.mkdir_p("one\\two\\four")
        cache.directories.should == ["one/two", "one/two/three", "one/two/four"]
      end
+
+      it "handles absolute paths" do
+        _cache = {}
+        cache = build_from(_cache)
+        File.should_receive(:exists?).with("/one").and_return(true)
+        File.should_receive(:exists?).with("/one/two").and_return(false)
+        FileUtils.should_receive(:mkdir).with("/one/two")
+        cache.mkdir_p("/one/two")
+        cache.directories.should == ["/one/two"]
+      end
    end

    describe "#directories" do
      it "returns a list of directories that are cached" do
-        _cache = {directories: {"dir1" => true, "dir2" => true}}
+        _cache = {"directories" => {"dir1" => true, "dir2" => true}}
        build_from(_cache).directories.should == ["dir1", "dir2"]
      end
    end
@@ -1,12 +1,6 @@
 module Rscons
  describe Environment do
    describe "#initialize" do
-      it "stores the construction variables passed in" do
-        env = Environment.new("CFLAGS" => ["-g"], "CPPPATH" => ["dir"])
-        env["CFLAGS"].should == ["-g"]
-        env["CPPPATH"].should == ["dir"]
-      end
-
      it "adds the default builders when they are not excluded" do
        env = Environment.new
        env.builders.size.should be > 0
@@ -17,18 +11,10 @@ module Rscons
      end

      it "excludes the default builders with exclude_builders: :all" do
-        env = Environment.new(exclude_builders: :all)
+        env = Environment.new(exclude_builders: true)
        env.builders.size.should == 0
      end

-      it "excludes the named builders" do
-        env = Environment.new(exclude_builders: ["Library"])
-        env.builders.size.should be > 0
-        env.builders.find {|name, builder| name == "Object"}.should_not be_nil
-        env.builders.find {|name, builder| name == "Program"}.should_not be_nil
-        env.builders.find {|name, builder| name == "Library"}.should be_nil
-      end
-
      context "when a block is given" do
        it "yields self and invokes #process()" do
          env = Environment.new do |env|
@@ -60,9 +46,9 @@ module Rscons

    describe "#add_builder" do
      it "adds the builder to the list of builders" do
-        env = Environment.new(exclude_builders: :all)
+        env = Environment.new(exclude_builders: true)
        env.builders.keys.should == []
-        env.add_builder(Rscons::Object.new)
+        env.add_builder(Rscons::Builders::Object.new)
        env.builders.keys.should == ["Object"]
      end
    end
@@ -75,6 +61,18 @@ module Rscons
          env.get_build_fname("src\\dir\\other.d", ".a").should == "src/dir/other.a"
          env.get_build_fname("source.cc", ".o").should == "source.o"
        end
+
+        context "with a build_root" do
+          it "uses the build_root unless the path is absolute" do
+            env = Environment.new
+            env.build_root = "build/proj"
+            env.get_build_fname("src/dir/file.c", ".o").should == "build/proj/src/dir/file.o"
+            env.get_build_fname("/some/lib.c", ".a").should == "/some/lib.a"
+            env.get_build_fname("C:\\abspath\\mod.cc", ".o").should == "C:/abspath/mod.o"
+            env.get_build_fname("build\\proj\\generated.c", ".o").should == "build/proj/generated.o"
+            env.get_build_fname("build/proj.XX", ".yy").should == "build/proj/build/proj.yy"
+          end
+        end
      end

      context "with build directories" do
@@ -87,19 +85,36 @@ module Rscons
          env.get_build_fname("libs/otherlib/otherlib.cc", ".o").should == "build/libs/otherlib/otherlib.o"
          env.get_build_fname("other_directory/o.d", ".a").should == "other_directory/o.a"
        end
+
+        context "with a build_root" do
+          it "uses the build_root unless a build directory matches or the path is absolute" do
+            env = Environment.new
+            env.build_dir("src", "bld")
+            env.build_dir(%r{^libs/([^/]+)}, 'build/libs/\1')
+            env.build_root = "bldit"
+
+            env.get_build_fname("src/input.cc", ".o").should == "bld/input.o"
+            env.get_build_fname("libs/lib1/some/file.c", ".o").should == "build/libs/lib1/some/file.o"
+            env.get_build_fname("libs/otherlib/otherlib.cc", ".o").should == "build/libs/otherlib/otherlib.o"
+            env.get_build_fname("other_directory/o.d", ".a").should == "bldit/other_directory/o.a"
+            env.get_build_fname("bldit/some/mod.d", ".a").should == "bldit/some/mod.a"
+          end
+        end
      end
    end

    describe "#[]" do
      it "allows reading construction variables" do
-        env = Environment.new("CFLAGS" => ["-g", "-Wall"])
+        env = Environment.new
+        env["CFLAGS"] = ["-g", "-Wall"]
        env["CFLAGS"].should == ["-g", "-Wall"]
      end
    end

    describe "#[]=" do
      it "allows writing construction variables" do
-        env = Environment.new("CFLAGS" => ["-g", "-Wall"])
+        env = Environment.new
+        env["CFLAGS"] = ["-g", "-Wall"]
        env["CFLAGS"] -= ["-g"]
        env["CFLAGS"] += ["-O3"]
        env["CFLAGS"].should == ["-Wall", "-O3"]
@@ -110,7 +125,9 @@ module Rscons

    describe "#append" do
      it "allows adding many construction variables at once" do
-        env = Environment.new("CFLAGS" => ["-g"], "CPPPATH" => ["inc"])
+        env = Environment.new
+        env["CFLAGS"] = ["-g"]
+        env["CPPPATH"] = ["inc"]
        env.append("CFLAGS" => ["-Wall"], "CPPPATH" => ["include"])
        env["CFLAGS"].should == ["-Wall"]
        env["CPPPATH"].should == ["include"]
@@ -123,7 +140,8 @@ module Rscons
        env.Program("a.out", "main.c")

        cache = "cache"
-        Cache.should_receive(:new).and_return(cache)
+        Cache.should_receive(:instance).and_return(cache)
+        cache.should_receive(:clear_checksum_cache!)
        env.should_receive(:run_builder).with(anything, "a.out", ["main.c"], cache, {}).and_return(true)
        cache.should_receive(:write)

@@ -136,7 +154,8 @@ module Rscons
        env.Object("main.o", "other.cc")

        cache = "cache"
-        Cache.should_receive(:new).and_return(cache)
+        Cache.should_receive(:instance).and_return(cache)
+        cache.should_receive(:clear_checksum_cache!)
        env.should_receive(:run_builder).with(anything, "main.o", ["other.cc"], cache, {}).and_return("main.o")
        env.should_receive(:run_builder).with(anything, "a.out", ["main.o"], cache, {}).and_return("a.out")
        cache.should_receive(:write)
@@ -150,12 +169,40 @@ module Rscons
        env.Object("main.o", "other.cc")

        cache = "cache"
-        Cache.should_receive(:new).and_return(cache)
+        Cache.should_receive(:instance).and_return(cache)
+        cache.should_receive(:clear_checksum_cache!)
        env.should_receive(:run_builder).with(anything, "main.o", ["other.cc"], cache, {}).and_return(false)
        cache.should_receive(:write)

        expect { env.process }.to raise_error BuildError, /Failed.to.build.main.o/
      end
+
+      it "writes the cache when the Builder raises an exception" do
+        env = Environment.new
+        env.Object("module.o", "module.c")
+
+        cache = "cache"
+        Cache.should_receive(:instance).and_return(cache)
+        cache.should_receive(:clear_checksum_cache!)
+        env.stub(:run_builder) do |builder, target, sources, cache, vars|
+          raise "Ruby exception thrown by builder"
+        end
+        cache.should_receive(:write)
+
+        expect { env.process }.to raise_error RuntimeError, /Ruby exception thrown by builder/
+      end
+    end
+
+    describe "#clear_targets" do
+      it "resets @targets to an empty hash" do
+        env = Environment.new
+        env.Program("a.out", "main.o")
+        expect(env.instance_variable_get(:@targets).keys).to eq(["a.out"])
+
+        env.clear_targets
+
+        expect(env.instance_variable_get(:@targets).keys).to eq([])
+      end
    end

    describe "#build_command" do
@@ -170,13 +217,27 @@ module Rscons
      end
    end

+    describe "#expand_varref" do
+      it "returns the fully expanded variable reference" do
+        env = Environment.new
+        env["path"] = ["dir1", "dir2"]
+        env["flags"] = ["-x", "-y", "${specialflag}"]
+        env["specialflag"] = "-z"
+        env.expand_varref(["-p${path}", "${flags}"]).should == ["-pdir1", "-pdir2", "-x", "-y", "-z"]
+        env.expand_varref("foo").should == "foo"
+        expect {env.expand_varref("${foo}")}.to raise_error /expand.a.variable.reference/
+        env.expand_varref("${specialflag}").should == "-z"
+        env.expand_varref("${path}").should == ["dir1", "dir2"]
+      end
+    end
+
    describe "#execute" do
      context "with echo: :short" do
        context "with no errors" do
          it "prints the short description and executes the command" do
            env = Environment.new(echo: :short)
            env.should_receive(:puts).with("short desc")
-            env.should_receive(:system).with("a", "command", {}).and_return(true)
+            env.should_receive(:system).with("a", "command").and_return(true)
            env.execute("short desc", ["a", "command"])
          end
        end
@@ -185,7 +246,7 @@ module Rscons
          it "prints the short description, executes the command, and prints the failed command line" do
            env = Environment.new(echo: :short)
            env.should_receive(:puts).with("short desc")
-            env.should_receive(:system).with("a", "command", {}).and_return(false)
+            env.should_receive(:system).with("a", "command").and_return(false)
            $stdout.should_receive(:write).with("Failed command was: ")
            env.should_receive(:puts).with("a command")
            env.execute("short desc", ["a", "command"])
@@ -197,8 +258,8 @@ module Rscons
        it "prints the command executed and executes the command" do
          env = Environment.new(echo: :command)
          env.should_receive(:puts).with("a command '--arg=val with spaces'")
-          env.should_receive(:system).with("a", "command", "--arg=val with spaces", opt: :val).and_return(false)
-          env.execute("short desc", ["a", "command", "--arg=val with spaces"], opt: :val)
+          env.should_receive(:system).with({modified: :environment}, "a", "command", "--arg=val with spaces", {opt: :val}).and_return(false)
+          env.execute("short desc", ["a", "command", "--arg=val with spaces"], env: {modified: :environment}, options: {opt: :val})
        end
      end
    end
@@ -206,8 +267,7 @@ module Rscons
    describe "#method_missing" do
      it "calls the original method missing when the target method is not a known builder" do
        env = Environment.new
-        env.should_receive(:orig_method_missing).with(:foobar)
-        env.foobar
+        expect {env.foobar}.to raise_error /undefined method .foobar./
      end

      it "records the target when the target method is a known builder" do
@@ -217,7 +277,7 @@ module Rscons
        target = env.instance_variable_get(:@targets)["target"]
        target.should_not be_nil
        target[:builder].is_a?(Builder).should be_true
-        target[:source].should == ["src1", "src2"]
+        target[:sources].should == ["src1", "src2"]
        target[:vars].should == {var: "val"}
        target[:args].should == []
      end
@@ -228,6 +288,20 @@ module Rscons
      end
    end

+    describe "#depends" do
+      it "records the given dependencies in @user_deps" do
+        env = Environment.new
+        env.depends("foo", "bar", "baz")
+        env.instance_variable_get(:@user_deps).should == {"foo" => ["bar", "baz"]}
+      end
+      it "records user dependencies only once" do
+        env = Environment.new
+        env.instance_variable_set(:@user_deps, {"foo" => ["bar"]})
+        env.depends("foo", "bar", "baz")
+        env.instance_variable_get(:@user_deps).should == {"foo" => ["bar", "baz"]}
+      end
+    end
+
    describe "#build_sources" do
      class ABuilder < Builder
        def produces?(target, source, env)
@@ -1,6 +0,0 @@
-describe "Module#short_name" do
-  it "returns the inner name of the module" do
-    Rscons::Environment.short_name.should == "Environment"
-    Rscons::Object.short_name.should == "Object"
-  end
-end
@@ -1,6 +1,6 @@
 module Rscons
  describe VarSet do
-    describe '.initialize' do
+    describe '#initialize' do
      it "initializes variables from a Hash" do
        v = VarSet.new({"one" => 1, "two" => :two})
        v["one"].should == 1
@@ -20,25 +20,19 @@ module Rscons
      end
    end

-    describe :[] do
+    describe "#[]" do
+      it "allows accessing a variable with its verbatim value if type is not specified" do
        v = VarSet.new({"fuz" => "a string", "foo" => 42, "bar" => :baz,
                        "qax" => [3, 6], "qux" => {a: :b}})
-      it "allows accessing a variable with its verbatim value if type is not specified" do
        v["fuz"].should == "a string"
        v["foo"].should == 42
        v["bar"].should == :baz
        v["qax"].should == [3, 6]
        v["qux"].should == {a: :b}
      end
-      it "allows accessing a non-array converted to an array" do
-        v["fuz", :array].should == ["a string"]
-      end
-      it "allows accessing an array as a single value" do
-        v["qax", :scalar].should == 3
-      end
    end

-    describe :[]= do
+    describe "#[]=" do
      it "allows assigning to variables" do
        v = VarSet.new("CFLAGS" => ["-Wall", "-O3"])
        v["CPPPATH"] = ["one", "two"]
@@ -47,40 +41,86 @@ module Rscons
      end
    end

-    describe '.append' do
+    describe "#include?" do
+      it "returns whether the variable is in the VarSet" do
+        v = VarSet.new("CFLAGS" => [], :foo => :bar)
+
+        expect(v.include?("CFLAGS")).to be_true
+        expect(v.include?(:CFLAGS)).to be_false
+        expect(v.include?(:foo)).to be_true
+        expect(v.include?("foo")).to be_false
+        expect(v.include?("bar")).to be_false
+
+        v2 = v.clone
+        v2.append("bar" => [])
+
+        expect(v2.include?("CFLAGS")).to be_true
+        expect(v2.include?(:CFLAGS)).to be_false
+        expect(v2.include?(:foo)).to be_true
+        expect(v2.include?("foo")).to be_false
+        expect(v2.include?("bar")).to be_true
+      end
+    end
+
+    describe '#append' do
      it "adds values from a Hash to the VarSet" do
        v = VarSet.new("LDFLAGS" => "-lgcc")
        v.append("LIBS" => "gcc", "LIBPATH" => ["mylibs"])
-        v.vars.keys.should =~ ["LDFLAGS", "LIBS", "LIBPATH"]
+        expect(v["LDFLAGS"]).to eq("-lgcc")
+        expect(v["LIBS"]).to eq("gcc")
+        expect(v["LIBPATH"]).to eq(["mylibs"])
      end
+
      it "adds values from another VarSet to the VarSet" do
        v = VarSet.new("CPPPATH" => ["mydir"])
        v2 = VarSet.new("CFLAGS" => ["-O0"], "CPPPATH" => ["different_dir"])
        v.append(v2)
-        v.vars.keys.should =~ ["CPPPATH", "CFLAGS"]
-        v["CPPPATH"].should == ["different_dir"]
+        expect(v["CFLAGS"]).to eq(["-O0"])
+        expect(v["CPPPATH"]).to eq(["different_dir"])
+      end
+
+      it "does not pick up subsequent variable changes from a given VarSet" do
+        v = VarSet.new("dirs" => ["a"])
+        v2 = VarSet.new
+        v2.append(v)
+        v["dirs"] << "b"
+        expect(v["dirs"]).to eq(["a", "b"])
+        expect(v2["dirs"]).to eq(["a"])
      end
    end

-    describe '.merge' do
+    describe '#merge' do
      it "returns a new VarSet merged with the given Hash" do
        v = VarSet.new("foo" => "yoda")
        v2 = v.merge("baz" => "qux")
-        v.vars.keys.should == ["foo"]
-        v2.vars.keys.should =~ ["foo", "baz"]
+        expect(v["foo"]).to eq("yoda")
+        expect(v2["foo"]).to eq("yoda")
+        expect(v2["baz"]).to eq("qux")
      end
+
      it "returns a new VarSet merged with the given VarSet" do
        v = VarSet.new("foo" => ["a", "b"], "bar" => 42)
        v2 = v.merge(VarSet.new("bar" => 33, "baz" => :baz))
        v2["foo"] << "c"
-        v["foo"].should == ["a", "b"]
-        v["bar"].should == 42
-        v2["foo"].should == ["a", "b", "c"]
-        v2["bar"].should == 33
+        expect(v["foo"]).to eq ["a", "b"]
+        expect(v["bar"]).to eq 42
+        expect(v2["foo"]).to eq ["a", "b", "c"]
+        expect(v2["bar"]).to eq 33
+      end
+
+      it "does not pick up subsequent variable changes from a given VarSet" do
+        v = VarSet.new("var" => ["a", "b"], "var2" => ["1", "2"])
+        v["var2"] << "3"
+        v2 = v.clone
+        v["var"] << "c"
+        expect(v["var"]).to eq(["a", "b", "c"])
+        expect(v["var2"]).to eq(["1", "2", "3"])
+        expect(v2["var"]).to eq(["a", "b"])
+        expect(v2["var2"]).to eq(["1", "2", "3"])
      end
    end

-    describe '.expand_varref' do
+    describe '#expand_varref' do
      v = VarSet.new("CFLAGS" => ["-Wall", "-O2"],
                     "CC" => "gcc",
                     "CPPPATH" => ["dir1", "dir2"],
@@ -2,7 +2,7 @@ describe Rscons do
  describe ".clean" do
    it "removes all build targets and created directories" do
      cache = "cache"
-      Rscons::Cache.should_receive(:new).and_return(cache)
+      Rscons::Cache.should_receive(:instance).and_return(cache)
      cache.should_receive(:targets).and_return(["build/a.out", "build/main.o"])
      FileUtils.should_receive(:rm_f).with("build/a.out")
      FileUtils.should_receive(:rm_f).with("build/main.o")
@@ -18,7 +18,7 @@ describe Rscons do
      Dir.should_receive(:rmdir).with("build")
      File.should_receive(:directory?).with("other").and_return(true)
      Dir.should_receive(:entries).with("other").and_return([".", "..", "other.file"])
-      Rscons::Cache.should_receive(:clear)
+      cache.should_receive(:clear)

      Rscons.clean
    end
Author	SHA1	Message	Date
josh	03ffb39956	v1.4.0	2014-04-15 16:19:19 -04:00
josh	0a10af3f5e	update README.md for v1.4.0 release notes	2014-04-15 16:18:58 -04:00
josh	ddf00d08a7	shortcut all of Environment#process if @targets is empty	2014-04-15 16:18:33 -04:00
josh	8be1842cf8	update documentation for new builders	2014-04-15 16:06:00 -04:00
josh	d424facf7f	Add Preprocess and Disassemble builders	2014-04-15 15:21:55 -04:00
josh	ee5aca275d	Write Cache to disk if an exception occurs while processing the Environment - fix #4	2014-04-15 14:20:30 -04:00
josh	ea30b0b5ee	Fix Cache#mkdir_p to handle absolute paths - fix #5	2014-04-15 14:15:32 -04:00
josh	5a0d80b781	Cache: implement "dirty" attribute to only re-serialize when necessary	2014-04-15 14:11:10 -04:00
josh	a2653a77d1	shortcut Environment#process if @targets is empty	2014-04-15 14:04:59 -04:00
josh	160434b903	Cache: change to a Singleton object so it is only loaded from disk once	2014-04-15 14:02:26 -04:00
josh	5ce8940d54	stop encoding Cache contents	2014-04-15 13:39:45 -04:00
josh	1a5e9ddaa6	Implement copy-on-write semantics for VarSet, speeding up Environment cloning	2014-04-15 11:21:15 -04:00
josh	5924154229	speed up VarSet#deep_dup a bit	2014-04-15 09:47:05 -04:00
josh	5beda54374	do not clone @varset when appending to the cloned environment since appending will do its own clone	2014-04-15 09:36:30 -04:00
josh	ae0ad98075	use @varset.append() instead of @varset.send(:append)	2014-04-15 09:32:35 -04:00
josh	f5be3a3571	VarSet: implement deep copying ourselves instead of using Marshal for a speed increase	2014-04-15 09:16:30 -04:00
josh	fdc5c8773c	Issue #7 - store MD5 of build command instead of the full command in the cache	2014-04-14 17:17:54 -04:00
josh	c61380b354	Issue #7 - change .rsconscache from using YAML to JSON to speed up parsing	2014-04-14 16:52:21 -04:00
josh	d8dda291a5	ensure that Dir[] results are predictable in build tests	2014-04-14 13:13:43 -04:00
josh	1fe2c6401d	expand ^/ in target paths to be relative to the build root	2014-03-27 13:30:11 -04:00
josh	4818fd10fe	README.md: add more details about Environment cloning	2014-03-27 12:02:46 -04:00
josh	5989e24ee6	update some documentation	2014-03-27 11:57:45 -04:00
josh	1875a2ea66	Pass the Environment object to build hooks in the :env key of the build_op parameter	2014-03-27 10:44:10 -04:00
josh	cbd5816b4b	add VarSet#include?	2014-03-27 10:39:46 -04:00
josh	b2c970c9ca	add Environment#add_target and use it from Environment#method_missing	2014-03-26 11:29:02 -04:00
josh	92a9982988	use #super from #method_missing instead of method aliasing	2014-03-26 11:23:32 -04:00
josh	533ee9c16c	add CFile builder to create C/C++ sources from lex/yacc input files	2014-03-18 21:57:53 -04:00
josh	831b9bf2c7	v1.3.0	2014-02-25 12:18:02 -05:00
josh	031395bb57	add v1.3.0 release notes	2014-02-25 12:17:49 -05:00
josh	e3aeb7f4d7	Change Environment#execute() options Hash to contain :env and :options keys for Kernel#system()	2014-02-25 12:14:52 -05:00
josh	6aa5037234	v1.2.0	2014-02-20 16:42:10 -05:00
josh	0d8f661fd4	add :clone option to Environment#clone to control exactly which Environment attributes are cloned	2014-02-19 15:02:46 -05:00
josh	e5ca8776a9	allow nil to be passed in to Environment#build_root=	2014-02-19 15:02:18 -05:00
josh	2dde39a0ec	standardize on "Rscons" capitalization	2014-02-18 16:14:44 -05:00
josh	af0679708c	v1.1.0	2014-02-17 16:37:59 -05:00
josh	4b0d0c3957	README: add Release Notes section	2014-02-17 16:15:49 -05:00
josh	202f10b86f	README: add example for custom builder with multiple output files	2014-02-17 16:14:10 -05:00
josh	1d47db3144	support passing multiple targets to Cache#up_to_date? and #register_build	2014-02-17 16:10:15 -05:00
josh	f7b7a4fefa	v1.0.0	2014-02-14 10:46:31 -05:00
josh	00b038ef50	use require_relative instead of require	2014-02-14 10:37:41 -05:00
josh	98f8f38715	remove String#set_suffix monkey patch	2014-02-14 10:36:15 -05:00
josh	2ffb5d525a	remove String#absolute_path? monkey patch	2014-02-14 10:32:57 -05:00
josh	fa7d17675b	remove String#has_suffix? monkey-patch; use String#end_with?	2014-02-14 10:20:32 -05:00
josh	b43c473762	README: add link to API documentation at rubydoc.info	2014-02-14 09:57:46 -05:00
josh	f278b211f7	README: add more information about custom builders	2014-02-14 09:50:39 -05:00
josh	c897bcf06e	README.md fixes/tweaks	2014-02-14 09:42:04 -05:00
josh	7c89dddbd6	v0.3.1	2014-01-23 14:40:45 -05:00
josh	c07d9f86a6	bugfix: loading a Cache without deps or user_deps stored causes an exception	2014-01-23 14:40:30 -05:00
josh	ff26da8865	fix custom builder examples in README.md	2014-01-15 16:57:46 -05:00
josh	5ff555cf6a	add Environment#expand_varref()	2014-01-02 11:49:08 -05:00
josh	e3aadc562f	Rscons::Varset: remove unused type parameter to #[]	2014-01-02 11:05:15 -05:00
josh	7ff2ec1f1a	v0.3.0	2013-12-31 14:10:47 -05:00
josh	5362f761e6	move default builder classes into Rscons::Builders namespace module	2013-12-31 13:31:17 -05:00
josh	cdb3352b4e	remove module monkey-patching; add Builder#name()	2013-12-31 13:10:00 -05:00
josh	08bc390d40	Rscons::BuildError inherits from RuntimeError instead of Exception	2013-12-31 13:08:38 -05:00
josh	f8af0630b0	pass env to Cache#up_to_date?() and #register_build() instead of user_deps	2013-12-31 12:46:30 -05:00
josh	1868193b54	do not prepend build_root to source files that are already inside build_root	2013-12-31 10:15:19 -05:00
josh	8976d7dea2	update README custom builder examples	2013-12-27 15:01:02 -05:00
josh	295324eafd	add Environment#depends() to specify user dependencies for a build target	2013-12-27 14:31:46 -05:00
josh	7330e74ab8	modify Cache to store user-specified extra dependencies	2013-12-27 14:20:32 -05:00
josh	a28cef9eb7	change "vars" parameters to be required	2013-12-27 13:53:40 -05:00
josh	e667046da8	add Environment#clear_targets()	2013-12-27 13:35:16 -05:00
josh	539a49fe90	do not allow construction variables as arguments to Environment#initialize() or Environment#clone()	2013-12-27 12:10:54 -05:00
josh	7681c7584f	add String#absolute_path?	2013-12-27 11:40:24 -05:00
josh	8fcbd39057	v0.2.2	2013-11-13 23:52:33 -05:00
josh	d0bbc78751	Program: do not continue executing builder if building a source fails	2013-11-13 23:52:15 -05:00
josh	7249e57951	add info to error message when expanding unknown variable types	2013-11-13 23:50:46 -05:00
josh	d01913641f	v0.2.1	2013-11-11 11:36:10 -05:00
josh	d5be569cd5	fix Environment#clone() to allow subclassing	2013-11-11 11:35:59 -05:00