v0.2.0

this change is backwards-incompatible

.gitignore

@@ -15,4 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
-build_tests_run
+build_test_run

README.md

@@ -2,11 +2,13 @@
 
 Software construction library 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:
 
@@ -18,20 +20,135 @@ Or install it yourself as:
 
 ## Usage
 
-    RScons::Environment.new do |env|
+Rscons is a Ruby library.
-      env.Program('program', Dir['*.c'])
+It can be called from a standalone Ruby script or it can be used with rake and
-    end
+called from your Rakefile.
 
-    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
+
+```ruby
+class GenerateFoo < Rscons::Builder
+  def run(target, sources, cache, env, vars)
+    File.open(target, "w") do |fh|
+      fh.puts <<EOF
+#define GENERATED 42
+EOF
     end
+  end
+end
+
+Rscons::Environment.new do |env|
+  env.GenerateFoo("foo.h", [])
+  env.Program("a.out", Dir["*.c"])
+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
+```
+
+### Example: Creating a static library
+
+```ruby
+Rscons::Environment.new do |env|
+  env.Library("mylib.a", Dir["src/**/*.c"])
+end
+```
+
+## Details
+
+### Default Builders
+
+Rscons ships with a number of default builders:
+
+* Library, which collects object files into a static library archive file
+* Object, which compiles source files to produce an object file
+* Program, which links object files to produce an executable
+
+If you want to create an Environment that does not contain any (or select)
+builders, you can use the `exclude_builders` key to the Environment constructor.
+
+### Managing Environments
+
+An Rscons::Environment consists of:
+
+* a collection of construction variables
+* a collection of builders
+* a mapping of build directories
+* a collection of targets to build
+* a collection of build hooks
+
+When cloning an environment, the construction variables and builders are
+cloned, but the new environment does not inherit any of the targets, build
+hooks, build directories, or the build root from the source environment.
+
+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".
+
+### Construction Variables
+
+The default construction variables that Rscons uses are named using uppercase
+strings.
+Rscons options are lowercase symbols.
+Lowercase strings are reserved as user-defined construction variables.
 
 ## Contributing
 

Rakefile.rb

@@ -7,11 +7,8 @@ end
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-require "rake/clean"
 require "yard"
 
-CLEAN.include 'build_tests_run'
-
 RSpec::Core::RakeTask.new(:spec)
 
 YARD::Rake::YardocTask.new do |yard|
@@ -19,3 +16,11 @@ YARD::Rake::YardocTask.new do |yard|
 end
 
 task :default => :spec
+
+task :clean do
+  FileUtils.rm_rf(["build_test_run", "doc", "coverage"])
+end
+
+task :clobber => :clean do
+  FileUtils.rm_rf(["pkg"])
+end

build_tests/build_dir/build.rb

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

build_tests/build_dir/tweaker_build.rb

@@ -1,12 +0,0 @@
-Rscons::Environment.new do |env|
-  env.append('CPPPATH' => Dir['src/**/*/'])
-  env.build_dir(%r{^src/([^/]+)/}, 'build_\\1/')
-  env.add_tweaker do |build_op|
-    if build_op[:target] =~ %r{build_one/.*\.o}
-      build_op[:vars]["CFLAGS"] << "-O1"
-    elsif build_op[:target] =~ %r{build_two/.*\.o}
-      build_op[:vars]["CFLAGS"] << "-O2"
-    end
-  end
-  env.Program('tweaker', 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,15 +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, builders: [MySource.new]) do |env|
-  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/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/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/builders/library.rb

@@ -8,7 +8,7 @@ module Rscons
         'AR' => 'ar',
         'LIBSUFFIX' => '.a',
         'ARFLAGS' => [],
-        'ARCOM' => ['$AR', 'rcs', '$ARFLAGS', '$_TARGET', '$_SOURCES']
+        'ARCMD' => ['${AR}', 'rcs', '${ARFLAGS}', '${_TARGET}', '${_SOURCES}']
       }
     end
 
@@ -20,7 +20,7 @@ module Rscons
           '_TARGET' => target,
           '_SOURCES' => objects,
         })
-        command = env.build_command(env['ARCOM'], vars)
+        command = env.build_command(env['ARCMD'], vars)
         standard_build("AR #{target}", target, command, objects, env, cache)
       end
     end

lib/rscons/builders/object.rb

@@ -2,17 +2,24 @@ module Rscons
   # A default RScons builder which knows how to produce an object file from
   # various types of source files.
   class Object < Builder
+    KNOWN_SUFFIXES = {
+      "AS" => "ASSUFFIX",
+      "CC" => "CSUFFIX",
+      "CXX" => "CXXSUFFIX",
+      "DC" => "DSUFFIX",
+    }
+
     def default_variables(env)
       {
         'OBJSUFFIX' => '.o',
 
-        'AS' => '$CC',
+        'AS' => '${CC}',
         'ASFLAGS' => [],
         'ASSUFFIX' => '.S',
-        'ASPPPATH' => '$CPPPATH',
+        'ASPPPATH' => '${CPPPATH}',
-        'ASPPFLAGS' => '$CPPFLAGS',
+        'ASPPFLAGS' => '${CPPFLAGS}',
-        'ASDEPGEN' => ['-MMD', '-MF', '$_DEPFILE'],
+        'ASDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
-        'ASCOM' => ['$AS', '-c', '-o', '$_TARGET', '$ASDEPGEN', '-I$[ASPPPATH]', '$ASPPFLAGS', '$ASFLAGS', '$_SOURCES'],
+        'ASCMD' => ['${AS}', '-c', '-o', '${_TARGET}', '${ASDEPGEN}', '-I${ASPPPATH}', '${ASPPFLAGS}', '${ASFLAGS}', '${_SOURCES}'],
 
         'CPPFLAGS' => [],
         'CPPPATH' => [],
@@ -20,22 +27,27 @@ module Rscons
         'CC' => 'gcc',
         'CFLAGS' => [],
         'CSUFFIX' => '.c',
-        'CCDEPGEN' => ['-MMD', '-MF', '$_DEPFILE'],
+        'CCDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
-        'CCCOM' => ['$CC', '-c', '-o', '$_TARGET', '$CCDEPGEN', '-I$[CPPPATH]', '$CPPFLAGS', '$CFLAGS', '$_SOURCES'],
+        'CCCMD' => ['${CC}', '-c', '-o', '${_TARGET}', '${CCDEPGEN}', '-I${CPPPATH}', '${CPPFLAGS}', '${CFLAGS}', '${_SOURCES}'],
 
         'CXX' => 'g++',
         'CXXFLAGS' => [],
         'CXXSUFFIX' => '.cc',
-        'CXXDEPGEN' => ['-MMD', '-MF', '$_DEPFILE'],
+        'CXXDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
-        'CXXCOM' =>['$CXX', '-c', '-o', '$_TARGET', '$CXXDEPGEN', '-I$[CPPPATH]', '$CPPFLAGS', '$CXXFLAGS', '$_SOURCES'],
+        'CXXCMD' =>['${CXX}', '-c', '-o', '${_TARGET}', '${CXXDEPGEN}', '-I${CPPPATH}', '${CPPFLAGS}', '${CXXFLAGS}', '${_SOURCES}'],
+
+        'DC' => 'gdc',
+        'DFLAGS' => [],
+        'DSUFFIX' => '.d',
+        'D_IMPORT_PATH' => [],
+        'DCCMD' => ['${DC}', '-c', '-o', '${_TARGET}', '-I${D_IMPORT_PATH}', '${DFLAGS}', '${_SOURCES}'],
       }
     end
 
     def produces?(target, source, env)
