v1.9.3

Return a BuildTarget object from Environment#method_missing when a build target is registered.

.gitignore

@@ -1,18 +1,6 @@
-*.gem
+/.yardoc/
-*.rbc
+/_yardoc/
-.bundle
+/coverage/
-.config
+/doc/
-.yardoc
+/pkg/
-Gemfile.lock
+/build_test_run/
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-build_tests_run

Gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: .
+  specs:
+    rscons (1.9.3)
+      json (~> 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    json (1.8.3)
+    rake (10.4.2)
+    rdoc (4.2.0)
+      json (~> 1.4)
+    redcarpet (3.3.3)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.1)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    simplecov (0.11.1)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+  x86-mingw32
+
+DEPENDENCIES
+  rake
+  rdoc
+  redcarpet
+  rscons!
+  rspec
+  simplecov
+  yard
+
+BUNDLED WITH
+   1.10.6

README.md

@@ -1,16 +1,19 @@
 # Rscons
 
-Software construction library inspired by SCons and implemented in Ruby
+Rscons is a software construction framework inspired by SCons and implemented
+in Ruby.
+
+[![Gem Version](https://badge.fury.io/rb/rscons.png)](http://badge.fury.io/rb/rscons)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'rscons'
+    gem "rscons"
 
 And then execute:
 
-    $ bundle
+    $ bundle install
 
 Or install it yourself as:
 
@@ -18,20 +21,524 @@ Or install it yourself as:
 
 ## Usage
 
-    RScons::Environment.new do |env|
+Rscons is implemented as a Ruby library and distributed as a gem.
-      env.Program('program', Dir['*.c'])
+It also provides a "rscons" executable which can evaluate a build script (by
-    end
+default named Rsconsfile or Rsconsfile.rb).
+It can also be used from rake or from a standalone Ruby script.
 
-    main_env = RScons::Environment.new do |env|
+### Example: Building a C Program
-      env.build_dir('src', 'build/main')
-      env.Program('program', Dir['src/**/*.cc'])
-    end
 
-    debug_env = main_env.clone do |env|
+```ruby
-      env.build_dir('src', 'build/debug')
+Rscons::Environment.new do |env|
-      env['CFLAGS'] = ['-g', '-O0']
+  env["CFLAGS"] << "-Wall"
-      env.Program('program-debug', Dir['src/**/*.cc'])
+  env.Program("program", Dir["**/*.c"])
+end
+```
+
+### Example: Building a D Program
+
+```ruby
+Rscons::Environment.new do |env|
+  env["DFLAGS"] << "-Wall"
+  env.Program("program", Dir["**/*.d"])
+end
+```
+
+### Example: Cloning an Environment
+
+```ruby
+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"]
+  env["LIBS"] = ["SDL"]
+  env.Program("program", Dir["src/**/*.cc"])
+end
+
+debug_env = main_env.clone do |env|
+  # Store object files from sources under "src" in "build/debug"
+  env.build_dir("src", "build/debug")
+  env["CFLAGS"] -= ["-O3"]
+  env["CFLAGS"] += ["-g", "-O0"]
+  env.Program("program-debug", Dir["src/**/*.cc"])
+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: Custom Builder Using Environment#add_builder()
+
+The `add_builder` method of the `Rscons::Environment` class optionally allows
+you to define and register a builder by providing a name and action block. This
+can be useful if the builder you are trying to define is easily expressed as a
+short ruby procedure. When `add_builder` is called in this manner a new builder
+will be registered with the environment with the given name. When this builder
+is used it will call the provided block in order to build the target.
+
+```ruby
+Rscons::Environment.new do |env|
+  env.add_builder(:JsonToYaml) do |target, sources, cache, env, vars|
+    unless cache.up_to_date?(target, :JsonToYaml, sources, env)
+      cache.mkdir_p(File.dirname(target))
+      File.open(target, 'w') do |f|
+        f.write(YAML.dump(JSON.load(IO.read(sources.first))))
+      end
+      cache.register_build(target, :JsonToYaml, sources, env)
+    end
+    target
+  end
+  env.JsonToYaml('foo.yml','foo.json')
+end
+```
+
+### Example: Using different compilation flags for some sources
+
+```ruby
+Rscons::Environment.new do |env|
+  env["CFLAGS"] = ["-O3", "-Wall", "-DDEFINE"]
+  env.add_build_hook do |build_op|
+    if build_op[:target] =~ %r{build/third-party}
+      build_op[:vars]["CFLAGS"] -= ["-Wall"]
+    end
+  end
+  env.build_dir("src", "build")
+  env.Program("program", Dir["**/*.cc"])
+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.
+
+Build hooks can alter construction variable values for a particular build
+operation. Build hooks can also register new build targets.
+
+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
+Rscons::Environment.new do |env|
+  env.Library("mylib.a", Dir["src/**/*.c"])
+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
+
+### Builders
+
+Rscons ships with a number of builders:
+
+* Command, which executes a user-defined command to produce the target.
+* Copy, which is identical to Install.
+* 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.
+* Install, which installs files or directories to a specified destination.
+* 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 builders,
+you can use the `exclude_builders` key to the Environment constructor.
+
+#### Command
+
+```ruby
+env.Command(target, sources, "CMD" => command)
+# Example
+env.Command("docs.html", "docs.md",
+    "CMD" => ["pandoc", "-fmarkdown", "-thtml", "-o${_TARGET}", "${_SOURCES}"],
+    "CMD_DESC" => "PANDOC")
+```
+
+The command builder executes a user-defined command in order to produce the
+desired target file based on the provided source files.
+
+#### 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.
+
+#### Install
+
+```ruby
+env.Install(destination, sources)
+# Example
+env.Install("dist/bin", "app.exe")
+env.Install("dist/share", "share")
+```
+
+#### 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
+
+An Rscons::Environment consists of:
+
+* a collection of construction variables
+* a collection of builders
+* 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, 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:
+
+```ruby
+base_env = Rscons::Environment.new
+base_env["CPPPATH"] = ["one", "two"]
+cloned_env = base_env.clone
+cloned_env["CPPPATH"] << "three"
+```
+
+`base_env["CPPPATH"]` will not include "three".
+
+#### Build Hooks
+
+Environments can have build hooks which are added with `env.add_build_hook()`.
+Build hooks are invoked immediately before a builder executes.
+Build hooks can modify the construction variables in use for the build
+operation.
+They can also register new build targets.
+
+Environments can also have post-build hooks added with `env.add_post_build_hook()`.
+Post-build hooks are only invoked if the build operation was a success.
+Post-build hooks can invoke commands using the newly-built files, or register
+new build targets.
+
+### Phony Targets
+
+A build target name given as a Symbol instead of a String is interpreted as a
+"phony" target.
+Phony targets operate similarly to normal build targets, except that a file is
+not expected to be produced by the builder.
+Phony targets will still be "rebuilt" if any source or the command is out of
+date.
+
+### Explicit Dependencies
+
+A target can be marked as depending on another file that Rscons would not
+otherwise know about via the `Environment#depends` function. For example,
+to force the linker to re-link a Program output when a linker script changes:
+
+```ruby
+Rscons::Environment.new do |env|
+  env.Program("a.out", "foo.c", "LDFLAGS" => %w[-T linker_script.ld])
+  env.depends("a.out", "linker_script.ld")
+end
+```
+
+You can pass multiple dependency files to `Environment#depends`:
+
+```ruby
+env.depends("my_app", "config/link.ld", "README.txt", *Dir.glob("assets/**/*"))
+```
+
+### Construction Variable Naming
+
+* 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.9.2
+
+- allow phony targets in conjunction with build roots
+
+### v1.9.1
+
+- change *SUFFIX defaults to arrays
+- add various C++ file suffixes
+- use ${INCPREFIX} instead of hard-coded "-I" in Preprocess builder
+
+### v1.9.0
+
+#### New Features
+
+- #6 - add Install and Copy builders
+- #22 - allow overriding Command builder short description with CMD_DESC variable
+- #24 - add "rscons" executable
+- #25 - add support for phony targets given as Symbols instead of Strings
+- #26 - support registering multiple build targets with the same target name
+- #27 - add Directory builder
+
+#### Fixes
+
+- #20 - fix variable references that expand to arrays in build target sources
+- #21 - rework Preprocess builder to consider deep dependencies
+- fix Rscons.set_suffix to append the given suffix if the filename has none
+- remove ${CFLAGS} from default CPP_CMD
+
+### v1.8.1
+
+- fix Environment#dump when construction variables are symbols
+
+### v1.8.0
+
+- new Command builder to execute arbitrary user commands
+- new SimpleBuilder class
+  - create new builders quickly by passing a block to Environment#add_builder
+- improved YARD documentation
+- add Environment#dump to debug Environment construction variables
+
+### v1.7.0
+
+- allow build hooks to register new build targets
+- add post-build hooks (register with Environment#add_post_build_hook)
+- clear all build targets after processing an Environment
+- allow trailing slashes in arguments to Environment#build_dir
+
+### v1.6.1
+
+- add DEPFILESUFFIX construction variable to override dependency file suffix
+- fix Environment#depends to expand its arguments for construction variables
+
+### v1.6.0
+
+- support lambdas as construction variable values
+
+### v1.5.0
+
+- add "json" as a runtime dependency
+- update construction variables to match SCons more closely
+  - add CPPDEFPREFIX, INCPREFIX, CPPDEFINES, CCFLAGS, LIBDIRPREFIX, and LIBLINKPREFIX
+- add Environment#shell
+- add Environment#parse_flags, #parse_flags!, #merge_flags
+- unbuffer $stdout by default
+- add PROGSUFFIX construction variable (defaults to .exe on MinGW/Cygwin)
+- add Rscons::BuildTarget and Builder#create_build_target
+- update specs to RSpec 3.x and fix to run on MinGW/Cygwin/Linux
+- add YARD documentation to get to 100% coverage
+
+### v1.4.3
+
+- fix builders properly using construction variable overrides
+- expand nil construction variables to empty strings
+
+### v1.4.2
+
+- add Environment#expand_path
+- expand construction variable references in builder targets and sources before invoking builder
+
+### v1.4.1
+
+- fix invoking a builder with no sources while a build root defined
+
+### 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
 

Rakefile.rb

@@ -7,12 +7,17 @@ end
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-require "rake/clean"
 require "yard"
+require "rake/clean"
 
-CLEAN.include 'build_tests_run'
+CLEAN.include %w[build_test_run .yardoc doc coverage]
+CLOBBER.include %w[pkg]
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec, :example_string) do |task, args|
+  if args.example_string
+    task.rspec_opts = %W[-e "#{args.example_string}" -f documentation]
+  end
+end
 
 YARD::Rake::YardocTask.new do |yard|
   yard.files = ['lib/**/*.rb']

bin/rscons

@@ -0,0 +1,3 @@
+require "rscons/cli"
+
+Rscons::Cli.run(ARGV)

build_tests/build_dir/build.rb

@@ -1,5 +0,0 @@
-Rscons::Environment.new do |env|
-  env.append('CPPPATH' => Dir['src/**/*/'])
-  env.build_dir('src', 'build')
-  env.Program('build_dir', Dir['src/**/*.c'])
-end

build_tests/clone_env/build.rb

@@ -1,11 +0,0 @@
-debug = Rscons::Environment.new do |env|
-  env.build_dir('src', 'debug')
-  env['CFLAGS'] = '-O2'
-  env['CPPFLAGS'] = '-DSTRING="Debug Version"'
-  env.Program('program-debug', Dir['src/*.c'])
-end
-
-release = debug.clone('CPPFLAGS' => '-DSTRING="Release Version"') do |env|
-  env.build_dir('src', 'release')
-  env.Program('program-release', Dir['src/*.c'])
-end

build_tests/custom_builder/build.rb

@@ -1,16 +0,0 @@
-class MySource < Rscons::Builder
-  def run(target, sources, cache, env, vars = {})
-    File.open(target, 'w') do |fh|
-      fh.puts <<EOF
-#define THE_VALUE 5678
-EOF
-    end
-    target
-  end
-end
-
-Rscons::Environment.new(echo: :short) do |env|
-  env.add_builder(MySource.new)
-  env.MySource('inc.h', [])
-  env.Program('program', Dir['*.c'])
-end

build_tests/d/main.d

@@ -0,0 +1,6 @@
+import std.stdio;
+
+void main()
+{
+    writeln("Hello from D!");
+}

build_tests/header/build.rb

@@ -1,3 +0,0 @@
-Rscons::Environment.new(echo: :short) do |env|
-  env.Program('header', Dir['*.c'])
-end

build_tests/json_to_yaml/foo.json

@@ -0,0 +1 @@
+{ "key": "value" }

build_tests/library/build.rb

@@ -1,4 +0,0 @@
-Rscons::Environment.new(echo: :command) do |env|
-  env.Program('library', ['lib.a', 'three.c'])
-  env.Library("lib.a", ['one.c', 'two.c'], 'CPPFLAGS' => ['-Dmake_lib'])
-end

build_tests/preprocess/bar.h

@@ -0,0 +1 @@
+#define BAR xyz42abc

build_tests/preprocess/foo.h

@@ -0,0 +1,2 @@
+#include "bar.h"
+BAR

build_tests/simple/build.rb

@@ -1,4 +0,0 @@
-Rscons::Environment.new do |env|
-  # CHANGE FLAGS
-  env.Program('simple', Dir['*.c'])
-end

build_tests/simple_cc/build.rb

@@ -1,4 +0,0 @@
-Rscons::Environment.new do |env|
-  # CHANGE FLAGS
-  env.Program('simple', Dir['*.cc'])
-end

build_tests/two_sources/build.rb

@@ -1,4 +0,0 @@
-Rscons::Environment.new(echo: :command) do |env|
-  env.Object("one.o", "one.c", 'CPPFLAGS' => ['-DONE'])
-  env.Program('two_sources', ['one.o', 'two.c'])
-end

lib/rscons.rb

@@ -1,25 +1,153 @@
-require "rscons/builder"
+require_relative "rscons/build_target"
-require "rscons/cache"
+require_relative "rscons/builder"
-require "rscons/environment"
+require_relative "rscons/cache"
-require "rscons/varset"
+require_relative "rscons/environment"
-require "rscons/version"
+require_relative "rscons/varset"
-
+require_relative "rscons/version"
-require "rscons/monkey/module"
-require "rscons/monkey/string"
 
 # default builders
-require "rscons/builders/library"
+require_relative "rscons/builders/cfile"
-require "rscons/builders/object"
+require_relative "rscons/builders/command"
-require "rscons/builders/program"
+require_relative "rscons/builders/directory"
+require_relative "rscons/builders/disassemble"
+require_relative "rscons/builders/install"
+require_relative "rscons/builders/library"
+require_relative "rscons/builders/object"
+require_relative "rscons/builders/preprocess"
+require_relative "rscons/builders/program"
+require_relative "rscons/builders/simple_builder"
 
 # Namespace module for rscons classes
 module Rscons
+
+  # Names of the default builders which will be added to all newly created
+  # {Environment} objects.
   DEFAULT_BUILDERS = [
-    Library,
+    :CFile,
-    Object,
+    :Command,
-    Program,
+    :Copy,
+    :Directory,
+    :Disassemble,
+    :Install,
+    :Library,
+    :Object,
+    :Preprocess,
+    :Program,
   ]
 
-  class BuildError < Exception
+  # Class to represent a fatal error while building a target.
+  class BuildError < RuntimeError; end
+
+  class << self
+
+    # Remove all generated files.
+    #
+    # @return [void]
+    def clean
+      cache = Cache.instance
+      # remove all built files
+      cache.targets.each do |target|
+        FileUtils.rm_f(target)
+      end
+      # remove all created directories if they are empty
+      cache.directories.sort {|a, b| b.size <=> a.size}.each do |directory|
+        next unless File.directory?(directory)
+        if (Dir.entries(directory) - ['.', '..']).empty?
+          Dir.rmdir(directory) rescue nil
+        end
+      end
+      cache.clear
+    end
+
+    # Return whether the given path is an absolute filesystem path.
+    #
+    # @param path [String] the path to examine.
+    #
+    # @return [Boolean] Whether the given path is an absolute filesystem path.
+    def absolute_path?(path)
+      path =~ %r{^(/|\w:[\\/])}
+    end
+
+    # Return whether the given target is a phony target.
+    #
+    # @param target [Symbol, String] Target name.
+    #
+    # @return [Boolean] Whether the given target is a phony target.
+    def phony_target?(target)
+      target.is_a?(Symbol)
+    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, e.g. ".exe".
+    #
+    # @return [String] New path.
+    def set_suffix(path, suffix)
+      path.sub(/\.[^.]*$/, "") + suffix
+    end
+
+    # Return the system shell and arguments for executing a shell command.
+    #
+    # @return [Array<String>] The shell and flag.
+    def get_system_shell
+      @shell ||=
+        begin
+          test_shell = lambda do |*args|
+            begin
+              "success" == IO.popen([*args, "echo success"]) do |io|
+                io.read.strip
+              end
+            rescue
+              false
+            end
+          end
+          if ENV["SHELL"] and ENV["SHELL"] != "" and test_shell[ENV["SHELL"], "-c"]
+            [ENV["SHELL"], "-c"]
+          elsif Object.const_get("RUBY_PLATFORM") =~ /mingw/
+            if test_shell["sh", "-c"]
+              # Using Rscons from MSYS should use MSYS's shell.
+              ["sh", "-c"]
+            else
+              ["cmd", "/c"]
+            end
+          else
+            ["sh", "-c"]
+          end
+        end
+    end
+
+    # Return an Array containing a command used to execute commands.
+    #
+    # This will normally be an empty Array, but on Windows if Rscons detects
+    # that it is running in MSYS then ["env"] will be returned.
+    #
+    # @return [Array<String>] Command used to execute commands.
+    def command_executer
+      @command_executer ||=
+        if Object.const_get("RUBY_PLATFORM") =~ /mingw/
+          if ENV.keys.find {|key| key =~ /MSYS/}
+            begin
+              if IO.popen(["env", "echo", "success"]) {|io| io.read.strip} == "success"
+                ["env"]
+              end
+            rescue
+            end
+          end
+        end || []
+    end
+
+    # Set the command executer array.
+    #
+    # @param val [Array<String>] Command used to execute commands.
+    #
+    # @return [Array<String>] Command used to execute commands.
+    def command_executer=(val)
+      @command_executer = val
+    end
+
   end
 end
+
+# Unbuffer $stdout
+$stdout.sync = true

lib/rscons/build_target.rb

@@ -0,0 +1,36 @@
+module Rscons
+  # The BuildTarget class represents a single build target.
+  class BuildTarget
+    # Create a BuildTarget object.
+    #
+    # @param options [Hash] Options to create the BuildTarget with.
+    # @option options [Environment] :env
+    #   The Environment.
+    # @option options [String] :target
+    #   The user-supplied target name.
+    # @option options [Array<String>] :sources
+    #   The user-supplied source file name(s).
+    def initialize(options)
+      @env = options[:env]
+      @target = options[:target]
+    end
+
+    # Manually record a given target as depending on the specified files.
+    #
+    # @param user_deps [Array<String>] Dependency files.
+    #
+    # @return [void]
+    def depends(*user_deps)
+      @env.depends(@target, *user_deps)
+    end
+
+    # Convert the BuildTarget to a String.
+    #
+    # This method always returns the target file name.
+    #
+    # @return [String] Target file name.
+    def to_s
+      @target
+    end
+  end
+end

lib/rscons/builder.rb

@@ -1,20 +1,100 @@
+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 a set of default variable values for the Environment to use
+    # Return the name of the builder.
-    # unless the user overrides any.
+    #
+    # If not overridden this defaults to the last component of the class name.
+    #
+    # @return [String] The name of the builder.
+    def name
+      self.class.name.split(":").last
+    end
+
+    # Return a set of default construction variables for the builder.
+    #
     # @param env [Environment] The Environment.
+    #
+    # @return [Hash] Default construction variables.
     def default_variables(env)
       {}
     end
 
+    # Create a BuildTarget object for this build target.
+    #
+    # Builder sub-classes can override this method to manipulate parameters
+    # (for example, add a suffix to the user-given target file name).
+    #
+    # @param options [Hash] Options to create the BuildTarget with.
+    # @option options [Environment] :env
+    #   The Environment.
+    # @option options [String] :target
+    #   The user-supplied target name.
+    # @option options [Array<String>] :sources
+    #   The user-supplied source file name(s).
+    #
+    # @return [BuildTarget]
+    def create_build_target(options)
+      BuildTarget.new(options)
+    end
+
     # Return whether this builder object is capable of producing a given target
     # file name from a given source file name.
+    #
     # @param target [String] The target file name.
-    # @param source [String, Array] The source file name(s).
+    # @param source [String] The source file name.
     # @param env [Environment] The Environment.
+    #
+    # @return [Boolean]
+    #   Whether this builder object is capable of producing a given target
+    #   file name from a given source file name.
     def produces?(target, source, env)
       false
     end
+
+    # Run the builder to produce a build target.
+    #
+    # @param target [String] Target file name.
+    # @param sources [Array<String>] Source file name(s).
+    # @param cache [Cache] The Cache object.
+    # @param env [Environment] The Environment executing the builder.
+    # @param vars [Hash,VarSet] Extra construction variables.
+    #
+    # @return [String,false]
+    #   Name of the target file on success or false on failure.
+    def run(target, sources, cache, env, vars)
+      raise "This method must be overridden in a subclass"
+    end
+
+    # Check if the cache is up to date for the target and if not execute the
+    # build command.
+    #
+    # @param short_cmd_string [String]
+    #   Short description of build action to be printed when env.echo ==
+    #   :short.
+    # @param target [String] Name of the target file.
+    # @param command [Array<String>]
+    #   The command to execute to build the target.
+    # @param sources [Array<String>] Source file name(s).
+    # @param env [Environment] The Environment executing the builder.
+    # @param cache [Cache] The Cache object.
+    #
+    # @return [String,false]
+    #   The name of the target on success or false on failure.
+    def standard_build(short_cmd_string, target, command, sources, env, cache)
+      unless cache.up_to_date?(target, command, sources, env)
+        unless Rscons.phony_target?(target)
+          cache.mkdir_p(File.dirname(target))
+          FileUtils.rm_f(target)
+        end
+        return false unless env.execute(short_cmd_string, command)
+        cache.register_build(target, command, sources, env)
+      end
+      target
+    end
   end
 end

lib/rscons/builders/cfile.rb

@@ -0,0 +1,55 @@
+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
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the 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
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        vars = vars.merge({
+          "_TARGET" => target,
+          "_SOURCES" => sources,
+        })
+        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("${#{cmd}_CMD}", vars)
+        standard_build("#{cmd} #{target}", target, command, sources, env, cache)
+      end
+    end
+  end
+end

lib/rscons/builders/command.rb

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

lib/rscons/builders/directory.rb

@@ -0,0 +1,31 @@
+module Rscons
+  module Builders
+    # The Directory builder creates a directory.
+    class Directory < Builder
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        if File.directory?(target)
+          target
+        elsif File.exists?(target)
+          $stderr.puts "Error: `#{target}' already exists and is not a directory"
+          false
+        else
+          puts "Directory #{target}"
+          cache.mkdir_p(target)
+          target
+        end
+      end
+
+    end
+  end
+end

lib/rscons/builders/disassemble.rb

@@ -0,0 +1,40 @@
+module Rscons
+  module Builders
+    # The Disassemble builder produces a disassembly listing of a source file.
+    class Disassemble < Builder
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
+      def default_variables(env)
+        {
+          "OBJDUMP" => "objdump",
+          "DISASM_CMD" => ["${OBJDUMP}", "${DISASM_FLAGS}", "${_SOURCES}"],
+          "DISASM_FLAGS" => ["--disassemble", "--source"],
+        }
+      end
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        vars = vars.merge("_SOURCES" => sources)
+        command = env.build_command("${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

lib/rscons/builders/install.rb

@@ -0,0 +1,64 @@
+require "pathname"
+
+module Rscons
+  module Builders
+    # The Install builder copies files/directories to new locations.
+    class Install < Builder
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        target_is_dir = (sources.length > 1) ||
+                        Dir.exists?(sources.first) ||
+                        Dir.exists?(target)
+        outdir = target_is_dir ? target : File.dirname(target)
+        # Collect the list of files to copy over.
+        file_map = {}
+        if target_is_dir
+          sources.each do |src|
+            if Dir.exists? src
+              Dir.glob("#{src}/**/*", File::FNM_DOTMATCH).select do |f|
+                File.file?(f)
+              end.each do |subfile|
+                subpath = Pathname.new(subfile).relative_path_from(Pathname.new(src)).to_s
+                file_map[subfile] = "#{outdir}/#{subpath}"
+              end
+            else
+              file_map[src] = "#{outdir}/#{File.basename(src)}"
+            end
+          end
+        else
+          file_map[sources.first] = target
+        end
+        printed_message = false
+        file_map.each do |src, dest|
+          # Check the cache and copy if necessary
+          unless cache.up_to_date?(dest, :Copy, [src], env)
+            unless printed_message
+              puts "#{name} #{target}"
+              printed_message = true
+            end
+            cache.mkdir_p(File.dirname(dest))
+            FileUtils.cp(src, dest, :preserve => true)
+          end
+          cache.register_build(dest, :Copy, [src], env)
+        end
+        target if (target_is_dir ? Dir.exists?(target) : File.exists?(target))
+      end
+
+
+    end
+
+    # The Copy builder is identical to the Install builder.
+    class Copy < Install; end
+
+  end
+end

lib/rscons/builders/library.rb

@@ -1,32 +1,42 @@
-require 'fileutils'
-
 module Rscons
-  # A default RScons builder that produces a static library archive.
+  module Builders
-  class Library < Builder
+    # A default Rscons builder that produces a static library archive.
-    def default_variables(env)
+    class Library < Builder
-      {
+      # Return default construction variables for the builder.
-        'AR' => 'ar',
+      #
-        'LIBSUFFIX' => '.a',
+      # @param env [Environment] The Environment using the builder.
-        'ARFLAGS' => [],
+      #
-        'ARCOM' => ['$AR', 'rcs', '$ARFLAGS', '$TARGET', '$SOURCES']
+      # @return [Hash] Default construction variables for the builder.
-      }
+      def default_variables(env)
-    end
+        {
+          'AR' => 'ar',
+          'LIBSUFFIX' => '.a',
+          'ARFLAGS' => ['rcs'],
+          'ARCMD' => ['${AR}', '${ARFLAGS}', '${_TARGET}', '${_SOURCES}']
+        }
+      end
 
-    def run(target, sources, cache, env, vars = {})
+      # Run the builder to produce a build target.
-      # build sources to linkable objects
+      #
-      objects = env.build_sources(sources, [env['OBJSUFFIX'], env['LIBSUFFIX']].flatten, cache, vars)
+      # @param target [String] Target file name.
-      if objects
+      # @param sources [Array<String>] Source file name(s).
-        vars = vars.merge({
+      # @param cache [Cache] The Cache object.
-          'TARGET' => target,
+      # @param env [Environment] The Environment executing the builder.
-          'SOURCES' => objects,
+      # @param vars [Hash,VarSet] Extra construction variables.
-        })
+      #
-        command = env.build_command(env['ARCOM'], vars)
+      # @return [String,false]
-        unless cache.up_to_date?(target, command, objects)
+      #   Name of the target file on success or false on failure.
-          FileUtils.rm_f(target)
+      def run(target, sources, cache, env, vars)
-          return false unless env.execute("AR #{target}", command)
+        # build sources to linkable objects
-          cache.register_build(target, command, objects)
+        objects = env.build_sources(sources, env.expand_varref(["${OBJSUFFIX}", "${LIBSUFFIX}"], vars).flatten, cache, vars)
+        if objects
+          vars = vars.merge({
+            '_TARGET' => target,
+            '_SOURCES' => objects,
+          })
+          command = env.build_command("${ARCMD}", vars)
+          standard_build("AR #{target}", target, command, objects, env, cache)
         end
-        target
       end
     end
   end

lib/rscons/builders/object.rb

@@ -1,69 +1,114 @@
 module Rscons
-  # A default RScons builder which knows how to produce an object file from
+  module Builders
-  # various types of source files.
+    # A default Rscons builder which knows how to produce an object file from
-  class Object < Builder
+    # various types of source files.
-    def default_variables(env)
+    class Object < Builder
-      {
+      # Mapping of known sources from which to build object files.
-        'OBJSUFFIX' => '.o',
+      KNOWN_SUFFIXES = {
-
+        "AS" => "ASSUFFIX",
-        'AS' => '$CC',
+        "CC" => "CSUFFIX",
-        'ASFLAGS' => [],
+        "CXX" => "CXXSUFFIX",
-        'ASSUFFIX' => '.S',
+        "DC" => "DSUFFIX",
-        'ASPPPATH' => '$CPPPATH',
-        'ASPPFLAGS' => '$CPPFLAGS',
-        'ASDEPGEN' => ['-MMD', '-MF', '$DEPFILE'],
-        'ASCOM' => ['$AS', '-c', '-o', '$TARGET', '$ASDEPGEN', '-I$[ASPPPATH]', '$ASPPFLAGS', '$ASFLAGS', '$SOURCES'],
-
-        'CPPFLAGS' => [],
-        'CPPPATH' => [],
-
-        'CC' => 'gcc',
-        'CFLAGS' => [],
-        'CSUFFIX' => '.c',
-        'CCDEPGEN' => ['-MMD', '-MF', '$DEPFILE'],
-        'CCCOM' => ['$CC', '-c', '-o', '$TARGET', '$CCDEPGEN', '-I$[CPPPATH]', '$CPPFLAGS', '$CFLAGS', '$SOURCES'],
-
-        'CXX' => 'g++',
-        'CXXFLAGS' => [],
-        'CXXSUFFIX' => '.cc',
-        'CXXDEPGEN' => ['-MMD', '-MF', '$DEPFILE'],
-        'CXXCOM' =>['$CXX', '-c', '-o', '$TARGET', '$CXXDEPGEN', '-I$[CPPPATH]', '$CPPFLAGS', '$CXXFLAGS', '$SOURCES'],
       }
-    end
 
-    def produces?(target, source, env)
+      # Return default construction variables for the builder.
-      target.has_suffix?(env['OBJSUFFIX']) and (
+      #
-        source.has_suffix?(env['ASSUFFIX']) or
+      # @param env [Environment] The Environment using the builder.
-        source.has_suffix?(env['CSUFFIX']) or
+      #
-        source.has_suffix?(env['CXXSUFFIX']))
+      # @return [Hash] Default construction variables for the builder.
-    end
+      def default_variables(env)
+        {
+          'OBJSUFFIX' => ['.o'],
+          'DEPFILESUFFIX' => '.mf',
 
-    def run(target, sources, cache, env, vars = {})
+          'CPPDEFPREFIX' => '-D',
-      vars = vars.merge({
+          'INCPREFIX' => '-I',
-        'TARGET' => target,
+
-        'SOURCES' => sources,
+          'AS' => '${CC}',
-        'DEPFILE' => target.set_suffix('.mf'),
+          'ASFLAGS' => [],
-      })
+          'ASSUFFIX' => ['.S'],
-      com_prefix = if sources.first.has_suffix?(env['ASSUFFIX'])
+          'ASPPPATH' => '${CPPPATH}',
-                     'AS'
+          'ASPPFLAGS' => '${CPPFLAGS}',
-                   elsif sources.first.has_suffix?(env['CSUFFIX'])
+          'ASDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
-                     'CC'
+          'ASCMD' => ['${AS}', '-c', '-o', '${_TARGET}', '${ASDEPGEN}', '${INCPREFIX}${ASPPPATH}', '${ASPPFLAGS}', '${ASFLAGS}', '${_SOURCES}'],
-                   elsif sources.first.has_suffix?(env['CXXSUFFIX'])
+
-                     'CXX'
+          'CPPFLAGS' => ['${CPPDEFPREFIX}${CPPDEFINES}'],
-                   else
+          'CPPDEFINES' => [],
-                     raise "Error: unknown input file type: #{sources.first.inspect}"
+          'CPPPATH' => [],
-                   end
+
-      command = env.build_command(env["#{com_prefix}COM"], vars)
+          'CCFLAGS' => [],
-      unless cache.up_to_date?(target, command, sources)
+
-        return false unless env.execute("#{com_prefix} #{target}", command)
+          'CC' => 'gcc',
-        deps = sources
+          'CFLAGS' => [],
-        if File.exists?(vars['DEPFILE'])
+          'CSUFFIX' => ['.c'],
-          deps += env.parse_makefile_deps(vars['DEPFILE'], target)
+          'CCDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
-          FileUtils.rm_f(vars['DEPFILE'])
+          'CCCMD' => ['${CC}', '-c', '-o', '${_TARGET}', '${CCDEPGEN}', '${INCPREFIX}${CPPPATH}', '${CPPFLAGS}', '${CFLAGS}', '${CCFLAGS}', '${_SOURCES}'],
-        end
+
-        cache.register_build(target, command, deps.uniq)
+          'CXX' => 'g++',
+          'CXXFLAGS' => [],
+          'CXXSUFFIX' => ['.cc', '.cpp', '.cxx', '.C'],
+          'CXXDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
+          'CXXCMD' =>['${CXX}', '-c', '-o', '${_TARGET}', '${CXXDEPGEN}', '${INCPREFIX}${CPPPATH}', '${CPPFLAGS}', '${CXXFLAGS}', '${CCFLAGS}', '${_SOURCES}'],
+
+          'DC' => 'gdc',
+          'DFLAGS' => [],
+          'DSUFFIX' => ['.d'],
+          'D_IMPORT_PATH' => [],
+          'DCCMD' => ['${DC}', '-c', '-o', '${_TARGET}', '${INCPREFIX}${D_IMPORT_PATH}', '${DFLAGS}', '${_SOURCES}'],
+        }
+      end
+
+      # Return whether this builder object is capable of producing a given target
+      # file name from a given source file name.
+      #
+      # @param target [String] The target file name.
+      # @param source [String] The source file name.
+      # @param env [Environment] The Environment.
+      #
+      # @return [Boolean]
+      #   Whether this builder object is capable of producing a given target
+      #   file name from a given source file name.
+      def produces?(target, source, env)
+        target.end_with?(*env['OBJSUFFIX']) and KNOWN_SUFFIXES.find do |compiler, suffix_var|
+          source.end_with?(*env[suffix_var])
+        end
+      end
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        vars = vars.merge({
+          '_TARGET' => target,
+          '_SOURCES' => sources,
+          '_DEPFILE' => Rscons.set_suffix(target, env.expand_varref("${DEPFILESUFFIX}", vars)),
+        })
+        com_prefix = KNOWN_SUFFIXES.find do |compiler, suffix_var|
+          sources.first.end_with?(*env.expand_varref("${#{suffix_var}}"))
+        end.tap do |v|
+          v.nil? and raise "Error: unknown input file type: #{sources.first.inspect}"
+        end.first
+        command = env.build_command("${#{com_prefix}CMD}", vars)
+        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)
+          deps = sources
+          if File.exists?(vars['_DEPFILE'])
+            deps += Environment.parse_makefile_deps(vars['_DEPFILE'], target)
+            FileUtils.rm_f(vars['_DEPFILE'])
+          end
+          cache.register_build(target, command, deps.uniq, env)
+        end
+        target
       end
-      target
     end
   end
 end

lib/rscons/builders/preprocess.rb

@@ -0,0 +1,60 @@
+require "fileutils"
+
+module Rscons
+  module Builders
+    # The Preprocess builder invokes the C preprocessor
+    class Preprocess < Builder
+
+      # Return default construction variables for the builder.
+      #
+      # @param env [Environment] The Environment using the builder.
+      #
+      # @return [Hash] Default construction variables for the builder.
+      def default_variables(env)
+        {
+          "CPP_CMD" => %w[
+            ${_PREPROCESS_CC} -E ${_PREPROCESS_DEPGEN}
+            -o ${_TARGET} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${_SOURCES}],
+        }
+      end
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        if sources.find {|s| s.end_with?(*env.expand_varref("${CXXSUFFIX}", vars))}
+          pp_cc = "${CXX}"
+          depgen = "${CXXDEPGEN}"
+        else
+          pp_cc = "${CC}"
+          depgen = "${CCDEPGEN}"
+        end
+        vars = vars.merge("_PREPROCESS_CC" => pp_cc,
+                          "_PREPROCESS_DEPGEN" => depgen,
+                          "_TARGET" => target,
+                          "_SOURCES" => sources,
+                          "_DEPFILE" => Rscons.set_suffix(target, env.expand_varref("${DEPFILESUFFIX}", vars)))
+        command = env.build_command("${CPP_CMD}", vars)
+        unless cache.up_to_date?(target, command, sources, env)
+          cache.mkdir_p(File.dirname(target))
+          return false unless env.execute("Preprocess #{target}", command)
+          deps = sources
+          if File.exists?(vars["_DEPFILE"])
+            deps += Environment.parse_makefile_deps(vars["_DEPFILE"], nil)
+            FileUtils.rm_f(vars["_DEPFILE"])
+          end
+          cache.register_build(target, command, deps.uniq, env)
+        end
+        target
+      end
+
+    end
+  end
+end

lib/rscons/builders/program.rb

@@ -1,38 +1,81 @@
 module Rscons
-  # A default RScons builder that knows how to link object files into an
+  module Builders
-  # executable program.
+    # A default Rscons builder that knows how to link object files into an
-  class Program < Builder
+    # executable program.
-    def default_variables(env)
+    class Program < Builder
-      {
+      # Return default construction variables for the builder.
-        'LD' => nil,
+      #
-        'OBJSUFFIX' => '.o',
+      # @param env [Environment] The Environment using the builder.
-        'LIBSUFFIX' => '.a',
+      #
-        'LDFLAGS' => [],
+      # @return [Hash] Default construction variables for the builder.
-        'LIBPATH' => [],
+      def default_variables(env)
-        'LIBS' => [],
+        {
-        'LDCOM' => ['$LD', '-o', '$TARGET', '$LDFLAGS', '$SOURCES', '-L$[LIBPATH]', '-l$[LIBS]']
+          'OBJSUFFIX' => '.o',
-      }
+          'PROGSUFFIX' => (Object.const_get("RUBY_PLATFORM") =~ /mingw|cygwin/ ? ".exe" : ""),
-    end
+          'LD' => nil,
+          'LIBSUFFIX' => '.a',
+          'LDFLAGS' => [],
+          'LIBPATH' => [],
+          'LIBDIRPREFIX' => '-L',
+          'LIBLINKPREFIX' => '-l',
+          'LIBS' => [],
+          'LDCMD' => ['${LD}', '-o', '${_TARGET}', '${LDFLAGS}', '${_SOURCES}', '${LIBDIRPREFIX}${LIBPATH}', '${LIBLINKPREFIX}${LIBS}']
+        }
+      end
 
-    def run(target, sources, cache, env, vars = {})
+      # Create a BuildTarget object for this build target.
-      # build sources to linkable objects
+      #
-      objects = env.build_sources(sources, [env['OBJSUFFIX'], env['LIBSUFFIX']].flatten, cache, vars)
+      # The build target filename is given a ".exe" suffix if Rscons is
-      if objects
+      # executing on a Windows platform and no other suffix is given.
-        use_cxx = sources.map do |s|
+      #
-          s.has_suffix?(env['CXXSUFFIX'])
+      # @param options [Hash] Options to create the BuildTarget with.
-        end.any?
+      # @option options [Environment] :env
-        ld_alt = use_cxx ? env['CXX'] : env['CC']
+      #   The Environment.
-        vars = vars.merge({
+      # @option options [String] :target
-          'TARGET' => target,
+      #   The user-supplied target name.
-          'SOURCES' => objects,
+      # @option options [Array<String>] :sources
-          'LD' => env['LD'] || ld_alt,
+      #   The user-supplied source file name(s).
-        })
+      #
-        command = env.build_command(env['LDCOM'], vars)
+      # @return [BuildTarget]
-        unless cache.up_to_date?(target, command, objects)
+      def create_build_target(options)
-          return false unless env.execute("LD #{target}", command)
+        my_options = options.dup
-          cache.register_build(target, command, objects)
+        unless my_options[:target] =~ /\./
+          my_options[:target] += options[:env].expand_varref("${PROGSUFFIX}")
         end
-        target
+        super(my_options)
+      end
+
+      # Run the builder to produce a build target.
+      #
+      # @param target [String] Target file name.
+      # @param sources [Array<String>] Source file name(s).
+      # @param cache [Cache] The Cache object.
+      # @param env [Environment] The Environment executing the builder.
+      # @param vars [Hash,VarSet] Extra construction variables.
+      #
+      # @return [String,false]
+      #   Name of the target file on success or false on failure.
+      def run(target, sources, cache, env, vars)
+        # build sources to linkable objects
+        objects = env.build_sources(sources, env.expand_varref(["${OBJSUFFIX}", "${LIBSUFFIX}"], vars).flatten, cache, vars)
+        return false unless objects
+        ld = env.expand_varref("${LD}", vars)
+        ld = if ld != ""
+               ld
+             elsif sources.find {|s| s.end_with?(*env.expand_varref("${DSUFFIX}", vars))}
+               "${DC}"
+             elsif sources.find {|s| s.end_with?(*env.expand_varref("${CXXSUFFIX}", vars))}
+               "${CXX}"
+             else
+               "${CC}"
+             end
+        vars = vars.merge({
+          '_TARGET' => target,
+          '_SOURCES' => objects,
+          'LD' => ld,
+        })
+        command = env.build_command("${LDCMD}", vars)
+        standard_build("LD #{target}", target, command, objects, env, cache)
       end
     end
   end

lib/rscons/builders/simple_builder.rb

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

lib/rscons/cache.rb

@@ -1,83 +1,118 @@
-require 'yaml'
+require "digest/md5"
-require 'fileutils'
+require "fileutils"
-require 'digest/md5'
+require "json"
-require 'set'
+require "set"
-require 'rscons/version'
+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',
+  #     "version" => "1.2.3",
-  #     targets: {
+  #     "targets" => {
-  #       'program' => {
+  #       "program" => {
-  #         'checksum' => 'A1B2C3D4',
+  #         "checksum" => "A1B2C3D4",
-  #         'command' => ['gcc', '-o', 'program', 'program.o'],
+  #         "command" => "13543518FE",
-  #         'deps' => [
+  #         "deps" => [
   #           {
-  #             'fname' => 'program.o',
+  #             "fname" => "program.o",
-  #             'checksum' => '87654321',
+  #             "checksum" => "87654321",
-  #           }
+  #           },
   #         ],
-  #       }
+  #         "user_deps" => [
-  #       'program.o' => {
-  #         'checksum' => '87654321',
-  #         'command' => ['gcc', '-c', '-o', 'program.o', 'program.c'],
-  #         'deps' => [
   #           {
-  #             'fname' => 'program.c',
+  #             "fname" => "lscript.ld",
-  #             'checksum' => '456789ABC',
+  #             "checksum" => "77551133",
+  #           },
+  #         ],
+  #       },
+  #       "program.o" => {
+  #         "checksum" => "87654321",
+  #         "command" => "98765ABCD",
+  #         "deps" => [
+  #           {
+  #             "fname" => "program.c",
+  #             "checksum" => "456789ABC",
   #           },
   #           {
-  #             'fname' => 'program.h',
+  #             "fname" => "program.h",
-  #             'checksum' => '7979764643',
+  #             "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'
+    CACHE_FILE = ".rsconscache"
 
-    #### Class Methods
+    # Prefix for phony cache entries.
-
+    PHONY_PREFIX = ":PHONY:"
-    # Remove the cache file
-    def self.clear
-      FileUtils.rm_f(CACHE_FILE)
-    end
-
-    #### Instance Methods
 
     # Create a Cache object and load in the previous contents from the cache
     # file.
     def initialize
-      @cache = YAML.load(File.read(CACHE_FILE)) rescue {
+      initialize!
-        targets: {},
+    end
-        version: VERSION,
+
-      }
+    # Remove the cache file.
+    #
+    # @return [void]
+    def clear
+      FileUtils.rm_f(CACHE_FILE)
+      initialize!
+    end
+
+    # Clear the cached file checksums.
+    #
+    # @return [void]
+    def clear_checksum_cache!
       @lookup_checksums = {}
     end
 
     # Write the cache to disk to be loaded next time.
+    #
+    # @return [void]
     def write
-      File.open(CACHE_FILE, 'w') do |fh|
+      if @dirty || (@cache["version"] != VERSION)
-        fh.puts(YAML.dump(@cache))
+        @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
+    # Check if target(s) are up to date.
-    # @param target [String] The name of the target file.
+    #
-    # @param command [Array] The command used to build the target.
+    # @param targets [Symbol, String, Array<String>]
-    # @param deps [Array] List of the target's dependency files.
+    #   The name(s) of the target file(s).
-    # @param options [Hash] Optional options. Can contain the following keys:
+    # @param command [String, Array, Hash]
-    #   :strict_deps::
+    #   The command used to build the target. The command parameter can
-    #     Only consider a target up to date if its list of dependencies is
+    #   actually be a String, Array, or Hash and could contain information
-    #     exactly equal (including order) to the cached list of dependencies
+    #   other than just the actual command used to build the target. For the
-    # @return true value if the target is up to date, meaning that:
+    #   purposes of the Cache, any difference in the command argument will
+    #   trigger a rebuild.
+    # @param deps [Array<String>] List of the target's dependency files.
+    # @param env [Environment] The Rscons::Environment.
+    # @param options [Hash] Optional options.
+    # @option options [Boolean] :strict_deps
+    #   Only consider a target up to date if its list of dependencies is
+    #   exactly equal (including order) to the cached list of dependencies
+    #
+    # @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
@@ -87,65 +122,170 @@ 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 = {})
-      # target file must exist on disk
+      Array(targets).each do |target|
-      return false unless File.exists?(target)
+        cache_key = get_cache_key(target)
 
-      # target must be registered in the cache
+        unless Rscons.phony_target?(target)
-      return false unless @cache[:targets].has_key?(target)
+          # target file must exist on disk
+          return false unless File.exists?(target)
+        end
 
-      # target must have the same checksum as when it was built last
+        # target must be registered in the cache
-      return false unless @cache[:targets][target][:checksum] == lookup_checksum(target)
+        return false unless @cache["targets"].has_key?(cache_key)
 
-      # command used to build target must be identical
+        unless Rscons.phony_target?(target)
-      return false unless @cache[:targets][target][:command] == command
+          # target must have the same checksum as when it was built last
+          return false unless @cache["targets"][cache_key]["checksum"] == lookup_checksum(target)
+        end
 
-      cached_deps = @cache[:targets][target][:deps].map { |dc| dc[:fname] }
+        # command used to build target must be identical
-      if options[:strict_deps]
+        return false unless @cache["targets"][cache_key]["command"] == Digest::MD5.hexdigest(command.inspect)
-        # depedencies passed in must exactly equal those in the cache
+
-        return false unless deps == cached_deps
+        cached_deps = @cache["targets"][cache_key]["deps"] || []
-      else
+        cached_deps_fnames = cached_deps.map { |dc| dc["fname"] }
-        # all dependencies passed in must exist in cache (but cache may have more)
+        if options[:strict_deps]
-        return false unless (Set.new(deps) - Set.new(cached_deps)).empty?
+          # depedencies passed in must exactly equal those in the cache
+          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_fnames)).empty?
+        end
+
+        # set of user dependencies must match
+        user_deps = env.get_user_deps(target) || []
+        cached_user_deps = @cache["targets"][cache_key]["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
+        (cached_deps + cached_user_deps).each do |dep_cache|
+          return false unless dep_cache["checksum"] == lookup_checksum(dep_cache["fname"])
+        end
       end
 
-      # all cached dependencies must have their checksums match
+      true
-      @cache[:targets][target][:deps].map do |dep_cache|
-        dep_cache[:checksum] == lookup_checksum(dep_cache[:fname])
-      end.all?
     end
 
-    # Store cache information about a target built by a builder
+    # Store cache information about target(s) built by a builder.
-    # @param target [String] The name of the target.
+    #
-    # @param command [Array] The command used to build the target.
+    # @param targets [Symbol, String, Array<String>]
-    # @param deps [Array] List of dependencies for the target.
+    #   The name of the target(s) built.
-    def register_build(target, command, deps)
+    # @param command [String, Array, Hash]
-      @cache[:targets][target] = {
+    #   The command used to build the target. The command parameter can
-        command: command,
+    #   actually be a String, Array, or Hash and could contain information
-        checksum: calculate_checksum(target),
+    #   other than just the actual command used to build the target. For the
-        deps: deps.map do |dep|
+    #   purposes of the Cache, any difference in the command argument will
-          {
+    #   trigger a rebuild.
-            fname: dep,
+    # @param deps [Array<String>] List of dependencies for the target.
-            checksum: lookup_checksum(dep),
+    # @param env [Environment] The {Rscons::Environment}.
-          }
+    #
+    # @return [void]
+    def register_build(targets, command, deps, env)
+      Array(targets).each do |target|
+        target_checksum = Rscons.phony_target?(target) ? "" : calculate_checksum(target)
+        @cache["targets"][get_cache_key(target)] = {
+          "command" => Digest::MD5.hexdigest(command.inspect),
+          "checksum" => target_checksum,
+          "deps" => deps.map do |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.
+    #
+    # @return [Array<String>] List of targets that have been built.
+    def targets
+      @cache["targets"].keys
+    end
+
+    # Make any needed directories and record the ones that are created for
+    # removal upon a "clean" operation.
+    #
+    # @param path [String] Directory to create.
+    #
+    # @return [void]
+    def mkdir_p(path)
+      parts = path.split(/[\\\/]/)
+      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
+          @dirty = true
         end
-      }
+      end
+    end
+
+    # Return a list of directories which were created as a part of the build.
+    #
+    # @return [Array<String>]
+    #   List of directories which were created as a part of the build.
+    def directories
+      @cache["directories"].keys
     end
 
-    # Private Instance Methods
     private
 
+    # Return a String key based on the target name to use in the on-disk cache.
+    #
+    # @param target_name [Symbol, String]
+    #   Target name.
+    #
+    # @return [String]
+    #   Key name.
+    def get_cache_key(target_name)
+      if Rscons.phony_target?(target_name)
+        PHONY_PREFIX + target_name.to_s
+      else
+        target_name
+      end
+    end
+
+    # 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
+    # the same file.
+    #
     # @param file [String] The file name.
+    #
+    # @return [String] The file's checksum.
     def lookup_checksum(file)
       @lookup_checksums[file] || calculate_checksum(file)
     end
 
-    # Calculate and return a file's checksum
+    # Calculate and return a file's checksum.
+    #
     # @param file [String] The file name.
+    #
+    # @return [String] The file's checksum.
     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

lib/rscons/cli.rb

@@ -0,0 +1,78 @@
+require "rscons"
+require "optparse"
+
+module Rscons
+  # Command-Line Interface functionality.
+  module Cli
+
+    # Default files to look for to execute if none specified.
+    DEFAULT_RSCONSFILES = %w[Rsconsfile Rsconsfile.rb]
+
+    class << self
+
+      # Run the Rscons CLI.
+      #
+      # @param argv [Array]
+      #   Command-line parameters.
+      #
+      # @return [void]
+      def run(argv)
+        argv = argv.dup
+        rsconsfile = nil
+
+        OptionParser.new do |opts|
+          opts.banner = "Usage: #{$0} [options]"
+
+          opts.separator ""
+          opts.separator "Options:"
+
+          opts.on("-c", "--clean", "Perform clean operation") do
+            Rscons.clean
+            exit 0
+          end
+
+          opts.on("-f FILE", "Execute FILE (default Rsconsfile)") do |f|
+            rsconsfile = f
+          end
+
+          opts.on_tail("--version", "Show version") do
+            puts "Rscons version #{Rscons::VERSION}"
+            exit 0
+          end
+
+          opts.on_tail("-h", "--help", "Show this help.") do
+            puts opts
+            exit 0
+          end
+
+        end.parse!(argv)
+
+        if rsconsfile
+          unless File.exists?(rsconsfile)
+            $stderr.puts "Cannot read #{rsconsfile}"
+            exit 1
+          end
+        else
+          rsconsfile = DEFAULT_RSCONSFILES.find do |f|
+            File.exists?(f)
+          end
+          unless rsconsfile
+            $stderr.puts "Could not find the Rsconsfile to execute."
+            $stderr.puts "Looked in: [#{DEFAULT_RSCONSFILES.join(", ")}]"
+            exit 1
+          end
+        end
+
+        begin
+          load rsconsfile
+        rescue Rscons::BuildError => e
+          $stderr.puts e.message
+          exit 1
+        end
+
+        exit 0
+      end
+
+    end
+  end
+end

lib/rscons/environment.rb

@@ -1,39 +1,57 @@
-require 'set'
+require "fileutils"
-require 'fileutils'
+require "set"
+require "shellwords"
 
 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
-    # [Array] of {Builder} objects.
+    # @return [Hash] Set of !{"builder_name" => builder_object} pairs.
     attr_reader :builders
 
+    # @return [Symbol] :command, :short, or :off
+    attr_accessor :echo
+
+    # @return [String, nil] The build root.
+    attr_reader :build_root
+
+    # Set the build root.
+    #
+    # @param build_root [String] The 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 both construction variables, which are
+    # @param options [Hash]
-    #   uppercase strings (such as "CC" or "LDFLAGS"), and RScons options,
+    # @option options [Symbol] :echo
-    #   which are lowercase symbols (such as :echo).
+    #   :command, :short, or :off (default :short)
+    # @option options [String] :build_root
+    #   Build root directory (default nil)
+    # @option options [Boolean] :exclude_builders
+    #   Whether 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 = {})
+    def initialize(options = {})
-      @varset = VarSet.new(variables)
+      @varset = VarSet.new
       @targets = {}
+      @user_deps = {}
       @builders = {}
       @build_dirs = []
-      @varset[:exclude_builders] ||= []
+      @build_hooks = {pre: [], post: []}
-      unless @varset[:exclude_builders] == :all
+      unless options[:exclude_builders]
-        exclude_builders = Set.new(@varset[:exclude_builders] || [])
+        DEFAULT_BUILDERS.each do |builder_class_name|
-        DEFAULT_BUILDERS.each do |builder_class|
+          builder_class = Builders.const_get(builder_class_name)
-          unless exclude_builders.include?(builder_class.short_name)
+          builder_class or raise "Could not find builder class #{builder_class_name}"
-            add_builder(builder_class.new)
+          add_builder(builder_class.new)
-          end
         end
       end
-      (@varset[:builders] || []).each do |builder|
+      @echo = options[:echo] || :short
-        add_builder(builder)
+      @build_root = options[:build_root]
-      end
-      @varset[:echo] ||= :command
 
       if block_given?
         yield self
@@ -42,18 +60,56 @@ module Rscons
     end
 
     # Make a copy of the Environment object.
-    # The cloned environment will contain a copy of all environment options,
+    #
-    # construction variables, builders, and build directories. It will not
+    # By default, a cloned environment will contain a copy of all environment
-    # contain a copy of the targets.
+    # 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.
-    def clone(variables = {})
+    #
-      env = Environment.new()
+    # Any options that #initialize receives can also be specified here.
-      @builders.each do |builder_name, builder|
+    #
-        env.add_builder(builder)
+    # @return [Environment] The newly created {Environment} object.
+    def clone(options = {})
+      clone = options[:clone] || Set[:variables, :builders]
+      clone = Set[:variables, :builders, :build_root, :build_dirs, :build_hooks] if clone == :all
+      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
+      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[:pre].each do |build_hook_block|
+          env.add_build_hook(&build_hook_block)
+        end
+        @build_hooks[:post].each do |build_hook_block|
+          env.add_post_build_hook(&build_hook_block)
+        end
       end
-      env.append(@varset)
-      env.append(variables)
 
       if block_given?
         yield env
@@ -63,8 +119,34 @@ module Rscons
     end
 
     # Add a {Builder} object to the Environment.
-    def add_builder(builder)
+    #
-      @builders[builder.class.short_name] = builder
+    # @overload add_builder(builder)
+    #
+    #   Add the given builder to the Environment.
+    #
+    #   @param builder [Builder] An instance of the builder to register.
+    #
+    # @overload add_builder(builder,&action)
+    #
+    #   Create a new {Builders::SimpleBuilder} instance and add it to the
+    #   environment.
+    #
+    #   @since 1.8.0
+    #
+    #   @param builder [String,Symbol]
+    #     The name of the builder to add.
+    #
+    #   @param action [Block]
+    #     A block that will be called when the builder is executed to generate
+    #     a target file. The provided block should have the same prototype as
+    #     {Rscons::Builder#run}.
+    #
+    # @return [void]
+    def add_builder(builder, &action)
+      if not builder.is_a? Rscons::Builder
+        builder = Rscons::Builders::SimpleBuilder.new(builder, &action)
+      end
+      @builders[builder.name] = builder
       var_defs = builder.default_variables(self)
       if var_defs
         var_defs.each_pair do |var, val|
@@ -73,147 +155,559 @@ module Rscons
       end
     end
 
+    # Add a build hook to the Environment.
+    #
+    # Build hooks are Ruby blocks which are invoked immediately before a
+    # build operation takes place. Build hooks have an opportunity to modify
+    # the construction variables in use for the build operation based on the
+    # builder in use, target file name, or sources. Build hooks can also
+    # register new build targets.
+    #
+    # @yield [build_op]
+    #   Invoke the given block with the current build operation.
+    # @yieldparam build_op [Hash]
+    #   Hash with keys:
+    #   - :builder - The builder object in use.
+    #   - :target - Target file name.
+    #   - :sources - List of source file(s).
+    #   - :vars - Set of construction variable values in use.
+    #   - :env - The Environment invoking the builder.
+    #
+    # @return [void]
+    def add_build_hook(&block)
+      @build_hooks[:pre] << block
+    end
+
+    # Add a post build hook to the Environment.
+    #
+    # Post-build hooks are Ruby blocks which are invoked immediately after a
+    # build operation takes place. Post-build hooks are only invoked if the
+    # build operation succeeded. Post-build hooks can register new build
+    # targets.
+    #
+    # @since 1.7.0
+    #
+    # @yield [build_op]
+    #   Invoke the given block with the current build operation.
+    # @yieldparam build_op [Hash]
+    #   Hash with keys:
+    #   - :builder - The builder object in use.
+    #   - :target - Target file name.
+    #   - :sources - List of source file(s).
+    #   - :vars - Set of construction variable values in use.
+    #   - :env - The Environment invoking the builder.
+    #
+    # @return [void]
+    def add_post_build_hook(&block)
+      @build_hooks[:post] << block
+    end
+
     # Specify a build directory for this Environment.
+    #
     # Source files from src_dir will produce object files under obj_dir.
+    #
+    # @param src_dir [String, Regexp]
+    #   Path to the source directory. If a Regexp is given, it will be matched
+    #   to source file names.
+    # @param obj_dir [String]
+    #   Path to the object directory. If a Regexp is given as src_dir, then
+    #   obj_dir can contain backreferences to groups matched from the source
+    #   file name.
+    #
+    # @return [void]
     def build_dir(src_dir, obj_dir)
-      src_dir = src_dir.gsub('\\', '/') if src_dir.is_a?(String)
+      if src_dir.is_a?(String)
-      obj_dir = obj_dir.gsub('\\', '/')
+        src_dir = src_dir.gsub("\\", "/").sub(%r{/*$}, "")
+      end
       @build_dirs << [src_dir, obj_dir]
     end
 
-    # Return the file name to be built from source_fname with suffix suffix.
+    # Return the file name to be built from +source_fname+ with suffix
+    # +suffix+.
+    #
     # This method takes into account the Environment's build directories.
-    # It also creates any parent directories needed to be able to open and
+    #
-    # write to the output file.
+    # @param source_fname [String] Source file name.
+    # @param suffix [String] Suffix, including "." if desired.
+    #
+    # @return [String]
+    #   The file name to be built from +source_fname+ with suffix +suffix+.
     def get_build_fname(source_fname, suffix)
-      build_fname = source_fname.set_suffix(suffix).gsub('\\', '/')
+      build_fname = Rscons.set_suffix(source_fname, suffix).gsub('\\', '/')
-      @build_dirs.each do |src_dir, obj_dir|
+      found_match = @build_dirs.find do |src_dir, obj_dir|
         if src_dir.is_a?(Regexp)
           build_fname.sub!(src_dir, obj_dir)
         else
-          build_fname.sub!(/^#{src_dir}\//, "#{obj_dir}/")
+          build_fname.sub!(%r{^#{src_dir}/}, "#{obj_dir}/")
         end
-        build_fname.gsub!('\\', '/')
       end
-      FileUtils.mkdir_p(File.dirname(build_fname))
+      if @build_root and not found_match
+        unless Rscons.absolute_path?(source_fname) or build_fname.start_with?("#{@build_root}/")
+          build_fname = "#{@build_root}/#{build_fname}"
+        end
+      end
+      build_fname.gsub!('\\', '/')
       build_fname
     end
 
-    # Access a construction variable or environment option.
+    # Get a construction variable's value.
+    #
     # @see VarSet#[]
     def [](*args)
       @varset.send(:[], *args)
     end
 
-    # Set a construction variable or environment option.
+    # Set a construction variable's value.
+    #
     # @see VarSet#[]=
     def []=(*args)
       @varset.send(:[]=, *args)
     end
 
-    # Add a set of construction variables or environment options.
+    # Add a set of construction variables to the Environment.
-    # @see VarSet#append
+    #
-    def append(*args)
+    # @param values [VarSet, Hash] New set of variables.
-      @varset.send(:append, *args)
+    #
+    # @return [void]
+    def append(values)
+      @varset.append(values)
     end
 
-    # Return a list of target file names
+    # Build all build targets specified in the Environment.
-    def targets
+    #
-      @targets.keys
-    end
-
-    # Return a list of sources needed to build target target.
-    def target_sources(target)
-      @targets[target][:source] rescue nil
-    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.
+    #
+    # @return [void]
     def process
-      cache = Cache.new
+      while @targets.size > 0
-      targets_processed = Set.new
+        expand_paths!
-      process_target = proc do |target|
+        targets = @targets
-        if @targets[target][:source].map do |src|
+        @targets = {}
-          targets_processed.include?(src) or not @targets.include?(src) or process_target.call(src)
+        cache = Cache.instance
-        end.all?
+        cache.clear_checksum_cache!
-          @targets[target][:builder].run(target,
+        targets_processed = Set.new
-                                         @targets[target][:source],
+        process_target = proc do |target|
-                                         cache,
+          unless targets_processed.include?(target)
-                                         self,
+            targets_processed << target
-                                         @targets[target][:vars] || {})
+            targets[target].each do |target_params|
-        else
+              target_params[:sources].each do |src|
-          false
+                if targets.include?(src) and not targets_processed.include?(src)
+                  process_target.call(src)
+                end
+              end
+              result = run_builder(target_params[:builder],
+                                   target,
+                                   target_params[:sources],
+                                   cache,
+                                   target_params[:vars] || {})
+              unless result
+                raise BuildError.new("Failed to build #{target}")
+              end
+            end
+          end
         end
-      end
+        begin
-      @targets.each do |target, info|
+          targets.each_key do |target|
-        next if targets_processed.include?(target)
+            process_target.call(target)
-        unless process_target.call(target)
+          end
+        ensure
           cache.write
-          raise BuildError.new("Failed to build #{target}")
         end
       end
-      cache.write
     end
 
-    # Build a command line from the given template, resolving references to
+    # Clear all targets registered for the Environment.
-    # variables using the Environment's construction variables and any extra
+    #
-    # variables specified.
+    # @return [void]
-    # @param command_template [Array] template for the command with variable
+    def clear_targets
-    #   references
+      @targets = {}
-    # @param extra_vars [Hash, VarSet] extra variables to use in addition to
-    #   (or replace) the Environment's construction variables when building
-    #   the command
-    def build_command(command_template, extra_vars)
-      @varset.merge(extra_vars).expand_varref(command_template)
     end
 
-    # Execute a builder command
+    # Expand a construction variable reference.
-    # @param short_desc [String] Message to print if the Environment's :echo
+    #
+    # @param varref [Array, String] Variable reference to expand.
+    # @param extra_vars [Hash, VarSet]
+    #   Extra variables to use in addition to (or replace) the Environment's
+    #   construction variables when expanding the variable reference.
+    #
+    # @return [Array, String] Expansion of the variable reference.
+    def expand_varref(varref, extra_vars = nil)
+      vars = if extra_vars.nil?
+               @varset
+             else
+               @varset.merge(extra_vars)
+             end
+      lambda_args = [env: self, vars: vars]
+      vars.expand_varref(varref, lambda_args)
+    end
+    alias_method :build_command, :expand_varref
+
+    # Execute a builder command.
+    #
+    # @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.
+    #
+    # @return [true,false,nil] Return value from 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|
+      env_args = options[:env] ? [options[:env]] : []
-        unless result or @varset[:echo] == :command
+      options_args = options[:options] ? [options[:options]] : []
+      system(*env_args, *Rscons.command_executer, *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
+    # Define a build target.
+    #
+    # @param method [Symbol] Method name.
+    # @param args [Array] Method arguments.
+    #
+    # @return [BuildTarget]
+    #   The {BuildTarget} object registered, if the method called is a
+    #   {Builder}.
     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)
+        sources = Array(sources)
-        @targets[target] = {
+        builder = @builders[method.to_s]
-          builder: @builders[method.to_s],
+        build_target = builder.create_build_target(env: self, target: target, sources: sources)
-          source: source,
+        add_target(build_target.to_s, builder, sources, vars, rest)
-          vars: vars,
+        build_target
-          args: rest,
-        }
       else
-        orig_method_missing(method, *args)
+        super
+      end
+    end
+
+    # Add a build target.
+    #
+    # @param target [String] Build target file name.
+    # @param builder [Builder] The {Builder} to use to build the target.
+    # @param sources [Array<String>] Source file name(s).
+    # @param vars [Hash] Construction variable overrides.
+    # @param args [Object] Any extra arguments passed to the {Builder}.
+    #
+    # @return [void]
+    def add_target(target, builder, sources, vars, args)
+      @targets[target] ||= []
+      @targets[target] << {
+        builder: builder,
+        sources: sources,
+        vars: vars,
+        args: args,
+      }
+    end
+
+    # Manually record a given target as depending on the specified files.
+    #
+    # @param target [String,BuildTarget] Target file.
+    # @param user_deps [Array<String>] Dependency files.
+    #
+    # @return [void]
+    def depends(target, *user_deps)
+      target = expand_varref(target.to_s)
+      user_deps = user_deps.map {|ud| expand_varref(ud)}
+      @user_deps[target] ||= []
+      @user_deps[target] = (@user_deps[target] + user_deps).uniq
+    end
+
+    # Return the list of user dependencies for a given target.
+    #
+    # @param target [String] Target file name.
+    #
+    # @return [Array<String>,nil]
+    #   List of user-specified dependencies for the target, or nil if none were
+    #   specified.
+    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.
+    #
+    # @param sources [Array<String>] List of source files to build.
+    # @param suffixes [Array<String>]
+    #   List of suffixes to try to convert source files into.
+    # @param cache [Cache] The Cache.
+    # @param vars [Hash] Extra variables to pass to the builder.
+    #
+    # @return [Array<String>] List of the converted file name(s).
+    def build_sources(sources, suffixes, cache, vars)
+      sources.map do |source|
+        if source.end_with?(*suffixes)
+          source
+        else
+          converted = nil
+          suffixes.each do |suffix|
+            converted_fname = get_build_fname(source, suffix)
+            builder = @builders.values.find { |b| b.produces?(converted_fname, source, self) }
+            if builder
+              converted = run_builder(builder, converted_fname, [source], cache, vars)
+              return nil unless converted
+              break
+            end
+          end
+          converted or raise "Could not find a builder to handle #{source.inspect}."
+        end
+      end
+    end
+
+    # Invoke a builder to build the given target based on the given sources.
+    #
+    # @param builder [Builder] The Builder to use.
+    # @param target [String] The target output file.
+    # @param sources [Array<String>] List of source files.
+    # @param cache [Cache] The Cache.
+    # @param vars [Hash] Extra variables to pass to the builder.
+    #
+    # @return [String,false] Return value from the {Builder}'s +run+ method.
+    def run_builder(builder, target, sources, cache, vars)
+      vars = @varset.merge(vars)
+      call_build_hooks = lambda do |sec|
+        @build_hooks[sec].each do |build_hook_block|
+          build_operation = {
+            builder: builder,
+            target: target,
+            sources: sources,
+            vars: vars,
+            env: self,
+          }
+          build_hook_block.call(build_operation)
+        end
+      end
+      call_build_hooks[:pre]
+      rv = builder.run(target, sources, cache, self, vars)
+      call_build_hooks[:post] if rv
+      rv
+    end
+
+    # Expand a path to be relative to the Environment's build root.
+    #
+    # Paths beginning with "^/" are expanded by replacing "^" with the
+    # Environment's build root.
+    #
+    # @param path [String] The path to expand.
+    #
+    # @return [String] The expanded path.
+    def expand_path(path)
+      if Rscons.phony_target?(path)
+        path
+      else
+        path.sub(%r{^\^(?=[\\/])}, @build_root)
+      end
+    end
+
+    # Execute a command using the system shell.
+    #
+    # The shell is automatically determined but can be overridden by the SHELL
+    # construction variable. If the SHELL construction variable is specified,
+    # the flag to pass to the shell is automatically dtermined but can be
+    # overridden by the SHELLFLAG construction variable.
+    #
+    # @param command [String] Command to execute.
+    #
+    # @return [String] The command's standard output.
+    def shell(command)
+      shell_cmd =
+        if self["SHELL"]
+          flag = self["SHELLFLAG"] || (self["SHELL"] == "cmd" ? "/c" : "-c")
+          [self["SHELL"], flag]
+        else
+          Rscons.get_system_shell
+        end
+      IO.popen([*shell_cmd, command]) do |io|
+        io.read
+      end
+    end
+
+    # @!method parse_flags(flags)
+    # @!method parse_flags!(flags)
+    #
+    # Parse command-line flags for compilation/linking options into separate
+    # construction variables.
+    #
+    # For {#parse_flags}, the parsed construction variables are returned in a
+    # Hash instead of merging them directly to the Environment. They can be
+    # merged with {#merge_flags}. The {#parse_flags!} version immediately
+    # merges the parsed flags as well.
+    #
+    # Example:
+    #   # Import FreeType build options
+    #   env.parse_flags!("!freetype-config --cflags --libs")
+    #
+    # @param flags [String]
+    #   String containing the flags to parse, or if the flags string begins
+    #   with "!", a shell command to execute using {#shell} to obtain the
+    #   flags to parse.
+    #
+    # @return [Hash] Set of construction variables to append.
+    def parse_flags(flags)
+      if flags =~ /^!(.*)$/
+        flags = shell($1)
+      end
+      rv = {}
+      words = Shellwords.split(flags)
+      skip = false
+      words.each_with_index do |word, i|
+        if skip
+          skip = false
+          next
+        end
+        append = lambda do |var, val|
+          rv[var] ||= []
+          rv[var] += val
+        end
+        handle = lambda do |var, val|
+          if val.nil? or val.empty?
+            val = words[i + 1]
+            skip = true
+          end
+          if val and not val.empty?
+            append[var, [val]]
+          end
+        end
+        if word == "-arch"
+          if val = words[i + 1]
+            append["CCFLAGS", ["-arch", val]]
+            append["LDFLAGS", ["-arch", val]]
+          end
+          skip = true
+        elsif word =~ /^#{self["CPPDEFPREFIX"]}(.*)$/
+          handle["CPPDEFINES", $1]
+        elsif word == "-include"
+          if val = words[i + 1]
+            append["CCFLAGS", ["-include", val]]
+          end
+          skip = true
+        elsif word == "-isysroot"
+          if val = words[i + 1]
+            append["CCFLAGS", ["-isysroot", val]]
+            append["LDFLAGS", ["-isysroot", val]]
+          end
+          skip = true
+        elsif word =~ /^#{self["INCPREFIX"]}(.*)$/
+          handle["CPPPATH", $1]
+        elsif word =~ /^#{self["LIBLINKPREFIX"]}(.*)$/
+          handle["LIBS", $1]
+        elsif word =~ /^#{self["LIBDIRPREFIX"]}(.*)$/
+          handle["LIBPATH", $1]
+        elsif word == "-mno-cygwin"
+          append["CCFLAGS", [word]]
+          append["LDFLAGS", [word]]
+        elsif word == "-mwindows"
+          append["LDFLAGS", [word]]
+        elsif word == "-pthread"
+          append["CCFLAGS", [word]]
+          append["LDFLAGS", [word]]
+        elsif word =~ /^-Wa,(.*)$/
+          append["ASFLAGS", $1.split(",")]
+        elsif word =~ /^-Wl,(.*)$/
+          append["LDFLAGS", $1.split(",")]
+        elsif word =~ /^-Wp,(.*)$/
+          append["CPPFLAGS", $1.split(",")]
+        elsif word.start_with?("-")
+          append["CCFLAGS", [word]]
+        elsif word.start_with?("+")
+          append["CCFLAGS", [word]]
+          append["LDFLAGS", [word]]
+        else
+          append["LIBS", [word]]
+        end
+      end
+      rv
+    end
+
+    def parse_flags!(flags)
+      flags = parse_flags(flags)
+      merge_flags(flags)
+      flags
+    end
+
+    # Merge construction variable flags into this Environment's construction
+    # variables.
+    #
+    # This method does the same thing as {#append}, except that Array values in
+    # +flags+ are appended to the end of Array construction variables instead
+    # of replacing their contents.
+    #
+    # @param flags [Hash]
+    #   Set of construction variables to merge into the current Environment.
+    #   This can be the value (or a modified version) returned by
+    #   {#parse_flags}.
+    #
+    # @return [void]
+    def merge_flags(flags)
+      flags.each_pair do |key, val|
+        if self[key].is_a?(Array) and val.is_a?(Array)
+          self[key] += val
+        else
+          self[key] = val
+        end
+      end
+    end
+
+    # Print the Environment's construction variables for debugging.
+    def dump
+      varset_hash = @varset.to_h
+      varset_hash.keys.sort_by(&:to_s).each do |var|
+        var_str = var.is_a?(Symbol) ? var.inspect : var
+        puts "#{var_str} => #{varset_hash[var].inspect}"
+      end
+    end
+
+    private
+
+    # Expand target and source paths before invoking builders.
+    #
+    # This method expand construction variable references in the target and
+    # source file names before passing them to the builder. It also expands
+    # "^/" prefixes to the Environment's build root if a build root is defined.
+    #
+    # @return [void]
+    def expand_paths!
+      @targets = @targets.reduce({}) do |result, (target, target_params_list)|
+        target = expand_path(target) if @build_root
+        target = expand_varref(target)
+        result[target] = target_params_list.map do |target_params|
+          sources = target_params[:sources].map do |source|
+            source = expand_path(source) if @build_root
+            expand_varref(source)
+          end.flatten
+          target_params.merge(sources: sources)
+        end
+        result
       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.
+    # @param target [String, nil]
-    def parse_makefile_deps(mf_fname, target)
+    #   Name of the target to gather dependencies for, nil for any/all.
+    #
+    # @return [Array<String>] Paths of dependency files.
+    def self.parse_makefile_deps(mf_fname, target)
       deps = []
       buildup = ''
       File.read(mf_fname).each_line do |line|
@@ -223,7 +717,7 @@ module Rscons
           buildup += ' ' + line
           if buildup =~ /^(.*): (.*)$/
             mf_target, mf_deps = $1.strip, $2
-            if mf_target == target
+            if target.nil? or mf_target == target
               deps += mf_deps.split(' ').map(&:strip)
             end
           end
@@ -232,32 +726,5 @@ module Rscons
       end
       deps
     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.
-    # @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.
-    # Return a list of the converted file names.
-    def build_sources(sources, suffixes, cache, vars = {})
-      sources.map do |source|
-        if source.has_suffix?(suffixes)
-          source
-        else
-          converted = nil
-          suffixes.each do |suffix|
-            converted_fname = get_build_fname(source, suffix)
-            builder = @builders.values.find { |b| b.produces?(converted_fname, source, self) }
-            if builder
-              converted = builder.run(converted_fname, [source], cache, self, vars)
-              return nil unless converted
-              break
-            end
-          end
-          converted or raise "Could not find a builder to handle #{source.inspect}."
-        end
-      end
-    end
   end
 end

lib/rscons/monkey/module.rb

@@ -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

lib/rscons/monkey/string.rb

@@ -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

lib/rscons/varset.rb

@@ -1,86 +1,181 @@
 module Rscons
-  # This class represents a collection of variables which can be accessed
+  # This class represents a collection of variables which supports efficient
-  # as certain types
+  # deep cloning.
   class VarSet
-    # The underlying hash
+    # Create a VarSet.
-    attr_reader :vars
+    #
-
-    # Create a VarSet
     # @param vars [Hash] Optional initial variables.
     def initialize(vars = {})
-      if vars.is_a?(VarSet)
+      @my_vars = {}
-        @vars = vars.clone.vars
+      @coa_vars = []
-      else
+      append(vars)
-        @vars = vars
-      end
     end
 
-    # Access the value of variable as a particular type
+    # Access the value of variable.
+    #
     # @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
+    # @return [Object] The variable's value.
-    #   the variable value will be returned. If the variable is an Array and
+    def [](key)
-    #   type is :string, the first element from the variable value will be
+      if @my_vars.include?(key)
-    #   returned.
+        @my_vars[key]
-    def [](key, type = nil)
-      val = @vars[key]
-      if type == :array and val.is_a?(String)
-        [val]
-      elsif type == :string and val.is_a?(Array)
-        val.first
       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
 
-    # Add or overwrite a set of variables
+    # Check if the VarSet contains a variable.
+    #
+    # @param key [String, Symbol] The variable name.
+    #
+    # @return [Boolean] Whether the VarSet contains the 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.
+    #
+    # @return [VarSet] Returns self.
     def append(values)
-      values = values.vars if values.is_a?(VarSet)
+      coa!
-      @vars.merge!(values)
+      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.
+    #
+    # @return [VarSet] The newly created VarSet.
     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
 
-    # Replace "$" variable references in varref with the variables values,
+    # Replace "$!{var}" variable references in varref with the expanded
-    # recursively.
+    # variables' values, recursively.
-    # @param varref [String, Array] Value containing references to variables.
+    #
-    def expand_varref(varref)
+    # @param varref [nil, String, Array, Proc]
-      if varref.is_a?(Array)
+    #   Value containing references to variables.
-        varref.map do |ent|
+    # @param lambda_args [Array]
-          expand_varref(ent)
+    #   Arguments to pass to any lambda variable values to be expanded.
-        end.flatten
+    #
-      else
+    # @return [nil, String, Array]
-        if varref =~ /^(.*)\$\[(\w+)\](.*)$/
+    #   Expanded value with "$!{var}" variable references replaced.
-          # expand array with given prefix, suffix
+    def expand_varref(varref, lambda_args)
+      if varref.is_a?(String)
+        if varref =~ /^(.*)\$\{([^}]+)\}(.*)$/
           prefix, varname, suffix = $1, $2, $3
-          varval = expand_varref(@vars[varname])
+          varval = expand_varref(self[varname], lambda_args)
-          unless varval.is_a?(Array)
+          if varval.is_a?(String) or varval.nil?
-            raise "Array expected for $#{varname}"
+            expand_varref("#{prefix}#{varval}#{suffix}", lambda_args)
+          elsif varval.is_a?(Array)
+            varval.map {|vv| expand_varref("#{prefix}#{vv}#{suffix}", lambda_args)}.flatten
+          else
+            raise "I do not know how to expand a variable reference to a #{varval.class.name} (from #{varname.inspect} => #{self[varname].inspect})"
           end
-          varval.map {|e| "#{prefix}#{e}#{suffix}"}
-        elsif varref =~ /^\$(.*)$/
-          # expand a single variable reference
-          varname = $1
-          varval = expand_varref(@vars[varname])
-          varval or raise "Could not find variable #{varname.inspect}"
-          expand_varref(varval)
         else
           varref
         end
+      elsif varref.is_a?(Array)
+        varref.map do |ent|
+          expand_varref(ent, lambda_args)
+        end.flatten
+      elsif varref.is_a?(Proc)
+        expand_varref(varref[*lambda_args], lambda_args)
+      elsif varref.nil?
+        nil
+      elsif varref.is_a?(Symbol)
+        varref
+      else
+        raise "Unknown varref type: #{varref.class} (#{varref.inspect})"
+      end
+    end
+
+    # Return a Hash containing all variables in the VarSet.
+    #
+    # @since 1.8.0
+    #
+    # This method is not terribly efficient. It is intended to be used only by
+    # debugging code to dump out a VarSet's variables.
+    #
+    # @return [Hash] All variables in the VarSet.
+    def to_h
+      result = deep_dup(@my_vars)
+      @coa_vars.reduce(result) do |result, coa_vars|
+        coa_vars.each_pair do |key, value|
+          unless result.include?(key)
+            result[key] = deep_dup(value)
+          end
+        end
+        result
+      end
+    end
+
+    private
+
+    # Move all VarSet variables into the copy-on-access list.
+    #
+    # @return [void]
+    def coa!
+      unless @my_vars.empty?
+        @coa_vars.unshift(@my_vars)
+        @my_vars = {}
+      end
+    end
+
+    # Create a deep copy of an object.
+    #
+    # Only objects which are of type String, Array, or Hash are deep copied.
+    # Any other object just has its referenced copied.
+    #
+    # @param obj [Object] Object to deep copy.
+    #
+    # @return [Object] 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

lib/rscons/version.rb

@@ -1,4 +1,4 @@
 module Rscons
   # gem version
-  VERSION = "0.0.6"
+  VERSION = "1.9.3"
 end

rscons.gemspec

@@ -1,30 +1,29 @@
 # -*- encoding: utf-8 -*-
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'rscons/version'
+require "rscons/version"
 
 Gem::Specification.new do |gem|
   gem.name          = "rscons"
   gem.version       = Rscons::VERSION
   gem.authors       = ["Josh Holtrop"]
   gem.email         = ["jholtrop@gmail.com"]
-  gem.description   = %q{Software construction library inspired by SCons and implemented in Ruby}
+  gem.description   = %q{Software construction library inspired by SCons and implemented in Ruby.}
   gem.summary       = %q{Software construction library inspired by SCons and implemented in Ruby}
   gem.homepage      = "https://github.com/holtrop/rscons"
-  gem.license       = 'MIT'
+  gem.license       = "MIT"
 
-  gem.files         = `git ls-files`.split($/)
+  gem.files         = Dir["{bin,assets,lib}/**/*", "*.gemspec", "LICENSE.txt"]
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_development_dependency "rspec-core"
+  gem.add_dependency "json", "~> 1.0"
-  gem.add_development_dependency "rspec-mocks"
+
-  gem.add_development_dependency "rspec-expectations"
   gem.add_development_dependency "rspec"
   gem.add_development_dependency "rake"
   gem.add_development_dependency "simplecov"
-  gem.add_development_dependency "json"
-  gem.add_development_dependency 'rdoc'
   gem.add_development_dependency "yard"
+  gem.add_development_dependency "rdoc"
+  gem.add_development_dependency "redcarpet"
 end

spec/rscons/builder_spec.rb

@@ -0,0 +1,9 @@
+module Rscons
+  describe Builder do
+    describe "#run" do
+      it "raises an error if called directly and not through a subclass" do
+        expect{subject.run(:target, :sources, :cache, :env, :vars)}.to raise_error /This method must be overridden in a subclass/
+      end
+    end
+  end
+end

spec/rscons/builders/cfile_spec.rb

@@ -0,0 +1,28 @@
+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
+        expect(subject).to 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"
+        expect(subject).to 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 "supports overriding construction variables" do
+        expect(subject).to receive(:standard_build).with("LEX lexer.c", "lexer.c", ["hi", "parser.l"], ["parser.l"], env, :cache)
+        subject.run("lexer.c", ["parser.l"], :cache, env, "LEX_CMD" => ["hi", "${_SOURCES}"])
+      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

spec/rscons/builders/command_spec.rb

@@ -0,0 +1,18 @@
+module Rscons
+  module Builders
+    describe Command do
+
+      let(:command) { ['pandoc', '-fmarkdown', '-thtml', '-o${_TARGET}', '${_SOURCES}'] }
+      let(:env) {Environment.new}
+      subject {Command.new}
+
+      it "invokes the command to build the target" do
+        expected_cmd = ['pandoc', '-fmarkdown', '-thtml', '-ofoo.html', 'foo.md']
+        expect(subject).to receive(:standard_build).with("PANDOC foo.html", "foo.html", expected_cmd, ["foo.md"], env, :cache)
+        subject.run("foo.html", ["foo.md"], :cache, env,
+                    "CMD" => command, "CMD_DESC" => "PANDOC")
+      end
+
+    end
+  end
+end

spec/rscons/builders/disassemble_spec.rb

@@ -0,0 +1,17 @@
+module Rscons
+  module Builders
+    describe Disassemble do
+      let(:env) {Environment.new}
+      subject {Disassemble.new}
+
+      it "supports overriding DISASM_CMD construction variable" do
+        cache = "cache"
+        allow(cache).to receive(:up_to_date?) { false }
+        allow(cache).to receive(:mkdir_p) { }
+        allow(cache).to receive(:register_build) { }
+        expect(env).to receive(:execute).with("Disassemble a_file.txt", ["my_disasm", "a_file.exe"], anything).and_return(true)
+        subject.run("a_file.txt", ["a_file.exe"], cache, env, "DISASM_CMD" => ["my_disasm", "${_SOURCES}"])
+      end
+    end
+  end
+end

spec/rscons/builders/library_spec.rb

@@ -0,0 +1,18 @@
+module Rscons
+  module Builders
+    describe Library do
+      let(:env) {Environment.new}
+      subject {Library.new}
+
+      it "supports overriding AR construction variable" do
+        expect(subject).to receive(:standard_build).with("AR prog.a", "prog.a", ["sp-ar", "rcs", "prog.a", "prog.o"], ["prog.o"], env, :cache)
+        subject.run("prog.a", ["prog.o"], :cache, env, "AR" => "sp-ar")
+      end
+
+      it "supports overriding ARCMD construction variable" do
+        expect(subject).to receive(:standard_build).with("AR prog.a", "prog.a", ["special", "AR!", "prog.o"], ["prog.o"], env, :cache)
+        subject.run("prog.a", ["prog.o"], :cache, env, "ARCMD" => ["special", "AR!", "${_SOURCES}"])
+      end
+    end
+  end
+end

spec/rscons/builders/object_spec.rb

@@ -0,0 +1,35 @@
+module Rscons
+  module Builders
+    describe Object do
+      let(:env) {Environment.new}
+      let(:cache) {double(Cache)}
+      subject {Object.new}
+
+      it "supports overriding CCCMD construction variable" do
+        expect(cache).to receive(:up_to_date?).and_return(false)
+        expect(cache).to receive(:mkdir_p)
+        expect(FileUtils).to receive(:rm_f)
+        expect(env).to receive(:execute).with("CC mod.o", ["llc", "mod.c"]).and_return(true)
+        expect(File).to receive(:exists?).and_return(false)
+        expect(cache).to receive(:register_build)
+
+        subject.run("mod.o", ["mod.c"], cache, env, "CCCMD" => ["llc", "${_SOURCES}"])
+      end
+
+      it "supports overriding DEPFILESUFFIX construction variable" do
+        expect(cache).to receive(:up_to_date?).and_return(false)
+        expect(cache).to receive(:mkdir_p)
+        expect(FileUtils).to receive(:rm_f)
+        expect(env).to receive(:execute).with(anything, %w[gcc -c -o f.o -MMD -MF f.d in.c]).and_return(true)
+        expect(File).to receive(:exists?).with("f.d").and_return(false)
+        expect(cache).to receive(:register_build)
+
+        subject.run("f.o", ["in.c"], cache, env, "DEPFILESUFFIX" => ".d")
+      end
+
+      it "raises an error when given a source file with an unknown suffix" do
+        expect { subject.run("mod.o", ["mod.xyz"], :cache, env, {}) }.to raise_error /unknown input file type: "mod.xyz"/
+      end
+    end
+  end
+end

spec/rscons/builders/preprocess_spec.rb

@@ -0,0 +1,48 @@
+module Rscons
+  module Builders
+    describe Preprocess do
+
+      let(:env) {Environment.new}
+      subject {Preprocess.new}
+
+      it "supports overriding CC construction variable" do
+        cache = double(Cache)
+        command = %w[my_cpp -E -MMD -MF module.mf -o module.pp module.c]
+        expect(cache).to receive(:up_to_date?).with("module.pp", command, %w[module.c], env).and_return(false)
+        expect(cache).to receive(:mkdir_p).with(".")
+        expect(env).to receive(:execute).with("Preprocess module.pp", command).and_return(true)
+        expect(File).to receive(:exists?).with("module.mf").and_return(true)
+        expect(Environment).to receive(:parse_makefile_deps).with("module.mf", nil).and_return(%w[module.c one.h two.h])
+        expect(FileUtils).to receive(:rm_f).with("module.mf")
+        expect(cache).to receive(:register_build).with("module.pp", command, %w[module.c one.h two.h], env)
+
+        expect(subject.run("module.pp", ["module.c"], cache, env, "CC" => "my_cpp")).to eq("module.pp")
+      end
+
+      it "supports overriding CPP_CMD construction variable" do
+        cache = double(Cache)
+        command = %w[my_cpp module.c]
+        expect(cache).to receive(:up_to_date?).with("module.pp", command, %w[module.c], env).and_return(false)
+        expect(cache).to receive(:mkdir_p).with(".")
+        expect(env).to receive(:execute).with("Preprocess module.pp", command).and_return(true)
+        expect(File).to receive(:exists?).with("module.mf").and_return(true)
+        expect(Environment).to receive(:parse_makefile_deps).with("module.mf", nil).and_return(%w[module.c one.h two.h])
+        expect(FileUtils).to receive(:rm_f).with("module.mf")
+        expect(cache).to receive(:register_build).with("module.pp", command, %w[module.c one.h two.h], env)
+
+        expect(subject.run("module.pp", ["module.c"], cache, env, "CPP_CMD" => ["my_cpp", "${_SOURCES}"])).to eq("module.pp")
+      end
+
+      it "returns false if executing the preprocessor fails" do
+        cache = double(Cache)
+        command = %w[gcc -E -MMD -MF module.mf -o module.pp module.c]
+        expect(cache).to receive(:up_to_date?).with("module.pp", command, %w[module.c], env).and_return(false)
+        expect(cache).to receive(:mkdir_p).with(".")
+        expect(env).to receive(:execute).with("Preprocess module.pp", command).and_return(false)
+
+        expect(subject.run("module.pp", ["module.c"], cache, env, {})).to eq(false)
+      end
+
+    end
+  end
+end

spec/rscons/builders/program_spec.rb

@@ -0,0 +1,18 @@
+module Rscons
+  module Builders
+    describe Program do
+      let(:env) {Environment.new}
+      subject {Program.new}
+
+      it "supports overriding CC construction variable" do
+        expect(subject).to receive(:standard_build).with("LD prog", "prog", ["sp-c++", "-o", "prog", "prog.o"], ["prog.o"], env, :cache)
+        subject.run("prog", ["prog.o"], :cache, env, "CC" => "sp-c++")
+      end
+
+      it "supports overriding LDCMD construction variable" do
+        expect(subject).to receive(:standard_build).with("LD prog.exe", "prog.exe", ["special", "LD!", "prog.o"], ["prog.o"], env, :cache)
+        subject.run("prog.exe", ["prog.o"], :cache, env, "LDCMD" => ["special", "LD!", "${_SOURCES}"])
+      end
+    end
+  end
+end

spec/rscons/builders/simple_builder_spec.rb

@@ -0,0 +1,19 @@
+module Rscons
+  module Builders
+    describe SimpleBuilder do
+      let(:env) {Environment.new}
+
+      it "should create a new builder with the given name (as a symbol) and action" do
+        builder = Rscons::Builders::SimpleBuilder.new(:Foo) { 0x1234 }
+        expect(builder.name).to eq("Foo")
+        expect(builder.run(1,2,3,4,5)).to eq(0x1234)
+      end
+
+      it "should create a new builder with the given name (as a string) and action" do
+        builder = Rscons::Builders::SimpleBuilder.new("Foo") { 0x1234 }
+        expect(builder.name).to eq("Foo")
+        expect(builder.run(1,2,3,4,5)).to eq(0x1234)
+      end
+    end
+  end
+end

spec/rscons/cache_spec.rb

@@ -0,0 +1,271 @@
+module Rscons
+  describe Cache do
+    before do
+      allow(File).to receive(:read) { nil }
+    end
+
+    def build_from(cache)
+      allow(JSON).to receive(:load) do
+        cache
+      end
+      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
+          expect(JSON).to receive(:load).and_return("string")
+          expect($stderr).to receive(:puts).with(/Warning:.*was.corrupt/)
+          c = Cache.instance
+          c.send(:initialize!)
+          expect(c.instance_variable_get(:@cache).is_a?(Hash)).to be_truthy
+        end
+      end
+    end
+
+    describe "#clear" do
+      it "removes the cache file" do
+        expect(FileUtils).to receive(:rm_f).with(Cache::CACHE_FILE)
+        allow(JSON).to receive(:load) {{}}
+        Cache.instance.clear
+      end
+    end
+
+    describe "#write" do
+      it "fills in 'version' and write to file" do
+        cache = {}
+        fh = $stdout
+        expect(fh).to receive(:puts)
+        expect(File).to receive(:open).and_yield(fh)
+        build_from(cache).write
+        expect(cache["version"]).to eq Rscons::VERSION
+      end
+    end
+
+    describe "#up_to_date?" do
+      empty_env = "env"
+      before do
+        allow(empty_env).to receive(:get_user_deps) { nil }
+      end
+
+      it "returns false when target file does not exist" do
+        expect(File).to receive(:exists?).with("target").and_return(false)
+        expect(build_from({}).up_to_date?("target", "command", [], empty_env)).to be_falsey
+      end
+
+      it "returns false when target is not registered in the cache" do
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(build_from({}).up_to_date?("target", "command", [], empty_env)).to be_falsey
+      end
+
+      it "returns false when the target's checksum does not match" do
+        _cache = {"targets" => {"target" => {"checksum" => "abc"}}}
+        cache = build_from(_cache)
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(cache).to receive(:calculate_checksum).with("target").and_return("def")
+        expect(cache.up_to_date?("target", "command", [], empty_env)).to be_falsey
+      end
+
+      it "returns false when the build command has changed" do
+        _cache = {"targets" => {"target" => {"checksum" => "abc", "command" => Digest::MD5.hexdigest("old command".inspect)}}}
+        cache = build_from(_cache)
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(cache).to receive(:calculate_checksum).with("target").and_return("abc")
+        expect(cache.up_to_date?("target", "command", [], empty_env)).to be_falsey
+      end
+
+      it "returns false when there is a new dependency" do
+        _cache = {"targets" => {"target" => {"checksum" => "abc",
+                                         "command" => Digest::MD5.hexdigest("command".inspect),
+                                         "deps" => [{"fname" => "dep.1"}]}}}
+        cache = build_from(_cache)
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(cache).to receive(:calculate_checksum).with("target").and_return("abc")
+        expect(cache.up_to_date?("target", "command", ["dep.1", "dep.2"], empty_env)).to be_falsey
+      end
+
+      it "returns false when a dependency's 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" => []}}}
+        cache = build_from(_cache)
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(cache).to receive(:calculate_checksum).with("target").and_return("abc")
+        expect(cache).to receive(:calculate_checksum).with("dep.1").and_return("dep.1.chk")
+        expect(cache).to receive(:calculate_checksum).with("dep.2").and_return("dep.2.changed")
+        expect(cache.up_to_date?("target", "command", ["dep.1", "dep.2"], empty_env)).to be_falsey
+      end
+
+      it "returns false with strict_deps=true when cache has an extra dependency" 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" => []}}}
+        cache = build_from(_cache)
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(cache).to receive(:calculate_checksum).with("target").and_return("abc")
+        expect(cache.up_to_date?("target", "command", ["dep.1", "dep.2"], empty_env, strict_deps: true)).to be_falsey
+      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"
+        expect(env).to receive(:get_user_deps).with("target").and_return(["file.ld"])
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(cache).to receive(:calculate_checksum).with("target").and_return("abc")
+        expect(cache.up_to_date?("target", "command", ["dep.1"], env)).to be_falsey
+      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"
+        expect(env).to receive(:get_user_deps).with("target").and_return(["user.dep"])
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(cache).to receive(:calculate_checksum).with("target").and_return("abc")
+        expect(cache).to receive(:calculate_checksum).with("dep.1").and_return("dep.1.chk")
+        expect(cache).to receive(:calculate_checksum).with("dep.2").and_return("dep.2.chk")
+        expect(cache).to receive(:calculate_checksum).with("extra.dep").and_return("extra.dep.chk")
+        expect(cache).to receive(:calculate_checksum).with("user.dep").and_return("INCORRECT")
+        expect(cache.up_to_date?("target", "command", ["dep.1", "dep.2"], env)).to be_falsey
+      end
+
+      it "returns true when no condition for false is met" 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" => []}}}
+        cache = build_from(_cache)
+        expect(File).to receive(:exists?).with("target").and_return(true)
+        expect(cache).to receive(:calculate_checksum).with("target").and_return("abc")
+        expect(cache).to receive(:calculate_checksum).with("dep.1").and_return("dep.1.chk")
+        expect(cache).to receive(:calculate_checksum).with("dep.2").and_return("dep.2.chk")
+        expect(cache).to receive(:calculate_checksum).with("extra.dep").and_return("extra.dep.chk")
+        expect(cache.up_to_date?("target", "command", ["dep.1", "dep.2"], empty_env)).to be_truthy
+      end
+    end
+
+    describe "#register_build" do
+      it "stores the given information in the cache" do
+        _cache = {}
+        cache = build_from(_cache)
+        env = "env"
+        expect(env).to receive(:get_user_deps).with("the target").and_return(["user.dep"])
+        expect(cache).to receive(:calculate_checksum).with("the target").and_return("the checksum")
+        expect(cache).to receive(:calculate_checksum).with("dep 1").and_return("dep 1 checksum")
+        expect(cache).to receive(:calculate_checksum).with("dep 2").and_return("dep 2 checksum")
+        expect(cache).to 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"]
+        expect(cached_target).to_not be_nil
+        expect(cached_target["command"]).to eq Digest::MD5.hexdigest("the command".inspect)
+        expect(cached_target["checksum"]).to eq "the checksum"
+        expect(cached_target["deps"]).to eq [
+          {"fname" => "dep 1", "checksum" => "dep 1 checksum"},
+          {"fname" => "dep 2", "checksum" => "dep 2 checksum"},
+        ]
+        expect(cached_target["user_deps"]).to eq [
+          {"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" => {}}}
+        expect(build_from(cache).targets).to eq ["t1", "t2", "t3"]
+      end
+    end
+
+    describe "#mkdir_p" do
+      it "makes directories and records any created in the cache" do
+        _cache = {}
+        cache = build_from(_cache)
+        expect(File).to receive(:exists?).with("one").and_return(true)
+        expect(File).to receive(:exists?).with("one/two").and_return(false)
+        expect(FileUtils).to receive(:mkdir).with("one/two")
+        expect(File).to receive(:exists?).with("one/two/three").and_return(false)
+        expect(FileUtils).to receive(:mkdir).with("one/two/three")
+        expect(File).to receive(:exists?).with("one").and_return(true)
+        expect(File).to receive(:exists?).with("one/two").and_return(true)
+        expect(File).to receive(:exists?).with("one/two/four").and_return(false)
+        expect(FileUtils).to receive(:mkdir).with("one/two/four")
+        cache.mkdir_p("one/two/three")
+        cache.mkdir_p("one\\two\\four")
+        expect(cache.directories).to eq ["one/two", "one/two/three", "one/two/four"]
+      end
+
+      it "handles absolute paths" do
+        _cache = {}
+        cache = build_from(_cache)
+        expect(File).to receive(:exists?).with("/one").and_return(true)
+        expect(File).to receive(:exists?).with("/one/two").and_return(false)
+        expect(FileUtils).to receive(:mkdir).with("/one/two")
+        cache.mkdir_p("/one/two")
+        expect(cache.directories).to eq ["/one/two"]
+      end
+    end
+
+    describe "#directories" do
+      it "returns a list of directories that are cached" do
+        _cache = {"directories" => {"dir1" => true, "dir2" => true}}
+        expect(build_from(_cache).directories).to eq ["dir1", "dir2"]
+      end
+    end
+
+    describe "#lookup_checksum" do
+      it "does not re-calculate the checksum when it is already cached" do
+        cache = build_from({})
+        cache.instance_variable_set(:@lookup_checksums, {"f1" => "f1.chk"})
+        expect(cache).to_not receive(:calculate_checksum)
+        expect(cache.send(:lookup_checksum, "f1")).to eq "f1.chk"
+      end
+
+      it "calls calculate_checksum when the checksum is not cached" do
+        cache = build_from({})
+        expect(cache).to receive(:calculate_checksum).with("f1").and_return("ck")
+        expect(cache.send(:lookup_checksum, "f1")).to eq "ck"
+      end
+    end
+
+    describe "#calculate_checksum" do
+      it "calculates the MD5 of the file contents" do
+        contents = "contents"
+        expect(File).to receive(:read).with("fname", mode: "rb").and_return(contents)
+        expect(Digest::MD5).to receive(:hexdigest).with(contents).and_return("the_checksum")
+        expect(build_from({}).send(:calculate_checksum, "fname")).to eq "the_checksum"
+      end
+    end
+  end
+end

spec/rscons/environment_spec.rb

@@ -1,22 +1,466 @@
 module Rscons
   describe Environment do
-    describe '.parse_makefile_deps' do
+    describe "#initialize" do
+      it "adds the default builders when they are not excluded" do
+        env = Environment.new
+        expect(env.builders.size).to be > 0
+        expect(env.builders.map {|name, builder| builder.is_a?(Builder)}.all?).to be_truthy
+        expect(env.builders.find {|name, builder| name == "Object"}).to_not be_nil
+        expect(env.builders.find {|name, builder| name == "Program"}).to_not be_nil
+        expect(env.builders.find {|name, builder| name == "Library"}).to_not be_nil
+      end
+
+      it "excludes the default builders with exclude_builders: :all" do
+        env = Environment.new(exclude_builders: true)
+        expect(env.builders.size).to eq 0
+      end
+
+      context "when a block is given" do
+        it "yields self and invokes #process()" do
+          env = Environment.new do |env|
+            expect(env).to receive(:process)
+          end
+        end
+      end
+    end
+
+    describe "#clone" do
+      it 'creates unique copies of each construction variable' do
+        env = Environment.new
+        env["CPPPATH"] << "path1"
+        env2 = env.clone
+        env2["CPPPATH"] << "path2"
+        expect(env["CPPPATH"]).to eq ["path1"]
+        expect(env2["CPPPATH"]).to eq ["path1", "path2"]
+      end
+
+      it "supports nil, false, true, String, Symbol, Array, Hash, and Integer variables" do
+        env = Environment.new
+        env["nil"] = nil
+        env["false"] = false
+        env["true"] = true
+        env["String"] = "String"
+        env["Symbol"] = :Symbol
+        env["Array"] = ["a", "b"]
+        env["Hash"] = {"a" => "b"}
+        env["Integer"] = 1234
+        env2 = env.clone
+        expect(env2["nil"]).to be_nil
+        expect(env2["false"].object_id).to eq(false.object_id)
+        expect(env2["true"].object_id).to eq(true.object_id)
+        expect(env2["String"]).to eq("String")
+        expect(env2["Symbol"]).to eq(:Symbol)
+        expect(env2["Array"]).to eq(["a", "b"])
+        expect(env2["Hash"]).to eq({"a" => "b"})
+        expect(env2["Integer"]).to eq(1234)
+      end
+
+      context "when a block is given" do
+        it "yields self and invokes #process()" do
+          env = Environment.new
+          env.clone do |env2|
+            expect(env2).to receive(:process)
+          end
+        end
+      end
+    end
+
+    describe "#add_builder" do
+      it "adds the builder to the list of builders" do
+        env = Environment.new(exclude_builders: true)
+        expect(env.builders.keys).to eq []
+        env.add_builder(Rscons::Builders::Object.new)
+        expect(env.builders.keys).to eq ["Object"]
+      end
+
+      it "adds a new simple builder to the list of builders" do
+        env = Environment.new(exclude_builders: true)
+        expect(env.builders.keys).to eq []
+        env.add_builder(:Foo) {}
+        expect(env.builders.keys).to eq ["Foo"]
+      end
+    end
+
+    describe "#get_build_fname" do
+      context "with no build directories" do
+        it "returns the name of the source file with suffix changed" do
+          env = Environment.new
+          expect(env.get_build_fname("src/dir/file.c", ".o")).to eq "src/dir/file.o"
+          expect(env.get_build_fname("src\\dir\\other.d", ".a")).to eq "src/dir/other.a"
+          expect(env.get_build_fname("source.cc", ".o")).to eq "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"
+            expect(env.get_build_fname("src/dir/file.c", ".o")).to eq "build/proj/src/dir/file.o"
+            expect(env.get_build_fname("/some/lib.c", ".a")).to eq "/some/lib.a"
+            expect(env.get_build_fname("C:\\abspath\\mod.cc", ".o")).to eq "C:/abspath/mod.o"
+            expect(env.get_build_fname("build\\proj\\generated.c", ".o")).to eq "build/proj/generated.o"
+            expect(env.get_build_fname("build/proj.XX", ".yy")).to eq "build/proj/build/proj.yy"
+          end
+        end
+      end
+
+      context "with build directories" do
+        it "uses the build directories to create the output file name" do
+          env = Environment.new
+          env.build_dir("src", "bld")
+          env.build_dir(%r{^libs/([^/]+)}, 'build/libs/\1')
+          expect(env.get_build_fname("src/input.cc", ".o")).to eq "bld/input.o"
+          expect(env.get_build_fname("libs/lib1/some/file.c", ".o")).to eq "build/libs/lib1/some/file.o"
+          expect(env.get_build_fname("libs/otherlib/otherlib.cc", ".o")).to eq "build/libs/otherlib/otherlib.o"
+          expect(env.get_build_fname("other_directory/o.d", ".a")).to eq "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"
+
+            expect(env.get_build_fname("src/input.cc", ".o")).to eq "bld/input.o"
+            expect(env.get_build_fname("libs/lib1/some/file.c", ".o")).to eq "build/libs/lib1/some/file.o"
+            expect(env.get_build_fname("libs/otherlib/otherlib.cc", ".o")).to eq "build/libs/otherlib/otherlib.o"
+            expect(env.get_build_fname("other_directory/o.d", ".a")).to eq "bldit/other_directory/o.a"
+            expect(env.get_build_fname("bldit/some/mod.d", ".a")).to eq "bldit/some/mod.a"
+          end
+        end
+      end
+    end
+
+    describe "#[]" do
+      it "allows reading construction variables" do
+        env = Environment.new
+        env["CFLAGS"] = ["-g", "-Wall"]
+        expect(env["CFLAGS"]).to eq ["-g", "-Wall"]
+      end
+    end
+
+    describe "#[]=" do
+      it "allows writing construction variables" do
+        env = Environment.new
+        env["CFLAGS"] = ["-g", "-Wall"]
+        env["CFLAGS"] -= ["-g"]
+        env["CFLAGS"] += ["-O3"]
+        expect(env["CFLAGS"]).to eq ["-Wall", "-O3"]
+        env["other_var"] = "val33"
+        expect(env["other_var"]).to eq "val33"
+      end
+    end
+
+    describe "#append" do
+      it "allows adding many construction variables at once" do
+        env = Environment.new
+        env["CFLAGS"] = ["-g"]
+        env["CPPPATH"] = ["inc"]
+        env.append("CFLAGS" => ["-Wall"], "CPPPATH" => ["include"])
+        expect(env["CFLAGS"]).to eq ["-Wall"]
+        expect(env["CPPPATH"]).to eq ["include"]
+      end
+    end
+
+    describe "#process" do
+      it "runs builders for all of the targets specified" do
+        env = Environment.new
+        env.Program("a.out", "main.c")
+
+        cache = "cache"
+        expect(Cache).to receive(:instance).and_return(cache)
+        expect(cache).to receive(:clear_checksum_cache!)
+        expect(env).to receive(:run_builder).with(anything, "a.out", ["main.c"], cache, {}).and_return(true)
+        expect(cache).to receive(:write)
+
+        env.process
+      end
+
+      it "builds dependent targets first" do
+        env = Environment.new
+        env.Program("a.out", "main.o")
+        env.Object("main.o", "other.cc")
+
+        cache = "cache"
+        expect(Cache).to receive(:instance).and_return(cache)
+        expect(cache).to receive(:clear_checksum_cache!)
+        expect(env).to receive(:run_builder).with(anything, "main.o", ["other.cc"], cache, {}).and_return("main.o")
+        expect(env).to receive(:run_builder).with(anything, "a.out", ["main.o"], cache, {}).and_return("a.out")
+        expect(cache).to receive(:write)
+
+        env.process
+      end
+
+      it "raises a BuildError when building fails" do
+        env = Environment.new
+        env.Program("a.out", "main.o")
+        env.Object("main.o", "other.cc")
+
+        cache = "cache"
+        expect(Cache).to receive(:instance).and_return(cache)
+        expect(cache).to receive(:clear_checksum_cache!)
+        expect(env).to receive(:run_builder).with(anything, "main.o", ["other.cc"], cache, {}).and_return(false)
+        expect(cache).to 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"
+        expect(Cache).to receive(:instance).and_return(cache)
+        expect(cache).to receive(:clear_checksum_cache!)
+        allow(env).to receive(:run_builder) do |builder, target, sources, cache, vars|
+          raise "Ruby exception thrown by builder"
+        end
+        expect(cache).to 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
+      it "returns a command based on the variables in the Environment" do
+        env = Environment.new
+        env["path"] = ["dir1", "dir2"]
+        env["flags"] = ["-x", "-y", "${specialflag}"]
+        env["specialflag"] = "-z"
+        template = ["cmd", "-I${path}", "${flags}", "${_source}", "${_dest}"]
+        cmd = env.build_command(template, "_source" => "infile", "_dest" => "outfile")
+        expect(cmd).to eq ["cmd", "-Idir1", "-Idir2", "-x", "-y", "-z", "infile", "outfile"]
+      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["foo"] = {}
+        expect(env.expand_varref(["-p${path}", "${flags}"])).to eq ["-pdir1", "-pdir2", "-x", "-y", "-z"]
+        expect(env.expand_varref("foo")).to eq "foo"
+        expect {env.expand_varref("${foo}")}.to raise_error /Unknown.varref.type/
+        expect(env.expand_varref("${specialflag}")).to eq "-z"
+        expect(env.expand_varref("${path}")).to eq ["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)
+            expect(env).to receive(:puts).with("short desc")
+            expect(env).to receive(:system).with(*Rscons.command_executer, "a", "command").and_return(true)
+            env.execute("short desc", ["a", "command"])
+          end
+        end
+
+        context "with errors" do
+          it "prints the short description, executes the command, and prints the failed command line" do
+            env = Environment.new(echo: :short)
+            expect(env).to receive(:puts).with("short desc")
+            expect(env).to receive(:system).with(*Rscons.command_executer, "a", "command").and_return(false)
+            expect($stdout).to receive(:write).with("Failed command was: ")
+            expect(env).to receive(:puts).with("a command")
+            env.execute("short desc", ["a", "command"])
+          end
+        end
+      end
+
+      context "with echo: :command" do
+        it "prints the command executed and executes the command" do
+          env = Environment.new(echo: :command)
+          expect(env).to receive(:puts).with("a command '--arg=val with spaces'")
+          expect(env).to receive(:system).with({modified: :environment}, *Rscons.command_executer, "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
+
+    describe "#method_missing" do
+      it "calls the original method missing when the target method is not a known builder" do
+        env = Environment.new
+        expect {env.foobar}.to raise_error /undefined method .foobar./
+      end
+
+      it "records the target when the target method is a known builder" do
+        env = Environment.new
+        expect(env.instance_variable_get(:@targets)).to eq({})
+        env.Object("target.o", ["src1.c", "src2.c"], var: "val")
+        target = env.instance_variable_get(:@targets)["target.o"]
+        expect(target).to_not be_nil
+        expect(target[0][:builder].is_a?(Builder)).to be_truthy
+        expect(target[0][:sources]).to eq ["src1.c", "src2.c"]
+        expect(target[0][:vars]).to eq({var: "val"})
+        expect(target[0][:args]).to eq []
+      end
+
+      it "raises an error when vars is not a Hash" do
+        env = Environment.new
+        expect { env.Program("a.out", "main.c", "other") }.to raise_error /Unexpected construction variable set/
+      end
+    end
+
+    describe "#depends" do
+      it "records the given dependencies in @user_deps" do
+        env = Environment.new
+        env.depends("foo", "bar", "baz")
+        expect(env.instance_variable_get(:@user_deps)).to eq({"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")
+        expect(env.instance_variable_get(:@user_deps)).to eq({"foo" => ["bar", "baz"]})
+      end
+      it "expands arguments for construction variable references" do
+        env = Environment.new
+        env["foo"] = "foo.exe"
+        env["bar"] = "bar.c"
+        env.depends("${foo}", "${bar}", "a.h")
+        expect(env.instance_variable_get(:@user_deps)).to eq({"foo.exe" => ["bar.c", "a.h"]})
+      end
+    end
+
+    describe "#build_sources" do
+      class ABuilder < Builder
+        def produces?(target, source, env)
+          target =~ /\.ab_out$/ and source =~ /\.ab_in$/
+        end
+      end
+
+      it "finds and invokes a builder to produce output files with the requested suffixes" do
+        cache = "cache"
+        env = Environment.new
+        env.add_builder(ABuilder.new)
+        expect(env.builders["Object"]).to receive(:run).with("mod.o", ["mod.c"], cache, env, anything).and_return("mod.o")
+        expect(env.builders["ABuilder"]).to receive(:run).with("mod2.ab_out", ["mod2.ab_in"], cache, env, anything).and_return("mod2.ab_out")
+        expect(env.build_sources(["precompiled.o", "mod.c", "mod2.ab_in"], [".o", ".ab_out"], cache, {})).to eq ["precompiled.o", "mod.o", "mod2.ab_out"]
+      end
+    end
+
+    describe "#run_builder" do
+      it "modifies the construction variables using given build hooks and invokes the builder" do
+        env = Environment.new
+        env.add_build_hook do |build_op|
+          if build_op[:sources].first =~ %r{src/special}
+            build_op[:vars]["CFLAGS"] += ["-O3", "-DSPECIAL"]
+          end
+        end
+        allow(env.builders["Object"]).to receive(:run) do |target, sources, cache, env, vars|
+          expect(vars["CFLAGS"]).to eq []
+        end
+        env.run_builder(env.builders["Object"], "build/normal/module.o", ["src/normal/module.c"], "cache", {})
+        allow(env.builders["Object"]).to receive(:run) do |target, sources, cache, env, vars|
+          expect(vars["CFLAGS"]).to eq ["-O3", "-DSPECIAL"]
+        end
+        env.run_builder(env.builders["Object"], "build/special/module.o", ["src/special/module.c"], "cache", {})
+      end
+    end
+
+    describe "#shell" do
+      it "executes the given shell command and returns the results" do
+        env = Environment.new
+        expect(env.shell("echo hello").strip).to eq("hello")
+      end
+      it "determines shell flag to be /c when SHELL is specified as 'cmd'" do
+        env = Environment.new
+        env["SHELL"] = "cmd"
+        expect(IO).to receive(:popen).with(["cmd", "/c", "my_cmd"])
+        env.shell("my_cmd")
+      end
+      it "determines shell flag to be -c when SHELL is specified as something else" do
+        env = Environment.new
+        env["SHELL"] = "my_shell"
+        expect(IO).to receive(:popen).with(["my_shell", "-c", "my_cmd"])
+        env.shell("my_cmd")
+      end
+    end
+
+    describe "#parse_flags" do
+      it "executes the shell command and parses the returned flags when the input argument begins with !" do
+        env = Environment.new
+        env["CCFLAGS"] = ["-g"]
+        expect(env).to receive(:shell).with("my_command").and_return(%[-arch my_arch -Done=two -include ii -isysroot sr -Iincdir -Llibdir -lmy_lib -mno-cygwin -mwindows -pthread -std=c99 -Wa,'asm,args 1 2' -Wl,linker,"args 1 2" -Wp,cpp,args,1,2 -arbitrary +other_arbitrary some_lib /a/b/c/lib])
+        rv = env.parse_flags("!my_command")
+        expect(rv).to eq({
+          "CCFLAGS" => %w[-arch my_arch -include ii -isysroot sr -mno-cygwin -pthread -std=c99 -arbitrary +other_arbitrary],
+          "LDFLAGS" => %w[-arch my_arch -isysroot sr -mno-cygwin -mwindows -pthread] + ["linker", "args 1 2"] + %w[+other_arbitrary],
+          "CPPPATH" => %w[incdir],
+          "LIBS" => %w[my_lib some_lib /a/b/c/lib],
+          "LIBPATH" => %w[libdir],
+          "CPPDEFINES" => %w[one=two],
+          "ASFLAGS" => ["asm", "args 1 2"],
+          "CPPFLAGS" => %w[cpp args 1 2],
+        })
+        expect(env["CCFLAGS"]).to eq(["-g"])
+        expect(env["ASFLAGS"]).to eq([])
+        env.merge_flags(rv)
+        expect(env["CCFLAGS"]).to eq(%w[-g -arch my_arch -include ii -isysroot sr -mno-cygwin -pthread -std=c99 -arbitrary +other_arbitrary])
+        expect(env["ASFLAGS"]).to eq(["asm", "args 1 2"])
+      end
+    end
+
+    describe "#parse_flags!" do
+      it "parses the given build flags and merges them into the Environment" do
+        env = Environment.new
+        env["CFLAGS"] = ["-g"]
+        rv = env.parse_flags!("-I incdir -D my_define -L /a/libdir -l /some/lib")
+        expect(rv).to eq({
+          "CPPPATH" => %w[incdir],
+          "LIBS" => %w[/some/lib],
+          "LIBPATH" => %w[/a/libdir],
+          "CPPDEFINES" => %w[my_define],
+        })
+        expect(env["CPPPATH"]).to eq(%w[incdir])
+        expect(env["LIBS"]).to eq(%w[/some/lib])
+        expect(env["LIBPATH"]).to eq(%w[/a/libdir])
+        expect(env["CPPDEFINES"]).to eq(%w[my_define])
+      end
+    end
+
+    describe "#merge_flags" do
+      it "appends array contents and replaces other variable values" do
+        env = Environment.new
+        env["CPPPATH"] = ["incdir"]
+        env["CSUFFIX"] = ".x"
+        env.merge_flags("CPPPATH" => ["a"], "CSUFFIX" => ".c")
+        expect(env["CPPPATH"]).to eq(%w[incdir a])
+        expect(env["CSUFFIX"]).to eq(".c")
+      end
+    end
+
+    describe ".parse_makefile_deps" do
       it 'handles dependencies on one line' do
-        File.should_receive(:read).with('makefile').and_return(<<EOS)
+        expect(File).to receive(:read).with('makefile').and_return(<<EOS)
 module.o: source.cc
 EOS
-        env = Environment.new
+        expect(Environment.parse_makefile_deps('makefile', 'module.o')).to eq ['source.cc']
-        env.parse_makefile_deps('makefile', 'module.o').should == ['source.cc']
       end
 
       it 'handles dependencies split across many lines' do
-        File.should_receive(:read).with('makefile').and_return(<<EOS)
+        expect(File).to receive(:read).with('makefile').and_return(<<EOS)
 module.o: module.c \\
   module.h \\
   other.h
 EOS
-        env = Environment.new
+        expect(Environment.parse_makefile_deps('makefile', 'module.o')).to eq [
-        env.parse_makefile_deps('makefile', 'module.o').should == [
           'module.c', 'module.h', 'other.h']
       end
     end

spec/rscons/varset_spec.rb

@@ -0,0 +1,203 @@
+module Rscons
+  describe VarSet do
+
+    describe '#initialize' do
+      it "initializes variables from a Hash" do
+        v = VarSet.new({"one" => 1, "two" => :two})
+        expect(v["one"]).to eq(1)
+        expect(v["two"]).to eq(:two)
+      end
+      it "initializes variables from another VarSet" do
+        v = VarSet.new({"one" => 1})
+        v2 = VarSet.new(v)
+        expect(v2["one"]).to eq 1
+      end
+      it "makes a deep copy of the given VarSet" do
+        v = VarSet.new({"array" => [1, 2, 3]})
+        v2 = VarSet.new(v)
+        v["array"] << 4
+        expect(v["array"]).to eq([1, 2, 3, 4])
+        expect(v2["array"]).to eq([1, 2, 3])
+      end
+    end
+
+    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}})
+        expect(v["fuz"]).to eq("a string")
+        expect(v["foo"]).to eq(42)
+        expect(v["bar"]).to eq(:baz)
+        expect(v["qax"]).to eq([3, 6])
+        expect(v["qux"]).to eq({a: :b})
+      end
+    end
+
+    describe "#[]=" do
+      it "allows assigning to variables" do
+        v = VarSet.new("CFLAGS" => ["-Wall", "-O3"])
+        v["CPPPATH"] = ["one", "two"]
+        expect(v["CFLAGS"]).to eq(["-Wall", "-O3"])
+        expect(v["CPPPATH"]).to eq(["one", "two"])
+      end
+    end
+
+    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_truthy
+        expect(v.include?(:CFLAGS)).to be_falsey
+        expect(v.include?(:foo)).to be_truthy
+        expect(v.include?("foo")).to be_falsey
+        expect(v.include?("bar")).to be_falsey
+
+        v2 = v.clone
+        v2.append("bar" => [])
+
+        expect(v2.include?("CFLAGS")).to be_truthy
+        expect(v2.include?(:CFLAGS)).to be_falsey
+        expect(v2.include?(:foo)).to be_truthy
+        expect(v2.include?("foo")).to be_falsey
+        expect(v2.include?("bar")).to be_truthy
+      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"])
+        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)
+        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
+      it "returns a new VarSet merged with the given Hash" do
+        v = VarSet.new("foo" => "yoda")
+        v2 = v.merge("baz" => "qux")
+        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"
+        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
+      v = VarSet.new("CFLAGS" => ["-Wall", "-O2"],
+                     "CC" => "gcc",
+                     "CPPPATH" => ["dir1", "dir2"],
+                     "compiler" => "${CC}",
+                     "cmd" => ["${CC}", "-c", "${CFLAGS}", "-I${CPPPATH}"],
+                     "lambda" => lambda {|args| "#{args[:v]}--12"})
+      it "expands to the string itself if the string is not a variable reference" do
+        expect(v.expand_varref("CC", :lambda_args)).to eq("CC")
+        expect(v.expand_varref("CPPPATH", :lambda_args)).to eq("CPPPATH")
+        expect(v.expand_varref("str", :lambda_args)).to eq("str")
+      end
+      it "expands a single variable reference beginning with a '$'" do
+        expect(v.expand_varref("${CC}", :lambda_args)).to eq("gcc")
+        expect(v.expand_varref("${CPPPATH}", :lambda_args)).to eq(["dir1", "dir2"])
+      end
+      it "expands a single variable reference in ${arr} notation" do
+        expect(v.expand_varref("prefix${CFLAGS}suffix", :lambda_args)).to eq(["prefix-Wallsuffix", "prefix-O2suffix"])
+        expect(v.expand_varref(v["cmd"], :lambda_args)).to eq(["gcc", "-c", "-Wall", "-O2", "-Idir1", "-Idir2"])
+      end
+      it "expands a variable reference recursively" do
+        expect(v.expand_varref("${compiler}", :lambda_args)).to eq("gcc")
+        expect(v.expand_varref("${cmd}", :lambda_args)).to eq(["gcc", "-c", "-Wall", "-O2", "-Idir1", "-Idir2"])
+      end
+      it "resolves multiple variable references in one element by enumerating all combinations" do
+        expect(v.expand_varref("cflag: ${CFLAGS}, cpppath: ${CPPPATH}, compiler: ${compiler}", :lambda_args)).to eq([
+          "cflag: -Wall, cpppath: dir1, compiler: gcc",
+          "cflag: -O2, cpppath: dir1, compiler: gcc",
+          "cflag: -Wall, cpppath: dir2, compiler: gcc",
+          "cflag: -O2, cpppath: dir2, compiler: gcc",
+        ])
+      end
+      it "returns an empty string when a variable reference refers to a non-existent variable" do
+        expect(v.expand_varref("${not_here}", :lambda_args)).to eq("")
+      end
+      it "calls a lambda with the given lambda arguments" do
+        expect(v.expand_varref("${lambda}", [v: "fez"])).to eq("fez--12")
+      end
+      it "raises an error when given an invalid argument" do
+        expect { v.expand_varref({a: :b}, :lambda_args) }.to raise_error /Unknown varref type: Hash/
+      end
+      it "raises an error when an expanded variable is an unexpected type" do
+        expect(v).to receive(:[]).at_least(1).times.with("bad").and_return("bad_val")
+        expect(v).to receive(:expand_varref).with("bad_val", :lambda_args).and_return({a: :b})
+        expect(v).to receive(:expand_varref).and_call_original
+        expect { v.expand_varref("${bad}", :lambda_args) }.to raise_error /I do not know how to expand a variable reference to a Hash/
+      end
+    end
+
+    describe "#to_h" do
+      it "returns a Hash of all variables in the VarSet" do
+        v = VarSet.new({"fuz" => "a string", "foo" => 42, "bar" => :baz,
+                        "qax" => [3, 6], "qux" => {a: :b}})
+        v2 = v.merge("baz" => "qux", "qax" => [4, 7])
+        v3 = v2.merge("fuz" => nil)
+        v4 = v3.clone
+        v4["fuz"] = :fuzzy
+        v4["foo"] = 43
+        expect(v.to_h).to eq({
+          "fuz" => "a string", "foo" => 42, "bar" => :baz,
+          "qax" => [3, 6], "qux" => {a: :b},
+        })
+        expect(v2.to_h).to eq({
+          "fuz" => "a string", "foo" => 42, "bar" => :baz,
+          "qax" => [4, 7], "qux" => {a: :b}, "baz" => "qux",
+        })
+        expect(v3.to_h).to eq({
+          "fuz" => nil, "foo" => 42, "bar" => :baz,
+          "qax" => [4, 7], "qux" => {a: :b}, "baz" => "qux",
+        })
+        expect(v4.to_h).to eq({
+          "fuz" => :fuzzy, "foo" => 43, "bar" => :baz,
+          "qax" => [4, 7], "qux" => {a: :b}, "baz" => "qux",
+        })
+        expect(VarSet.new.to_h).to eq({})
+      end
+    end
+
+  end
+end

spec/rscons_spec.rb

@@ -0,0 +1,125 @@
+describe Rscons do
+  describe ".clean" do
+    it "removes all build targets and created directories" do
+      cache = "cache"
+      expect(Rscons::Cache).to receive(:instance).and_return(cache)
+      expect(cache).to receive(:targets).and_return(["build/a.out", "build/main.o"])
+      expect(FileUtils).to receive(:rm_f).with("build/a.out")
+      expect(FileUtils).to receive(:rm_f).with("build/main.o")
+      expect(cache).to receive(:directories).and_return(["build/one", "build/one/two", "build", "other"])
+      expect(File).to receive(:directory?).with("build/one/two").and_return(true)
+      expect(Dir).to receive(:entries).with("build/one/two").and_return([".", ".."])
+      expect(Dir).to receive(:rmdir).with("build/one/two")
+      expect(File).to receive(:directory?).with("build/one").and_return(true)
+      expect(Dir).to receive(:entries).with("build/one").and_return([".", ".."])
+      expect(Dir).to receive(:rmdir).with("build/one")
+      expect(File).to receive(:directory?).with("build").and_return(true)
+      expect(Dir).to receive(:entries).with("build").and_return([".", ".."])
+      expect(Dir).to receive(:rmdir).with("build")
+      expect(File).to receive(:directory?).with("other").and_return(true)
+      expect(Dir).to receive(:entries).with("other").and_return([".", "..", "other.file"])
+      expect(cache).to receive(:clear)
+
+      Rscons.clean
+    end
+  end
+
+  describe ".set_suffix" do
+    it "changes the suffix to the new one" do
+      expect(Rscons.set_suffix("foo.c", ".h")).to eq("foo.h")
+    end
+
+    it "appends a suffix if the given file name does not have one" do
+      expect(Rscons.set_suffix("bazz", ".d")).to eq("bazz.d")
+    end
+  end
+
+  describe ".get_system_shell" do
+    before(:each) do
+      Rscons.instance_variable_set(:@shell, nil)
+    end
+
+    after(:each) do
+      Rscons.instance_variable_set(:@shell, nil)
+    end
+
+    it "uses the SHELL environment variable if it tests successfully" do
+      my_ENV = {"SHELL" => "my_shell"}
+      allow(ENV).to receive(:[]) {|*args| my_ENV[*args]}
+      io = StringIO.new("success\n")
+      expect(IO).to receive(:popen).with(["my_shell", "-c", "echo success"]).and_yield(io)
+      expect(Rscons.get_system_shell).to eq(["my_shell", "-c"])
+    end
+
+    it "uses sh -c on a mingw platform if it tests successfully" do
+      my_ENV = {"SHELL" => nil}
+      allow(ENV).to receive(:[]) {|*args| my_ENV[*args]}
+      io = StringIO.new("success\n")
+      expect(IO).to receive(:popen).with(["sh", "-c", "echo success"]).and_yield(io)
+      expect(Object).to receive(:const_get).with("RUBY_PLATFORM").and_return("x86-mingw")
+      expect(Rscons.get_system_shell).to eq(["sh", "-c"])
+    end
+
+    it "uses cmd /c on a mingw platform if sh -c does not test successfully" do
+      my_ENV = {"SHELL" => nil}
+      allow(ENV).to receive(:[]) {|*args| my_ENV[*args]}
+      io = StringIO.new("success\n")
+      expect(IO).to receive(:popen).with(["sh", "-c", "echo success"]).and_raise "ENOENT"
+      expect(Object).to receive(:const_get).with("RUBY_PLATFORM").and_return("x86-mingw")
+      expect(Rscons.get_system_shell).to eq(["cmd", "/c"])
+    end
+
+    it "uses sh -c on a non-mingw platform if SHELL is not specified" do
+      my_ENV = {"SHELL" => nil}
+      allow(ENV).to receive(:[]) {|*args| my_ENV[*args]}
+      expect(Object).to receive(:const_get).with("RUBY_PLATFORM").and_return("x86-linux")
+      expect(Rscons.get_system_shell).to eq(["sh", "-c"])
+    end
+  end
+
+  context "command executer" do
+    describe ".command_executer" do
+      before(:each) do
+        Rscons.instance_variable_set(:@command_executer, nil)
+      end
+
+      after(:each) do
+        Rscons.instance_variable_set(:@command_executer, nil)
+      end
+
+      it "returns ['env'] if mingw platform in MSYS and 'env' works" do
+        expect(Object).to receive(:const_get).and_return("x86-mingw")
+        expect(ENV).to receive(:keys).and_return(["MSYSCON"])
+        io = StringIO.new("success\n")
+        expect(IO).to receive(:popen).with(["env", "echo", "success"]).and_yield(io)
+        expect(Rscons.command_executer).to eq(["env"])
+      end
+
+      it "returns [] if mingw platform in MSYS and 'env' does not work" do
+        expect(Object).to receive(:const_get).and_return("x86-mingw")
+        expect(ENV).to receive(:keys).and_return(["MSYSCON"])
+        expect(IO).to receive(:popen).with(["env", "echo", "success"]).and_raise "ENOENT"
+        expect(Rscons.command_executer).to eq([])
+      end
+
+      it "returns [] if mingw platform not in MSYS" do
+        expect(Object).to receive(:const_get).and_return("x86-mingw")
+        expect(ENV).to receive(:keys).and_return(["COMSPEC"])
+        expect(Rscons.command_executer).to eq([])
+      end
+
+      it "returns [] if not mingw platform" do
+        expect(Object).to receive(:const_get).and_return("x86-linux")
+        expect(Rscons.command_executer).to eq([])
+      end
+    end
+
+    describe ".command_executer=" do
+      it "overrides the value of @command_executer" do
+        Rscons.instance_variable_set(:@command_executer, ["env"])
+        Rscons.command_executer = []
+        expect(Rscons.instance_variable_get(:@command_executer)).to eq([])
+      end
+    end
+  end
+end

spec/spec_helper.rb

@@ -1 +1,7 @@
+require "simplecov"
+
+SimpleCov.start do
+  add_filter "/spec/"
+end
+
 require "rscons"