-      target.has_suffix?(env['OBJSUFFIX']) and (
+      target.has_suffix?(env['OBJSUFFIX']) and KNOWN_SUFFIXES.find do |compiler, suffix_var|
-        source.has_suffix?(env['ASSUFFIX']) or
+        source.has_suffix?(env[suffix_var])
-        source.has_suffix?(env['CSUFFIX']) or
+      end
-        source.has_suffix?(env['CXXSUFFIX']))
     end
 
     def run(target, sources, cache, env, vars = {})
@@ -44,23 +56,19 @@ module Rscons
         '_SOURCES' => sources,
         '_DEPFILE' => target.set_suffix('.mf'),
       })
-      com_prefix = if sources.first.has_suffix?(env['ASSUFFIX'])
+      com_prefix = KNOWN_SUFFIXES.find do |compiler, suffix_var|
-                     'AS'
+        sources.first.has_suffix?(env[suffix_var])
-                   elsif sources.first.has_suffix?(env['CSUFFIX'])
+      end.tap do |v|
-                     'CC'
+        v.nil? and raise "Error: unknown input file type: #{sources.first.inspect}"
-                   elsif sources.first.has_suffix?(env['CXXSUFFIX'])
+      end.first
-                     'CXX'
+      command = env.build_command(env["#{com_prefix}CMD"], vars)
-                   else
-                     raise "Error: unknown input file type: #{sources.first.inspect}"
-                   end
-      command = env.build_command(env["#{com_prefix}COM"], vars)
       unless cache.up_to_date?(target, command, sources)
         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 += env.parse_makefile_deps(vars['_DEPFILE'], target)
+          deps += Environment.parse_makefile_deps(vars['_DEPFILE'], target)
           FileUtils.rm_f(vars['_DEPFILE'])
         end
         cache.register_build(target, command, deps.uniq)

lib/rscons/builders/program.rb

@@ -10,26 +10,29 @@ module Rscons
         'LDFLAGS' => [],
         'LIBPATH' => [],
         'LIBS' => [],
-        'LDCOM' => ['$LD', '-o', '$_TARGET', '$LDFLAGS', '$_SOURCES', '-L$[LIBPATH]', '-l$[LIBS]']
+        'LDCMD' => ['${LD}', '-o', '${_TARGET}', '${LDFLAGS}', '${_SOURCES}', '-L${LIBPATH}', '-l${LIBS}']
       }
     end
 
     def run(target, sources, cache, env, vars = {})
       # build sources to linkable objects
       objects = env.build_sources(sources, [env['OBJSUFFIX'], env['LIBSUFFIX']].flatten, cache, vars)
-      if objects
+      ld = if env["LD"]
-        use_cxx = sources.map do |s|
+             env["LD"]
-          s.has_suffix?(env['CXXSUFFIX'])
+           elsif sources.find {|s| s.has_suffix?(env["DSUFFIX"])}
-        end.any?
+             env["DC"]
-        ld_alt = use_cxx ? env['CXX'] : env['CC']
+           elsif sources.find {|s| s.has_suffix?(env["CXXSUFFIX"])}
+             env["CXX"]
+           else
+             env["CC"]
+           end
       vars = vars.merge({
         '_TARGET' => target,
         '_SOURCES' => objects,
-          'LD' => env['LD'] || ld_alt,
+        'LD' => ld,
       })
-        command = env.build_command(env['LDCOM'], vars)
+      command = env.build_command(env['LDCMD'], vars)
       standard_build("LD #{target}", target, command, objects, env, cache)
     end
   end
-  end
 end

lib/rscons/cache.rb

@@ -67,12 +67,12 @@ module Rscons
       end
       @cache[:targets] ||= {}
       @cache[:directories] ||= {}
-      @cache[:version] ||= VERSION
       @lookup_checksums = {}
     end
 
     # Write the cache to disk to be loaded next time.
     def write
+      @cache[:version] = VERSION
       File.open(CACHE_FILE, 'w') do |fh|
         fh.puts(YAML.dump(@cache))
       end
@@ -119,9 +119,11 @@ module Rscons
       end
 
       # all cached dependencies must have their checksums match
-      @cache[:targets][target][:deps].map do |dep_cache|
+      @cache[:targets][target][:deps].each do |dep_cache|
-        dep_cache[:checksum] == lookup_checksum(dep_cache[:fname])
+        return false unless dep_cache[:checksum] == lookup_checksum(dep_cache[:fname])
-      end.all?
+      end
+
+      true
     end
 
     # Store cache information about a target built by a builder
@@ -150,16 +152,14 @@ module Rscons
     # removal upon a "clean" operation.
     def mkdir_p(path)
       parts = path.split(/[\\\/]/)
-      (0..parts.size).each do |i|
+      (0..parts.size-1).each do |i|
         subpath = File.join(*parts[0, i + 1]).encode(__ENCODING__)
         unless File.exists?(subpath)
           FileUtils.mkdir(subpath)
-          unless @cache[:directories].include?(subpath)
           @cache[:directories][subpath] = true
         end
       end
     end
-    end
 
     # Return a list of directories which were created as a part of the build
     def directories
@@ -179,7 +179,7 @@ module Rscons
     # Calculate and return a file's checksum
     # @param file [String] The file name.
     def calculate_checksum(file)
-      @lookup_checksums[file] = Digest::MD5.hexdigest(File.read(file, {mode: 'rb'})).encode(__ENCODING__) rescue ''
+      @lookup_checksums[file] = Digest::MD5.hexdigest(File.read(file, mode: 'rb')).encode(__ENCODING__) rescue ''
     end
   end
 end

lib/rscons/environment.rb

@@ -6,9 +6,12 @@ module Rscons
   # contains a collection of construction variables, options, builders, and
   # rules for building targets.
   class Environment
-    # [Hash] of {"builder_name" => builder_object} pairs.
+    # Hash of +{"builder_name" => builder_object}+ pairs.
     attr_reader :builders
 
+    # String or +nil+
+    attr_accessor :build_root
+
     # Create an Environment object.
     # @param variables [Hash]
     #   The variables hash can contain construction variables, which are
@@ -22,7 +25,7 @@ module Rscons
       @targets = {}
       @builders = {}
       @build_dirs = []
-      @tweakers = []
+      @build_hooks = []
       @varset[:exclude_builders] ||= []
       unless @varset[:exclude_builders] == :all
         exclude_builders = Set.new(@varset[:exclude_builders] || [])
@@ -32,10 +35,7 @@ module Rscons
           end
         end
       end
-      (@varset[:builders] || []).each do |builder|
+      @varset[:echo] ||= :short
-        add_builder(builder)
-      end
-      @varset[:echo] ||= :command
 
       if block_given?
         yield self
@@ -45,10 +45,10 @@ module Rscons
 
     # 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
+    # construction variables, and builders. It will not contain a copy of the
-    # contain a copy of the targets or tweakers.
+    # targets, build hooks, build directories, or the build root.  If a block
-    # If a block is given, the Environment object is yielded to the block and
+    # is given, the Environment object is yielded to the block and when the
-    # when the block returns, the {#process} method is automatically called.
+    # block returns, the {#process} method is automatically called.
     def clone(variables = {})
       env = Environment.new()
       @builders.each do |builder_name, builder|
@@ -75,9 +75,9 @@ module Rscons
       end
     end
 
-    # Add a tweaker block to the Environment.
+    # Add a build hook to the Environment.
-    def add_tweaker(&block)
+    def add_build_hook(&block)
-      @tweakers << block
+      @build_hooks << block
     end
 
     # Specify a build directory for this Environment.
@@ -89,18 +89,21 @@ module Rscons
 
     # Return the file name to be built from source_fname with suffix suffix.
     # This method takes into account the Environment's build directories.
-    # It also creates any parent directories needed to be able to open and
-    # write to the output file.
     def get_build_fname(source_fname, suffix)
       build_fname = source_fname.set_suffix(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!(%r{^#{src_dir}/}, "#{obj_dir}/")
         end
-        build_fname.gsub!('\\', '/')
       end
+      if @build_root and not found_match
+        unless source_fname.start_with?('/') or source_fname =~ %r{^\w:[\\/]}
+          build_fname = "#{@build_root}/#{build_fname}"
+        end
+      end
+      build_fname.gsub!('\\', '/')
       build_fname
     end
 
@@ -122,41 +125,33 @@ module Rscons
       @varset.send(:append, *args)
     end
 
-    # Return a list of target file names
-    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.
     def process
       cache = Cache.new
-      targets_processed = Set.new
+      targets_processed = {}
       process_target = proc do |target|
-        if @targets[target][:source].map do |src|
+        targets_processed[target] ||= begin
-          targets_processed.include?(src) or not @targets.include?(src) or process_target.call(src)
+          @targets[target][:source].each do |src|
-        end.all?
+            if @targets.include?(src) and not targets_processed.include?(src)
-          run_builder(@targets[target][:builder],
+              process_target.call(src)
+            end
+          end
+          result = run_builder(@targets[target][:builder],
                                target,
                                @targets[target][:source],
                                cache,
                                @targets[target][:vars] || {})
-        else
+          unless result
-          false
-        end
-      end
-      @targets.each do |target, info|
-        next if targets_processed.include?(target)
-        unless process_target.call(target)
             cache.write
             raise BuildError.new("Failed to build #{target}")
           end
+          result
+        end
+      end
+      @targets.each do |target, info|
+        process_target.call(target)
       end
       cache.write
     end
@@ -177,7 +172,7 @@ module Rscons
     # @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 to pass to Kernel#system.
     def execute(short_desc, command, options = {})
       print_command = proc do
         puts command.map { |c| c =~ /\s/ ? "'#{c}'" : c }.join(' ')
@@ -214,30 +209,6 @@ module Rscons
       end
     end
 
-    # Parse dependencies for a given target from a Makefile.
-    # This method is used internally by RScons builders.
-    # @param mf_fname [String] File name of the Makefile to read.
-    # @param target [String] Name of the target to gather dependencies for.
-    def parse_makefile_deps(mf_fname, target)
-      deps = []
-      buildup = ''
-      File.read(mf_fname).each_line do |line|
-        if line =~ /^(.*)\\\s*$/
-          buildup += ' ' + $1
-        else
-          buildup += ' ' + line
-          if buildup =~ /^(.*): (.*)$/
-            mf_target, mf_deps = $1.strip, $2
-            if mf_target == target
-              deps += mf_deps.split(' ').map(&:strip)
-            end
-          end
-          buildup = ''
-        end
-      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.
@@ -275,16 +246,40 @@ module Rscons
     # Return the result of the builder's run() method.
     def run_builder(builder, target, sources, cache, vars)
       vars = @varset.merge(vars)
-      @tweakers.each do |tweaker_block|
+      @build_hooks.each do |build_hook_block|
         build_operation = {
           builder: builder,
           target: target,
           sources: sources,
           vars: vars,
         }
-        tweaker_block.call(build_operation)
+        build_hook_block.call(build_operation)
       end
       builder.run(target, sources, cache, self, vars)
     end
+
+    # Parse dependencies for a given target from a Makefile.
+    # This method is used internally by RScons builders.
+    # @param mf_fname [String] File name of the Makefile to read.
+    # @param target [String] Name of the target to gather dependencies for.
+    def self.parse_makefile_deps(mf_fname, target)
+      deps = []
+      buildup = ''
+      File.read(mf_fname).each_line do |line|
+        if line =~ /^(.*)\\\s*$/
+          buildup += ' ' + $1
+        else
+          buildup += ' ' + line
+          if buildup =~ /^(.*): (.*)$/
+            mf_target, mf_deps = $1.strip, $2
+            if mf_target == target
+              deps += mf_deps.split(' ').map(&:strip)
+            end
+          end
+          buildup = ''
+        end
+      end
+      deps
+    end
   end
 end

lib/rscons/varset.rb

@@ -64,20 +64,16 @@ module Rscons
           expand_varref(ent)
         end.flatten
       else
-        if varref =~ /^(.*)\$\[(\w+)\](.*)$/
+        if varref =~ /^(.*)\$\{([^}]+)\}(.*)$/
-          # expand array with given prefix, suffix
           prefix, varname, suffix = $1, $2, $3
           varval = expand_varref(@vars[varname])
-          unless varval.is_a?(Array)
+          if varval.is_a?(String)
-            raise "Array expected for $#{varname}"
+            expand_varref("#{prefix}#{varval}#{suffix}")
+          elsif varval.is_a?(Array)
+            varval.map {|vv| expand_varref("#{prefix}#{vv}#{suffix}")}.flatten
+          else
+            raise "I do not know how to expand a variable reference to a #{varval.class.name}"
           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

lib/rscons/version.rb

@@ -1,4 +1,4 @@
 module Rscons
   # gem version
-  VERSION = "0.0.13"
+  VERSION = "0.2.0"
 end

spec/build_tests_spec.rb

@@ -1,45 +1,31 @@
 require 'fileutils'
 
 describe Rscons do
+  BUILD_TEST_RUN_DIR = "build_test_run"
+
   before(:all) do
-    FileUtils.rm_rf('build_tests_run')
+    FileUtils.rm_rf(BUILD_TEST_RUN_DIR)
     @owd = Dir.pwd
   end
 
+  before(:each) do
+    @output = ""
+    $stdout.stub(:write) do |content|
+      @output += content
+    end
+    $stderr.stub(:write) do |content|
+      @output += content
+    end
+  end
+
   after(:each) do
     Dir.chdir(@owd)
-    FileUtils.rm_rf('build_tests_run')
+    FileUtils.rm_rf(BUILD_TEST_RUN_DIR)
   end
 
-  def build_testdir(build_script = "build.rb")
+  def test_dir(build_test_directory)
-    if File.exists?(build_script)
+    FileUtils.cp_r("build_tests/#{build_test_directory}", BUILD_TEST_RUN_DIR)
-      build_rb = File.read(build_script)
+    Dir.chdir(BUILD_TEST_RUN_DIR)
-      File.open(build_script, "w") do |fh|
-        fh.puts(<<EOF + build_rb)
-require "simplecov"
-
-SimpleCov.start do
-  root("#{@owd}")
-  command_name("build_test_#{@build_test_name}")
-  add_filter("spec")
-end
-
-require "rscons"
-EOF
-      end
-      IO.popen(%{ruby -I #{@owd}/lib #{build_script}}) do |io|
-        io.readlines.reject do |line|
-          line =~ /^Coverage report/
-        end
-      end.map(&:strip)
-    end
-  end
-
-  def test_dir(build_test_directory, build_script = "build.rb")
-    @build_test_name = build_test_directory
-    FileUtils.cp_r("build_tests/#{build_test_directory}", 'build_tests_run')
-    Dir.chdir("build_tests_run")
-    build_testdir(build_script)
   end
 
   def file_sub(fname)
@@ -53,18 +39,31 @@ EOF
     end
   end
 
+  def lines
+    @output.lines.map(&:rstrip).tap do |v|
+      @output = ""
+    end
+  end
+
   ###########################################################################
   # Tests
   ###########################################################################
 
   it 'builds a C program with one source file' do
     test_dir('simple')
+    Rscons::Environment.new do |env|
+      env.Program('simple', Dir['*.c'])
+    end
     File.exists?('simple.o').should be_true
     `./simple`.should == "This is a simple C program\n"
   end
 
   it 'prints commands as they are executed' do
-    lines = test_dir('simple')
+    test_dir('simple')
+    Rscons::Environment.new(echo: :command) do |env|
+      env["LD"] = "gcc"
+      env.Program('simple', Dir['*.c'])
+    end
     lines.should == [
       'gcc -c -o simple.o -MMD -MF simple.mf simple.c',
       'gcc -o simple simple.o',
@@ -72,7 +71,10 @@ EOF
   end
 
   it 'prints short representations of the commands being executed' do
-    lines = test_dir('header')
+    test_dir('header')
+    Rscons::Environment.new do |env|
+      env.Program('header', Dir['*.c'])
+    end
     lines.should == [
       'CC header.o',
       'LD header',
@@ -81,61 +83,110 @@ EOF
 
   it 'builds a C program with one source file and one header file' do
     test_dir('header')
+    Rscons::Environment.new do |env|
+      env.Program('header', Dir['*.c'])
+    end
     File.exists?('header.o').should be_true
     `./header`.should == "The value is 2\n"
   end
 
   it 'rebuilds a C module when a header it depends on changes' do
     test_dir('header')
+    env = Rscons::Environment.new do |env|
+      env.Program('header', Dir['*.c'])
+    end
     `./header`.should == "The value is 2\n"
     file_sub('header.h') {|line| line.sub(/2/, '5')}
-    build_testdir
+    env.process
     `./header`.should == "The value is 5\n"
   end
 
   it 'does not rebuild a C module when its dependencies have not changed' do
-    lines = test_dir('header')
+    test_dir('header')
+    env = Rscons::Environment.new do |env|
+      env.Program('header', Dir['*.c'])
+    end
     `./header`.should == "The value is 2\n"
     lines.should == [
       'CC header.o',
       'LD header',
     ]
-    lines = build_testdir
+    env.process
     lines.should == []
   end
 
   it "does not rebuild a C module when only the file's timestampe has changed" do
-    lines = test_dir('header')
+    test_dir('header')
+    env = Rscons::Environment.new do |env|
+      env.Program('header', Dir['*.c'])
+    end
     `./header`.should == "The value is 2\n"
     lines.should == [
       'CC header.o',
       'LD header',
     ]
     file_sub('header.c') {|line| line}
-    lines = build_testdir
+    env.process
     lines.should == []
   end
 
   it 're-links a program when the link flags have changed' do
-    lines = test_dir('simple')
+    test_dir('simple')
+    Rscons::Environment.new(echo: :command) do |env|
+      env.Program('simple', Dir['*.c'])
+    end
     lines.should == [
       'gcc -c -o simple.o -MMD -MF simple.mf simple.c',
       'gcc -o simple simple.o',
     ]
-    file_sub('build.rb') {|line| line.sub(/.*CHANGE.FLAGS.*/, '  env["LIBS"] += ["c"]')}
+    Rscons::Environment.new(echo: :command) do |env|
-    lines = build_testdir
+      env["LIBS"] += ["c"]
+      env.Program('simple', Dir['*.c'])
+    end
     lines.should == ['gcc -o simple simple.o -lc']
   end
 
   it 'builds object files in a different build directory' do
-    lines = test_dir('build_dir')
+    test_dir('build_dir')
+    Rscons::Environment.new do |env|
+      env.append('CPPPATH' => Dir['src/**/*/'])
+      env.build_dir(%r{^src/([^/]+)/}, 'build_\\1/')
+      env.Program('build_dir', Dir['src/**/*.c'])
+    end
     `./build_dir`.should == "Hello from two()\n"
     File.exists?('build_one/one.o').should be_true
     File.exists?('build_two/two.o').should be_true
   end
 
+  it 'uses build directories before build root' do
+    test_dir('build_dir')
+    Rscons::Environment.new do |env|
+      env.append('CPPPATH' => Dir['src/**/*/'])
+      env.build_dir("src", "build")
+      env.build_root = "build_root"
+      env.Program('build_dir', Dir['src/**/*.c'])
+    end
+    lines.should == ["CC build/one/one.o", "CC build/two/two.o", "LD build_dir"]
+  end
+
+  it 'uses build_root if no build directories match' do
+    test_dir('build_dir')
+    Rscons::Environment.new do |env|
+      env.append('CPPPATH' => Dir['src/**/*/'])
+      env.build_dir("src2", "build")
+      env.build_root = "build_root"
+      env.Program('build_dir', Dir['src/**/*.c'])
+    end
+    lines.should == ["CC build_root/src/one/one.o", "CC build_root/src/two/two.o", "LD build_dir"]
+  end
+
   it 'cleans built files' do
-    lines = test_dir('build_dir')
+    test_dir('build_dir')
+    Rscons::Environment.new do |env|
+      env.append('CPPPATH' => Dir['src/**/*/'])
+      env.build_dir(%r{^src/([^/]+)/}, 'build_\\1/')
+      env.Program('build_dir', Dir['src/**/*.c'])
+    end
     `./build_dir`.should == "Hello from two()\n"
     File.exists?('build_one/one.o').should be_true
     File.exists?('build_two/two.o').should be_true
@@ -148,7 +199,12 @@ EOF
   end
 
   it 'does not clean created directories if other non-rscons-generated files reside there' do
-    lines = test_dir('build_dir')
+    test_dir('build_dir')
+    Rscons::Environment.new do |env|
+      env.append('CPPPATH' => Dir['src/**/*/'])
+      env.build_dir(%r{^src/([^/]+)/}, 'build_\\1/')
+      env.Program('build_dir', Dir['src/**/*.c'])
+    end
     `./build_dir`.should == "Hello from two()\n"
     File.exists?('build_one/one.o').should be_true
     File.exists?('build_two/two.o').should be_true
@@ -162,14 +218,44 @@ EOF
   end
 
   it 'allows Ruby classes as custom builders to be used to construct files' do
-    lines = test_dir('custom_builder')
+   test_dir('custom_builder')
+    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 do |env|
+      env.add_builder(MySource.new)
+      env.MySource('inc.h', [])
+      env.Program('program', Dir['*.c'])
+    end
+
     lines.should == ['CC program.o', 'LD program']
     File.exists?('inc.h').should be_true
     `./program`.should == "The value is 5678\n"
   end
 
   it 'allows cloning Environment objects' do
-    lines = test_dir('clone_env')
+    test_dir('clone_env')
+
+    debug = Rscons::Environment.new(echo: :command) 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
+
     lines.should == [
       %q{gcc -c -o debug/program.o -MMD -MF debug/program.mf '-DSTRING="Debug Version"' -O2 src/program.c},
       %q{gcc -o program-debug debug/program.o},
@@ -180,12 +266,19 @@ EOF
 
   it 'builds a C++ program with one source file' do
     test_dir('simple_cc')
+    Rscons::Environment.new do |env|
+      env.Program('simple', Dir['*.cc'])
+    end
     File.exists?('simple.o').should be_true
     `./simple`.should == "This is a simple C++ program\n"
   end
 
   it 'allows overriding construction variables for individual builder calls' do
-    lines = test_dir('two_sources')
+    test_dir('two_sources')
+    Rscons::Environment.new(echo: :command) do |env|
+      env.Object("one.o", "one.c", 'CPPFLAGS' => ['-DONE'])
+      env.Program('two_sources', ['one.o', 'two.c'])
+    end
     lines.should == [
       'gcc -c -o one.o -MMD -MF one.mf -DONE one.c',
       'gcc -c -o two.o -MMD -MF two.mf two.c',
@@ -196,7 +289,11 @@ EOF
   end
 
   it 'builds a static library archive' do
-    lines = test_dir('library')
+    test_dir('library')
+    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
     lines.should == [
       'gcc -c -o one.o -MMD -MF one.mf -Dmake_lib one.c',
       'gcc -c -o two.o -MMD -MF two.mf -Dmake_lib two.c',
@@ -208,13 +305,39 @@ EOF
     `ar t lib.a`.should == "one.o\ntwo.o\n"
   end
 
-  it 'supports tweakers to override construction variables' do
+  it 'supports build hooks to override construction variables' do
-    lines = test_dir("build_dir", "tweaker_build.rb")
+    test_dir("build_dir")
-    `./tweaker`.should == "Hello from two()\n"
+    Rscons::Environment.new(echo: :command) do |env|
+      env.append('CPPPATH' => Dir['src/**/*/'])
+      env.build_dir(%r{^src/([^/]+)/}, 'build_\\1/')
+      env.add_build_hook do |build_op|
+        if build_op[:target] =~ %r{build_one/.*\.o}
+          build_op[:vars]["CFLAGS"] << "-O1"
+        elsif build_op[:target] =~ %r{build_two/.*\.o}
+          build_op[:vars]["CFLAGS"] << "-O2"
+        end
+      end
+      env.Program('build_hook', Dir['src/**/*.c'])
+    end
+    `./build_hook`.should == "Hello from two()\n"
     lines.should =~ [
       'gcc -c -o build_one/one.o -MMD -MF build_one/one.mf -Isrc/one/ -Isrc/two/ -O1 src/one/one.c',
       'gcc -c -o build_two/two.o -MMD -MF build_two/two.mf -Isrc/one/ -Isrc/two/ -O2 src/two/two.c',
-      'gcc -o tweaker build_one/one.o build_two/two.o',
+      'gcc -o build_hook build_one/one.o build_two/two.o',
     ]
   end
+
+  unless ENV["omit_gdc_tests"]
+    it "supports building D sources" do
+      test_dir("d")
+      Rscons::Environment.new(echo: :command) do |env|
+        env.Program("hello-d", Dir["*.d"])
+      end
+      lines.should == [
+        "gdc -c -o main.o main.d",
+        "gdc -o hello-d main.o",
+      ]
+      `./hello-d`.rstrip.should == "Hello from D!"
+    end
+  end
 end

spec/rscons/cache_spec.rb

@@ -0,0 +1,204 @@
+module Rscons
+  describe Cache do
+    before do
+      File.stub(:read) { nil }
+    end
+
+    def build_from(cache)
+      YAML.should_receive(:load).and_return(cache)
+      Cache.new
+    end
+
+    describe ".clear" do
+      it "removes the cache file" do
+        FileUtils.should_receive(:rm_f).with(Cache::CACHE_FILE)
+        Cache.clear
+      end
+    end
+
+    describe "#initialize" do
+      context "when corrupt" do
+        it "prints a warning and defaults to an empty hash" do
+          YAML.should_receive(:load).and_return("string")
+          $stderr.should_receive(:puts).with(/Warning:.*was.corrupt/)
+          Cache.new.instance_variable_get(:@cache).is_a?(Hash).should be_true
+        end
+      end
+    end
+
+    describe "#write" do
+      it "should fill in :version and write to file" do
+        cache = {}
+        fh = $stdout
+        fh.should_receive(:puts)
+        File.should_receive(:open).and_yield(fh)
+        build_from(cache).write
+        cache[:version].should == Rscons::VERSION
+      end
+    end
+
+    describe "#up_to_date?" do
+      it "returns false when target file does not exist" do
+        File.should_receive(:exists?).with("target").and_return(false)
+        build_from({}).up_to_date?("target", "command", []).should be_false
+      end
+
+      it "returns false when target is not registered in the cache" do
+        File.should_receive(:exists?).with("target").and_return(true)
+        build_from({}).up_to_date?("target", "command", []).should be_false
+      end
+
+      it "returns false when the target's checksum does not match" do
+        _cache = {targets: {"target" => {checksum: "abc"}}}
+        cache = build_from(_cache)
+        File.should_receive(:exists?).with("target").and_return(true)
+        cache.should_receive(:calculate_checksum).with("target").and_return("def")
+        cache.up_to_date?("target", "command", []).should be_false
+      end
+
+      it "returns false when the build command has changed" do
+        _cache = {targets: {"target" => {checksum: "abc", command: "old command"}}}
+        cache = build_from(_cache)
+        File.should_receive(:exists?).with("target").and_return(true)
+        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
+        cache.up_to_date?("target", "command", []).should be_false
+      end
+
+      it "returns false when there is a new dependency" do
+        _cache = {targets: {"target" => {checksum: "abc",
+                                         command: "command",
+                                         deps: [{fname: "dep.1"}]}}}
+        cache = build_from(_cache)
+        File.should_receive(:exists?).with("target").and_return(true)
+        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"]).should be_false
+      end
+
+      it "returns false when a dependency's checksum has changed" do
+        _cache = {targets: {"target" => {checksum: "abc",
+                                         command: "command",
+                                         deps: [{fname: "dep.1",
+                                                 checksum: "dep.1.chk"},
+                                                {fname: "dep.2",
+                                                 checksum: "dep.2.chk"},
+                                                {fname: "extra.dep",
+                                                 checksum: "extra.dep.chk"}]}}}
+        cache = build_from(_cache)
+        File.should_receive(:exists?).with("target").and_return(true)
+        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
+        cache.should_receive(:calculate_checksum).with("dep.1").and_return("dep.1.chk")
+        cache.should_receive(:calculate_checksum).with("dep.2").and_return("dep.2.changed")
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"]).should be_false
+      end
+
+      it "returns false with strict_deps=true when cache has an extra dependency" do
+        _cache = {targets: {"target" => {checksum: "abc",
+                                         command: "command",
+                                         deps: [{fname: "dep.1",
+                                                 checksum: "dep.1.chk"},
+                                                {fname: "dep.2",
+                                                 checksum: "dep.2.chk"},
+                                                {fname: "extra.dep",
+                                                 checksum: "extra.dep.chk"}]}}}
+        cache = build_from(_cache)
+        File.should_receive(:exists?).with("target").and_return(true)
+        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"], strict_deps: true).should be_false
+      end
+
+      it "returns true when no condition for false is met" do
+        _cache = {targets: {"target" => {checksum: "abc",
+                                         command: "command",
+                                         deps: [{fname: "dep.1",
+                                                 checksum: "dep.1.chk"},
+                                                {fname: "dep.2",
+                                                 checksum: "dep.2.chk"},
+                                                {fname: "extra.dep",
+                                                 checksum: "extra.dep.chk"}]}}}
+        cache = build_from(_cache)
+        File.should_receive(:exists?).with("target").and_return(true)
+        cache.should_receive(:calculate_checksum).with("target").and_return("abc")
+        cache.should_receive(:calculate_checksum).with("dep.1").and_return("dep.1.chk")
+        cache.should_receive(:calculate_checksum).with("dep.2").and_return("dep.2.chk")
+        cache.should_receive(:calculate_checksum).with("extra.dep").and_return("extra.dep.chk")
+        cache.up_to_date?("target", "command", ["dep.1", "dep.2"]).should be_true
+      end
+    end
+
+    describe "#register_build" do
+      it "stores the given information in the cache" do
+        _cache = {}
+        cache = build_from(_cache)
+        cache.should_receive(:calculate_checksum).with("the target").and_return("the checksum")
+        cache.should_receive(:calculate_checksum).with("dep 1").and_return("dep 1 checksum")
+        cache.should_receive(:calculate_checksum).with("dep 2").and_return("dep 2 checksum")
+        cache.register_build("the target", "the command", ["dep 1", "dep 2"])
+        cached_target = cache.instance_variable_get(:@cache)[:targets]["the target"]
+        cached_target.should_not be_nil
+        cached_target[:command].should == "the command"
+        cached_target[:checksum].should == "the checksum"
+        cached_target[:deps].should == [
+          {fname: "dep 1", checksum: "dep 1 checksum"},
+          {fname: "dep 2", checksum: "dep 2 checksum"},
+        ]
+      end
+    end
+
+    describe "#targets" do
+      it "returns a list of targets that are cached" do
+        cache = {targets: {"t1" => {}, "t2" => {}, "t3" => {}}}
+        build_from(cache).targets.should == ["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)
+        File.should_receive(:exists?).with("one").and_return(true)
+        File.should_receive(:exists?).with("one/two").and_return(false)
+        FileUtils.should_receive(:mkdir).with("one/two")
+        File.should_receive(:exists?).with("one/two/three").and_return(false)
+        FileUtils.should_receive(:mkdir).with("one/two/three")
+        File.should_receive(:exists?).with("one").and_return(true)
+        File.should_receive(:exists?).with("one/two").and_return(true)
+        File.should_receive(:exists?).with("one/two/four").and_return(false)
+        FileUtils.should_receive(:mkdir).with("one/two/four")
+        cache.mkdir_p("one/two/three")
+        cache.mkdir_p("one\\two\\four")
+        cache.directories.should == ["one/two", "one/two/three", "one/two/four"]
+      end
+    end
+
+    describe "#directories" do
+      it "returns a list of directories that are cached" do
+        _cache = {directories: {"dir1" => true, "dir2" => true}}
+        build_from(_cache).directories.should == ["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"})
+        cache.should_not_receive(:calculate_checksum)
+        cache.send(:lookup_checksum, "f1").should == "f1.chk"
+      end
+
+      it "calls calculate_checksum when the checksum is not cached" do
+        cache = build_from({})
+        cache.should_receive(:calculate_checksum).with("f1").and_return("ck")
+        cache.send(:lookup_checksum, "f1").should == "ck"
+      end
+    end
+
+    describe "#calculate_checksum" do
+      it "calculates the MD5 of the file contents" do
+        contents = "contents"
+        File.should_receive(:read).with("fname", mode: "rb").and_return(contents)
+        Digest::MD5.should_receive(:hexdigest).with(contents).and_return("the_checksum")
+        build_from({}).send(:calculate_checksum, "fname").should == "the_checksum"
+      end
+    end
+  end
+end

spec/rscons/environment_spec.rb

@@ -1,6 +1,44 @@
 module Rscons
   describe Environment do
-    describe '.clone' do
+    describe "#initialize" do
+      it "stores the construction variables passed in" do
+        env = Environment.new("CFLAGS" => ["-g"], "CPPPATH" => ["dir"])
+        env["CFLAGS"].should == ["-g"]
+        env["CPPPATH"].should == ["dir"]
+      end
+
+      it "adds the default builders when they are not excluded" do
+        env = Environment.new
+        env.builders.size.should be > 0
+        env.builders.map {|name, builder| builder.is_a?(Builder)}.all?.should be_true
+        env.builders.find {|name, builder| name == "Object"}.should_not be_nil
+        env.builders.find {|name, builder| name == "Program"}.should_not be_nil
+        env.builders.find {|name, builder| name == "Library"}.should_not be_nil
+      end
+
+      it "excludes the default builders with exclude_builders: :all" do
+        env = Environment.new(exclude_builders: :all)
+        env.builders.size.should == 0
+      end
+
+      it "excludes the named builders" do
+        env = Environment.new(exclude_builders: ["Library"])
+        env.builders.size.should be > 0
+        env.builders.find {|name, builder| name == "Object"}.should_not be_nil
+        env.builders.find {|name, builder| name == "Program"}.should_not be_nil
+        env.builders.find {|name, builder| name == "Library"}.should be_nil
+      end
+
+      context "when a block is given" do
+        it "yields self and invokes #process()" do
+          env = Environment.new do |env|
+            env.should_receive(:process)
+          end
+        end
+      end
+    end
+
+    describe "#clone" do
       it 'should create unique copies of each construction variable' do
         env = Environment.new
         env["CPPPATH"] << "path1"
@@ -9,15 +47,229 @@ module Rscons
         env["CPPPATH"].should == ["path1"]
         env2["CPPPATH"].should == ["path1", "path2"]
       end
+
+      context "when a block is given" do
+        it "yields self and invokes #process()" do
+          env = Environment.new
+          env.clone do |env2|
+            env2.should_receive(:process)
+          end
+        end
+      end
     end
 
-    describe '.parse_makefile_deps' do
+    describe "#add_builder" do
+      it "adds the builder to the list of builders" do
+        env = Environment.new(exclude_builders: :all)
+        env.builders.keys.should == []
+        env.add_builder(Rscons::Object.new)
+        env.builders.keys.should == ["Object"]
+      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
+          env.get_build_fname("src/dir/file.c", ".o").should == "src/dir/file.o"
+          env.get_build_fname("src\\dir\\other.d", ".a").should == "src/dir/other.a"
+          env.get_build_fname("source.cc", ".o").should == "source.o"
+        end
+      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')
+          env.get_build_fname("src/input.cc", ".o").should == "bld/input.o"
+          env.get_build_fname("libs/lib1/some/file.c", ".o").should == "build/libs/lib1/some/file.o"
+          env.get_build_fname("libs/otherlib/otherlib.cc", ".o").should == "build/libs/otherlib/otherlib.o"
+          env.get_build_fname("other_directory/o.d", ".a").should == "other_directory/o.a"
+        end
+      end
+    end
+
+    describe "#[]" do
+      it "allows reading construction variables" do
+        env = Environment.new("CFLAGS" => ["-g", "-Wall"])
+        env["CFLAGS"].should == ["-g", "-Wall"]
+      end
+    end
+
+    describe "#[]=" do
+      it "allows writing construction variables" do
+        env = Environment.new("CFLAGS" => ["-g", "-Wall"])
+        env["CFLAGS"] -= ["-g"]
+        env["CFLAGS"] += ["-O3"]
+        env["CFLAGS"].should == ["-Wall", "-O3"]
+        env["other_var"] = "val33"
+        env["other_var"].should == "val33"
+      end
+    end
+
+    describe "#append" do
+      it "allows adding many construction variables at once" do
+        env = Environment.new("CFLAGS" => ["-g"], "CPPPATH" => ["inc"])
+        env.append("CFLAGS" => ["-Wall"], "CPPPATH" => ["include"])
+        env["CFLAGS"].should == ["-Wall"]
+        env["CPPPATH"].should == ["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"
+        Cache.should_receive(:new).and_return(cache)
+        env.should_receive(:run_builder).with(anything, "a.out", ["main.c"], cache, {}).and_return(true)
+        cache.should_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"
+        Cache.should_receive(:new).and_return(cache)
+        env.should_receive(:run_builder).with(anything, "main.o", ["other.cc"], cache, {}).and_return("main.o")
+        env.should_receive(:run_builder).with(anything, "a.out", ["main.o"], cache, {}).and_return("a.out")
+        cache.should_receive(:write)
+
+        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"
+        Cache.should_receive(:new).and_return(cache)
+        env.should_receive(:run_builder).with(anything, "main.o", ["other.cc"], cache, {}).and_return(false)
+        cache.should_receive(:write)
+
+        expect { env.process }.to raise_error BuildError, /Failed.to.build.main.o/
+      end
+    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")
+        cmd.should == ["cmd", "-Idir1", "-Idir2", "-x", "-y", "-z", "infile", "outfile"]
+      end
+    end
+
+    describe "#execute" do
+      context "with echo: :short" do
+        context "with no errors" do
+          it "prints the short description and executes the command" do
+            env = Environment.new(echo: :short)
+            env.should_receive(:puts).with("short desc")
+            env.should_receive(:system).with("a", "command", {}).and_return(true)
+            env.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)
+            env.should_receive(:puts).with("short desc")
+            env.should_receive(:system).with("a", "command", {}).and_return(false)
+            $stdout.should_receive(:write).with("Failed command was: ")
+            env.should_receive(:puts).with("a command")
+            env.execute("short desc", ["a", "command"])
+          end
+        end
+      end
+
+      context "with echo: :command" do
+        it "prints the command executed and executes the command" do
+          env = Environment.new(echo: :command)
+          env.should_receive(:puts).with("a command '--arg=val with spaces'")
+          env.should_receive(:system).with("a", "command", "--arg=val with spaces", opt: :val).and_return(false)
+          env.execute("short desc", ["a", "command", "--arg=val with spaces"], opt: :val)
+        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
+        env.should_receive(:orig_method_missing).with(:foobar)
+        env.foobar
+      end
+
+      it "records the target when the target method is a known builder" do
+        env = Environment.new
+        env.instance_variable_get(:@targets).should == {}
+        env.Program("target", ["src1", "src2"], var: "val")
+        target = env.instance_variable_get(:@targets)["target"]
+        target.should_not be_nil
+        target[:builder].is_a?(Builder).should be_true
+        target[:source].should == ["src1", "src2"]
+        target[:vars].should == {var: "val"}
+        target[:args].should == []
+      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 "#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)
+        env.builders["Object"].should_receive(:run).with("mod.o", ["mod.c"], cache, env, anything).and_return("mod.o")
+        env.builders["ABuilder"].should_receive(:run).with("mod2.ab_out", ["mod2.ab_in"], cache, env, anything).and_return("mod2.ab_out")
+        env.build_sources(["precompiled.o", "mod.c", "mod2.ab_in"], [".o", ".ab_out"], cache, {}).should == ["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
+        env.builders["Object"].stub(:run) do |target, sources, cache, env, vars|
+          vars["CFLAGS"].should == []
+        end
+        env.run_builder(env.builders["Object"], "build/normal/module.o", ["src/normal/module.c"], "cache", {})
+        env.builders["Object"].stub(:run) do |target, sources, cache, env, vars|
+          vars["CFLAGS"].should == ["-O3", "-DSPECIAL"]
+        end
+        env.run_builder(env.builders["Object"], "build/special/module.o", ["src/special/module.c"], "cache", {})
+      end
+    end
+
+    describe ".parse_makefile_deps" do
       it 'handles dependencies on one line' do
         File.should_receive(:read).with('makefile').and_return(<<EOS)
 module.o: source.cc
 EOS
-        env = Environment.new
+        Environment.parse_makefile_deps('makefile', 'module.o').should == ['source.cc']
-        env.parse_makefile_deps('makefile', 'module.o').should == ['source.cc']
       end
 
       it 'handles dependencies split across many lines' do
@@ -26,8 +278,7 @@ module.o: module.c \\
   module.h \\
   other.h
 EOS
-        env = Environment.new
+        Environment.parse_makefile_deps('makefile', 'module.o').should == [
-        env.parse_makefile_deps('makefile', 'module.o').should == [
           'module.c', 'module.h', 'other.h']
       end
     end

spec/rscons/varset_spec.rb

@@ -84,30 +84,35 @@ module Rscons
       v = VarSet.new("CFLAGS" => ["-Wall", "-O2"],
                      "CC" => "gcc",
                      "CPPPATH" => ["dir1", "dir2"],
-                     "compiler" => "$CC",
+                     "compiler" => "${CC}",
-                     "cmd" => ["$CC", "-c", "$CFLAGS", "-I$[CPPPATH]"])
+                     "cmd" => ["${CC}", "-c", "${CFLAGS}", "-I${CPPPATH}"])
       it "expands to the string itself if the string is not a variable reference" do
         v.expand_varref("CC").should == "CC"
         v.expand_varref("CPPPATH").should == "CPPPATH"
         v.expand_varref("str").should == "str"
       end
       it "expands a single variable reference beginning with a '$'" do
-        v.expand_varref("$CC").should == "gcc"
+        v.expand_varref("${CC}").should == "gcc"
-        v.expand_varref("$CPPPATH").should == ["dir1", "dir2"]
+        v.expand_varref("${CPPPATH}").should == ["dir1", "dir2"]
       end
-      it "expands a single variable reference in $[arr] notation" do
+      it "expands a single variable reference in ${arr} notation" do
-        v.expand_varref("prefix$[CFLAGS]suffix").should == ["prefix-Wallsuffix", "prefix-O2suffix"]
+        v.expand_varref("prefix${CFLAGS}suffix").should == ["prefix-Wallsuffix", "prefix-O2suffix"]
         v.expand_varref(v["cmd"]).should == ["gcc", "-c", "-Wall", "-O2", "-Idir1", "-Idir2"]
       end
       it "expands a variable reference recursively" do
-        v.expand_varref("$compiler").should == "gcc"
+        v.expand_varref("${compiler}").should == "gcc"
-        v.expand_varref("$cmd").should == ["gcc", "-c", "-Wall", "-O2", "-Idir1", "-Idir2"]
+        v.expand_varref("${cmd}").should == ["gcc", "-c", "-Wall", "-O2", "-Idir1", "-Idir2"]
       end
-      it "raises an error when array notation is applied to a non-array variable" do
+      it "resolves multiple variable references in one element by enumerating all combinations" do
-        expect { v.expand_varref("$[CC]") }.to raise_error /Array.expected/
+        v.expand_varref("cflag: ${CFLAGS}, cpppath: ${CPPPATH}, compiler: ${compiler}").should == [
+          "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 "raises an error when a variable reference refers to a non-existent variable" do
-        expect { v.expand_varref("$not_here") }.to raise_error /Could.not.find.variable..not_here/
+        expect { v.expand_varref("${not_here}") }.to raise_error /I do not know how to expand a variable reference to a NilClass/
       end
     end
   end

spec/rscons_spec.rb

@@ -0,0 +1,26 @@
+describe Rscons do
+  describe ".clean" do
+    it "removes all build targets and created directories" do
+      cache = "cache"
+      Rscons::Cache.should_receive(:new).and_return(cache)
+      cache.should_receive(:targets).and_return(["build/a.out", "build/main.o"])
+      FileUtils.should_receive(:rm_f).with("build/a.out")
+      FileUtils.should_receive(:rm_f).with("build/main.o")
+      cache.should_receive(:directories).and_return(["build/one", "build/one/two", "build", "other"])
+      File.should_receive(:directory?).with("build/one/two").and_return(true)
+      Dir.should_receive(:entries).with("build/one/two").and_return([".", ".."])
+      Dir.should_receive(:rmdir).with("build/one/two")
+      File.should_receive(:directory?).with("build/one").and_return(true)
+      Dir.should_receive(:entries).with("build/one").and_return([".", ".."])
+      Dir.should_receive(:rmdir).with("build/one")
+      File.should_receive(:directory?).with("build").and_return(true)
+      Dir.should_receive(:entries).with("build").and_return([".", ".."])
+      Dir.should_receive(:rmdir).with("build")
+      File.should_receive(:directory?).with("other").and_return(true)
+      Dir.should_receive(:entries).with("other").and_return([".", "..", "other.file"])
+      Rscons::Cache.should_receive(:clear)
+
+      Rscons.clean
+    end
+  end
+end

spec/spec_helper.rb

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