v1.16.0

CHANGELOG.md

@@ -1,5 +1,18 @@
 ## ChangeLog
 
+### v1.16.0
+
+#### New Features
+
+- Add `Rscons.glob`
+- Support command-line variables
+- improve debuggability of cache.up_to_date?
+- allow passing a VarSet into cache methods
+
+#### Fixes
+
+- generate dependencies for D builds
+
 ### v1.15.0
 
 - allow json 1.x or 2.x

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rscons (1.15.0)
+    rscons (1.16.0)
       json (>= 1.8, < 3.0)
 
 GEM
@@ -10,9 +10,8 @@ GEM
     diff-lcs (1.3)
     docile (1.1.5)
     json (2.1.0)
-    rake (12.0.0)
+    rake (12.3.1)
     rdoc (5.1.0)
-    redcarpet (3.4.0)
     rspec (3.6.0)
       rspec-core (~> 3.6.0)
       rspec-expectations (~> 3.6.0)
@@ -31,7 +30,7 @@ GEM
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
-    yard (0.9.9)
+    yard (0.9.12)
 
 PLATFORMS
   ruby
@@ -40,11 +39,10 @@ PLATFORMS
 DEPENDENCIES
   rake
   rdoc
-  redcarpet
   rscons!
   rspec
   simplecov
   yard
 
 BUNDLED WITH
-   1.15.4
+   1.16.2

README.md

@@ -1,7 +1,7 @@
 # Rscons
 
-Rscons is a software construction framework inspired by SCons and implemented
-in Ruby.
+Rscons (https://github.com/holtrop/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)
 
@@ -30,7 +30,7 @@ task block or split among multiple tasks.
 ```ruby
 Rscons::Environment.new do |env|
   env["CFLAGS"] << "-Wall"
-  env.Program("program", Dir["src/**/*.c"])
+  env.Program("program", Rscons.glob("src/**/*.c"))
 end
 ```
 
@@ -39,7 +39,7 @@ end
 ```ruby
 Rscons::Environment.new do |env|
   env["DFLAGS"] << "-Wall"
-  env.Program("program", Dir["src/**/*.d"])
+  env.Program("program", Rscons.glob("src/**/*.d"))
 end
 ```
 
@@ -51,7 +51,7 @@ main_env = Rscons::Environment.new do |env|
   env.build_dir("src", "build/main")
   env["CFLAGS"] = ["-DSOME_DEFINE", "-O3"]
   env["LIBS"] = ["SDL"]
-  env.Program("program", Dir["src/**/*.cc"])
+  env.Program("program", Rscons.glob("src/**/*.cc"))
 end
 
 debug_env = main_env.clone do |env|
@@ -59,7 +59,7 @@ debug_env = main_env.clone do |env|
   env.build_dir("src", "build/debug")
   env["CFLAGS"] -= ["-O3"]
   env["CFLAGS"] += ["-g", "-O0"]
-  env.Program("program-debug", Dir["src/**/*.cc"])
+  env.Program("program-debug", Rscons.glob("src/**/*.cc"))
 end
 ```
 
@@ -86,7 +86,7 @@ end
 Rscons::Environment.new do |env|
   env.add_builder(GenerateFoo.new)
   env.GenerateFoo("foo.h", [])
-  env.Program("a.out", Dir["*.c"])
+  env.Program("a.out", Rscons.glob("*.c"))
 end
 ```
 
@@ -111,6 +111,15 @@ Rscons::Environment.new do |env|
 end
 ```
 
+The `Cache#up_to_date?` method accepts an optional 5th parameter which is an
+options Hash. The `:debug` option can be specified in this Hash with a value
+of `true` to aid in debugging builders while developing them. For example:
+
+```ruby
+unless cache.up_to_date?(target, cmd, sources, env, debug: true)
+end
+```
+
 ### Example: Custom Builder That Generates Multiple Output Files
 
 ```ruby
@@ -191,7 +200,7 @@ Rscons::Environment.new do |env|
     end
   end
   env.build_dir("src", "build")
-  env.Program("program", Dir["**/*.cc"])
+  env.Program("program", Rscons.glob("**/*.cc"))
 end
 ```
 
@@ -199,7 +208,7 @@ end
 
 ```ruby
 Rscons::Environment.new do |env|
-  env.Library("mylib.a", Dir["src/**/*.c"])
+  env.Library("mylib.a", Rscons.glob("src/**/*.c"))
 end
 ```
 
@@ -327,7 +336,7 @@ env.Install("dist/share", "share")
 ```ruby
 env.Library(target, sources)
 # Example
-env.Library("lib.a", Dir["src/**/*.c"])
+env.Library("lib.a", Rscons.glob("src/**/*.c"))
 ```
 
 The Library builder creates a static library archive from the given source
@@ -362,7 +371,7 @@ preprocessed output to the target file.
 ```ruby
 env.Program(target, sources)
 # Example
-env.Program("myprog", Dir["src/**/*.cc"])
+env.Program("myprog", Rscons.glob("src/**/*.cc"))
 ```
 
 The Program builder compiles and links the given sources to an executable file.
@@ -375,7 +384,7 @@ This can be controlled with the `PROGSUFFIX` construction variable.
 ```ruby
 env.SharedLibrary(target, sources)
 # Example
-env.SharedLibrary("mydll", Dir["src/**/*.cc"])
+env.SharedLibrary("mydll", Rscons.glob("src/**/*.cc"))
 ```
 
 The SharedLibrary builder compiles and links the given sources to a dynamically
@@ -411,14 +420,14 @@ construction variables can be overridden by the user.
 | ARFLAGS | Array | Static library archiver flags | ["rcs"] |
 | AS | String | Assembler executable | "${CC}" |
 | ASCMD | Array | Assembler command line | ["${AS}", "-c", "-o", "${_TARGET}", "${ASDEPGEN}", "${INCPREFIX}${ASPPPATH}", "${ASPPFLAGS}", "${ASFLAGS}", "${_SOURCES}"] |
-| ASDEPGEN | Array | Assembly dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}"] |
+| ASDEPGEN | Array | Assembly dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}", "-MT", "TARGET"] |
 | ASFLAGS | Array | Assembler flags | [] |
 | ASPPFLAGS | Array | Assembler preprocessor flags | ["${CPPFLAGS}"] |
 | ASPPPATH | Array | Assembler preprocessor path | ["${CPPPATH}"] |
 | ASSUFFIX | Array | Assembly file suffixes | [".S"] |
 | CC | String | C compiler executable | "gcc" |
 | CCCMD | Array | C compiler command line | ["${CC}", "-c", "-o", "${_TARGET}", "${CCDEPGEN}", "${INCPREFIX}${CPPPATH}", "${CPPFLAGS}", "${CFLAGS}", "${CCFLAGS}", "${_SOURCES}"] |
-| CCDEPGEN | Array | C compiler dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}"] |
+| CCDEPGEN | Array | C compiler dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}", "-MT", "TARGET"] |
 | CCFLAGS | Array | Common flags for both C and C++ compiler | [] |
 | CFLAGS | Array | C compiler flags | [] |
 | CPP_CMD | Array | Preprocess command line | ["${_PREPROCESS_CC}", "-E", "${_PREPROCESS_DEPGEN}", "-o", "${_TARGET}", "${INCPREFIX}${CPPPATH}", "${CPPFLAGS}", "${_SOURCES}"] |
@@ -430,12 +439,13 @@ construction variables can be overridden by the user.
 | CSUFFIX | Array | C source file suffixes | [".c"] |
 | CXX | String | C++ compiler executable | "g++" |
 | CXXCMD | Array | C++ compiler command line | ["${CXX}", "-c", "-o", "${_TARGET}", "${CXXDEPGEN}", "${INCPREFIX}${CPPPATH}", "${CPPFLAGS}", "${CXXFLAGS}", "${CCFLAGS}", "${_SOURCES}"] |
-| CXXDEPGEN | Array | C++ compiler dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}"] |
+| CXXDEPGEN | Array | C++ compiler dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}", "-MT", "TARGET"] |
 | CXXFLAGS | Array | C++ compiler flags | [] |
 | CXXSUFFIX | Array | C++ source file suffixes | [".cc", ".cpp", ".cxx", ".C"] |
 | D_IMPORT_PATH | Array | D compiler import path | [] |
 | DC | String | D compiler executable | "gdc" |
-| DCCMD | Array | D compiler command line | ["${DC}", "-c", "-o", "${_TARGET}", "${INCPREFIX}${D_IMPORT_PATH}", "${DFLAGS}", "${_SOURCES}"] |
+| DCCMD | Array | D compiler command line | ["${DC}", "-c", "-o", "${_TARGET}", "${DDEPGEN}", "${INCPREFIX}${D_IMPORT_PATH}", "${DFLAGS}", "${_SOURCES}"] |
+| DDEPGEN | Array | D compiler dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}", "-MT", "TARGET"] |
 | DEPFILESUFFIX | String | Dependency file suffix for Makefile-style dependency rules emitted by the compiler (used internally for temporary dependency files used to determine a source file's dependencies) | ".mf" |
 | DFLAGS | Array | D compiler flags | [] |
 | DISASM_CMD | Array | Disassemble command line | ["${OBJDUMP}", "${DISASM_FLAGS}", "${_SOURCES}"] |
@@ -548,9 +558,19 @@ end
 You can pass multiple dependency files to `Environment#depends`:
 
 ```ruby
-env.depends("my_app", "config/link.ld", "README.txt", *Dir.glob("assets/**/*"))
+env.depends("my_app", "config/link.ld", "README.txt", *Rscons.glob("assets/**/*"))
 ```
 
+### Command-Line Variables
+
+Variables can be specified on the rscons command line. For example:
+
+```
+rscons VAR=val
+```
+
+These variables are accessible in a global VarSet called `Rscons.vars`.
+
 ### Construction Variable Naming
 
 * uppercase strings - the default construction variables that Rscons uses

bin/rscons

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 require "rscons/cli"
 
 Rscons::Cli.run(ARGV)

build_tests/build_dir/Rsconsfile

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

build_tests/build_dir/backward_compatible_build_hooks.rb

@@ -6,7 +6,7 @@ end
 
 Rscons::Environment.new(echo: :command) do |env|
   env.add_builder(MyObject.new)
-  env.append('CPPPATH' => Dir['src/**/*/'].sort)
+  env.append('CPPPATH' => Rscons.glob('src/**'))
   env.add_build_hook do |build_op|
     if build_op[:builder].name == "MyObject" && build_op[:sources].first =~ %r{one\.c}
       build_op[:vars]["CFLAGS"] << "-O1"

build_tests/build_dir/build_dirs_and_root.rb

@@ -1,6 +1,6 @@
 env = Rscons::Environment.new do |env|
-  env.append('CPPPATH' => Dir['src/**/*/'].sort)
+  env.append('CPPPATH' => Rscons.glob('src/**/*/'))
   env.build_dir("src", "build")
   env.build_root = "build_root"
-  env.Program('build_dir.exe', Dir['src/**/*.c'])
+  env.Program('build_dir.exe', Rscons.glob('src/**/*.c'))
 end

build_tests/build_dir/build_hooks.rb

@@ -1,5 +1,5 @@
 Rscons::Environment.new(echo: :command) do |env|
-  env.append('CPPPATH' => Dir['src/**/*/'].sort)
+  env.append('CPPPATH' => Rscons.glob('src/**/*/'))
   env.build_dir(%r{^src/([^/]+)/}, 'build_\\1/')
   env.add_build_hook do |build_op|
     if build_op[:target] =~ %r{build_one/.*\.o}
@@ -8,5 +8,5 @@ Rscons::Environment.new(echo: :command) do |env|
       build_op[:vars]["CFLAGS"] << "-O2"
     end
   end
-  env.Program('build_hook.exe', Dir['src/**/*.c'].sort)
+  env.Program('build_hook.exe', Rscons.glob('src/**/*.c'))
 end

build_tests/build_dir/carat.rb

@@ -1,8 +1,8 @@
 Rscons::Environment.new(echo: :command) do |env|
-  env.append('CPPPATH' => Dir['src/**/*/'].sort)
+  env.append('CPPPATH' => Rscons.glob('src/**').sort)
   env.build_root = "build_root"
   FileUtils.mkdir_p(env.build_root)
   FileUtils.mv("src/one/one.c", "build_root")
   env.Object("^/one.o", "^/one.c")
-  env.Program("build_dir.exe", Dir['src/**/*.c'] + ["^/one.o"])
+  env.Program("build_dir.exe", Rscons.glob('src/**/*.c') + ["^/one.o"])
 end

build_tests/build_dir/csuffix.rb

@@ -1,6 +1,6 @@
 Rscons::Environment.new do |env|
   env["CSUFFIX"] = %w[.yargh .c]
   env["CFLAGS"] += %w[-x c]
-  env["CPPPATH"] += Dir["src/**/"]
-  env.Program("build_dir.exe", Dir["src/**/*.{c,yargh}"])
+  env["CPPPATH"] += Rscons.glob("src/**")
+  env.Program("build_dir.exe", Rscons.glob("src/**/*.{c,yargh}"))
 end

build_tests/build_dir/no_match_build_dir.rb

@@ -1,6 +1,6 @@
 Rscons::Environment.new do |env|
-  env.append('CPPPATH' => Dir['src/**/*/'].sort)
+  env.append('CPPPATH' => Rscons.glob('src/**'))
   env.build_dir("src2", "build")
   env.build_root = "build_root"
-  env.Program('build_dir.exe', Dir['src/**/*.c'])
+  env.Program('build_dir.exe', Rscons.glob('src/**/*.c'))
 end

build_tests/build_dir/slashes.rb

@@ -1,6 +1,6 @@
 Rscons::Environment.new do |env|
-  env.append("CPPPATH" => Dir["src/**/*/"].sort)
+  env.append("CPPPATH" => Rscons.glob("src/**"))
   env.build_dir("src/one/", "build_one/")
   env.build_dir("src/two", "build_two")
-  env.Program("build_dir.exe", Dir["src/**/*.c"])
+  env.Program("build_dir.exe", Rscons.glob("src/**/*.c"))
 end

build_tests/d/Rsconsfile

@@ -1,3 +1,3 @@
 Rscons::Environment.new(echo: :command) do |env|
-  env.Program("hello-d.exe", Dir["*.d"])
+  env.Program("hello-d.exe", Rscons.glob("*.d"))
 end

build_tests/d/main.d

@@ -1,6 +1,7 @@
 import std.stdio;
+import mod;
 
 void main()
 {
-    writeln("Hello from D!");
+    writeln("Hello from D, value is ", Klass.VAL, "!");
 }

build_tests/d/mod.d

@@ -0,0 +1,4 @@
+class Klass
+{
+    enum VAL = 42;
+};

build_tests/library/override_arcmd.rb

@@ -1,4 +1,4 @@
 Rscons::Environment.new(echo: :command) do |env|
   env["ARCMD"] = %w[ar rcf ${_TARGET} ${_SOURCES}]
-  env.Library("lib.a", Dir["*.c"].sort)
+  env.Library("lib.a", Rscons.glob("*.c"))
 end

build_tests/shared_library/Rsconsfile

@@ -1,11 +1,11 @@
 Rscons::Environment.new do |env|
   env["CPPPATH"] << "src/lib"
-  libmine = env.SharedLibrary("mine", Dir["src/lib/*.c"])
+  libmine = env.SharedLibrary("mine", Rscons.glob("src/lib/*.c"))
   env.Program("test-shared.exe",
-              Dir["src/*.c"],
+              Rscons.glob("src/*.c"),
               "LIBPATH" => %w[.],
               "LIBS" => %w[mine])
   env.build_after("test-shared.exe", libmine.to_s)
   env.Program("test-static.exe",
-              Dir["src/**/*.c"])
+              Rscons.glob("src/**/*.c"))
 end

build_tests/shared_library/shared_library_cxx.rb

@@ -1,11 +1,11 @@
 Rscons::Environment.new do |env|
   env["CPPPATH"] << "src/lib"
-  libmine = env.SharedLibrary("mine", Dir["src/lib/*.cc"])
+  libmine = env.SharedLibrary("mine", Rscons.glob("src/lib/*.cc"))
   env.Program("test-shared.exe",
-              Dir["src/*.cc"],
+              Rscons.glob("src/*.cc"),
               "LIBPATH" => %w[.],
               "LIBS" => %w[mine])
   env.build_after("test-shared.exe", libmine.to_s)
   env.Program("test-static.exe",
-              Dir["src/**/*.cc"])
+              Rscons.glob("src/**/*.cc"))
 end

build_tests/shared_library/shared_library_d.rb

@@ -1,8 +1,8 @@
 Rscons::Environment.new do |env|
   env["CPPPATH"] << "src/lib"
-  libmine = env.SharedLibrary("mine", Dir["src/lib/*.d"])
+  libmine = env.SharedLibrary("mine", Rscons.glob("src/lib/*.d"))
   env.Program("test-shared.exe",
-              Dir["src/*.c"],
+              Rscons.glob("src/*.c"),
               "LIBPATH" => %w[.],
               "LIBS" => %w[mine])
   env.build_after("test-shared.exe", libmine.to_s)

build_tests/shared_library/shared_library_set_shld.rb

@@ -1,12 +1,12 @@
 Rscons::Environment.new do |env|
   env["CPPPATH"] << "src/lib"
   env["SHLD"] = "gcc"
-  libmine = env.SharedLibrary("mine", Dir["src/lib/*.c"])
+  libmine = env.SharedLibrary("mine", Rscons.glob("src/lib/*.c"))
   env.Program("test-shared.exe",
-              Dir["src/*.c"],
+              Rscons.glob("src/*.c"),
               "LIBPATH" => %w[.],
               "LIBS" => %w[mine])
   env.build_after("test-shared.exe", libmine.to_s)
   env.Program("test-static.exe",
-              Dir["src/**/*.c"])
+              Rscons.glob("src/**/*.c"))
 end

build_tests/simple/cache_debugging.rb

@@ -0,0 +1,34 @@
+class DebugBuilder < Rscons::Builder
+  def run(options)
+    target, sources, cache, env, vars = options.values_at(:target, :sources, :cache, :env, :vars)
+    command = %W[gcc -c -o #{target} #{sources.first}]
+    if Rscons.vars["command_change"]
+      command += %w[-Wall]
+    end
+    if Rscons.vars["new_dep"]
+      sources += ["extra"]
+    end
+    if Rscons.vars["strict_deps1"]
+      sources += ["extra"]
+      strict_deps = true
+    end
+    if Rscons.vars["strict_deps2"]
+      sources = ["extra"] + sources
+      strict_deps = true
+    end
+    unless cache.up_to_date?(target, command, sources, env, debug: true, strict_deps: strict_deps)
+      desc = "#{self.class.name} #{target}"
+      return false unless env.execute(desc, command)
+      cache.register_build(target, command, sources, env)
+    end
+    target
+  end
+end
+
+Rscons::Environment.new do |env|
+  env.add_builder(DebugBuilder.new)
+  if Rscons.vars["new_user_dep"]
+    env.depends("foo.o", "new_dep")
+  end
+  env.DebugBuilder("foo.o", "simple.c")
+end

build_tests/simple/cache_varset.rb

@@ -0,0 +1,20 @@
+class TestBuilder < Rscons::Builder
+  def run(options)
+    target, sources, cache, env = options.values_at(:target, :sources, :cache, :env)
+    command = Rscons::VarSet.new("A" => "a", "B" => "b")
+    unless cache.up_to_date?(target, command, sources, env)
+      File.open(target, "w") do |fh|
+        fh.puts("hi")
+      end
+      msg = "#{self.class.name} #{target}"
+      env.print_builder_run_message(msg, msg)
+      cache.register_build(target, command, sources, env)
+    end
+    target
+  end
+end
+
+Rscons::Environment.new do |env|
+  env.add_builder(TestBuilder.new)
+  env.TestBuilder("foo")
+end

build_tests/simple/cvar_array.rb

@@ -1,4 +1,4 @@
 Rscons::Environment.new do |env|
-  env["sources"] = Dir["*.c"].sort
+  env["sources"] = Rscons.glob("*.c")
   env.Program("simple.exe", "${sources}")
 end

lib/rscons.rb

@@ -55,6 +55,11 @@ module Rscons
     #   Whether to output ANSI color escape sequences.
     attr_accessor :do_ansi_color
 
+    # @since 1.16.0
+    # @return [VarSet]
+    #   Access any variables set on the rscons command-line.
+    attr_reader :vars
+
     # Remove all generated files.
     #
     # @return [void]
@@ -165,6 +170,35 @@ module Rscons
       @command_executer = val
     end
 
+    # Return a list of paths matching the specified pattern(s).
+    #
+    # @since 1.16.0
+    #
+    # A pattern can contain a "/**" component to recurse through directories.
+    # If the pattern ends with "/**" then only the recursive list of
+    # directories will be returned.
+    #
+    # Examples:
+    # - "src/**": return all directories under "src", recursively (including
+    #   "src" itself).
+    # - "src/**/*": return all files and directories recursively under the src
+    #   directory.
+    # - "src/**/*.c": return all .c files recursively under the src directory.
+    # - "dir/*/": return all directories in dir, but no files.
+    #
+    # @return [Array<String>] Paths matching the specified pattern(s).
+    def glob(*patterns)
+      require "pathname"
+      patterns.reduce([]) do |result, pattern|
+        if pattern.end_with?("/**")
+          pattern += "/"
+        end
+        result += Dir.glob(pattern).map do |path|
+          Pathname.new(path.gsub("\\", "/")).cleanpath.to_s
+        end
+      end.sort
+    end
+
     private
 
     # Determine the number of threads to use by default.
@@ -203,6 +237,7 @@ module Rscons
   end
 
   @n_threads = determine_n_threads
+  @vars = VarSet.new
 
 end
 

lib/rscons/builders/object.rb

@@ -30,7 +30,7 @@ module Rscons
           'ASSUFFIX' => ['.S'],
           'ASPPPATH' => '${CPPPATH}',
           'ASPPFLAGS' => '${CPPFLAGS}',
-          'ASDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
+          'ASDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}', '-MT', 'TARGET'],
           'ASCMD' => ['${AS}', '-c', '-o', '${_TARGET}', '${ASDEPGEN}', '${INCPREFIX}${ASPPPATH}', '${ASPPFLAGS}', '${ASFLAGS}', '${_SOURCES}'],
 
           'CPPFLAGS' => ['${CPPDEFPREFIX}${CPPDEFINES}'],
@@ -42,20 +42,21 @@ module Rscons
           'CC' => 'gcc',
           'CFLAGS' => [],
           'CSUFFIX' => ['.c'],
-          'CCDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
+          'CCDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}', '-MT', 'TARGET'],
           'CCCMD' => ['${CC}', '-c', '-o', '${_TARGET}', '${CCDEPGEN}', '${INCPREFIX}${CPPPATH}', '${CPPFLAGS}', '${CFLAGS}', '${CCFLAGS}', '${_SOURCES}'],
 
           'CXX' => 'g++',
           'CXXFLAGS' => [],
           'CXXSUFFIX' => ['.cc', '.cpp', '.cxx', '.C'],
-          'CXXDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}'],
+          'CXXDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}', '-MT', 'TARGET'],
           'CXXCMD' =>['${CXX}', '-c', '-o', '${_TARGET}', '${CXXDEPGEN}', '${INCPREFIX}${CPPPATH}', '${CPPFLAGS}', '${CXXFLAGS}', '${CCFLAGS}', '${_SOURCES}'],
 
           'DC' => 'gdc',
           'DFLAGS' => [],
           'DSUFFIX' => ['.d'],
+          'DDEPGEN' => ['-MMD', '-MF', '${_DEPFILE}', '-MT', 'TARGET'],
           'D_IMPORT_PATH' => [],
-          'DCCMD' => ['${DC}', '-c', '-o', '${_TARGET}', '${INCPREFIX}${D_IMPORT_PATH}', '${DFLAGS}', '${_SOURCES}'],
+          'DCCMD' => ['${DC}', '-c', '-o', '${_TARGET}', '${DDEPGEN}', '${INCPREFIX}${D_IMPORT_PATH}', '${DFLAGS}', '${_SOURCES}'],
         }
       end
 
@@ -114,7 +115,7 @@ module Rscons
         if options[:command_status]
           target, deps, cache, env, vars = options.values_at(:target, :sources, :cache, :env, :vars)
           if File.exists?(vars['_DEPFILE'])
-            deps += Environment.parse_makefile_deps(vars['_DEPFILE'], target)
+            deps += Environment.parse_makefile_deps(vars['_DEPFILE'], 'TARGET')
             FileUtils.rm_f(vars['_DEPFILE'])
           end
           cache.register_build(target, options[:tc].command, deps.uniq, env)

lib/rscons/builders/shared_object.rb

@@ -100,7 +100,7 @@ module Rscons
         if options[:command_status]
           target, deps, cache, env, vars = options.values_at(:target, :sources, :cache, :env, :vars)
           if File.exists?(vars['_DEPFILE'])
-            deps += Environment.parse_makefile_deps(vars['_DEPFILE'], target)
+            deps += Environment.parse_makefile_deps(vars['_DEPFILE'], 'TARGET')
             FileUtils.rm_f(vars['_DEPFILE'])
           end
           cache.register_build(target, options[:tc].command, deps.uniq, env)

lib/rscons/cache.rb

@@ -111,6 +111,10 @@ module Rscons
     # @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] :debug
+    #   If turned on, this causes the Cache to print messages explaining why
+    #   a build target is out of date. This could aid a builder author in
+    #   debugging the operation of their builder.
     # @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
@@ -133,39 +137,79 @@ module Rscons
 
         unless Rscons.phony_target?(target)
           # target file must exist on disk
-          return false unless File.exists?(target)
+          unless File.exists?(target)
+            if options[:debug]
+              puts "Target #{target} needs rebuilding because it does not exist on disk"
+            end
+            return false
+          end
         end
 
         # target must be registered in the cache
-        return false unless @cache["targets"].has_key?(cache_key)
+        unless @cache["targets"].has_key?(cache_key)
+          if options[:debug]
+            puts "Target #{target} needs rebuilding because there is no cached build information for it"
+          end
+          return false
+        end
 
         unless Rscons.phony_target?(target)
           # target must have the same checksum as when it was built last
-          return false unless @cache["targets"][cache_key]["checksum"] == lookup_checksum(target)
+          unless @cache["targets"][cache_key]["checksum"] == lookup_checksum(target)
+            if options[:debug]
+              puts "Target #{target} needs rebuilding because it has been changed on disk since being built last"
+            end
+            return false
+          end
         end
 
         # command used to build target must be identical
-        return false unless @cache["targets"][cache_key]["command"] == Digest::MD5.hexdigest(command.inspect)
+        unless @cache["targets"][cache_key]["command"] == Digest::MD5.hexdigest(command.inspect)
+          if options[:debug]
+            puts "Target #{target} needs rebuilding because the command used to build it has changed"
+          end
+          return false
+        end
 
         cached_deps = @cache["targets"][cache_key]["deps"] || []
         cached_deps_fnames = cached_deps.map { |dc| dc["fname"] }
         if options[:strict_deps]
           # depedencies passed in must exactly equal those in the cache
-          return false unless deps == cached_deps_fnames
+          unless deps == cached_deps_fnames
+            if options[:debug]
+              puts "Target #{target} needs rebuilding because the :strict_deps option is given and the set of dependencies does not match the previous set of dependencies"
+            end
+            return false
+          end
         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?
+          unless (Set.new(deps) - Set.new(cached_deps_fnames)).empty?
+            if options[:debug]
+              puts "Target #{target} needs rebuilding because there are new dependencies"
+            end
+            return false
+          end
         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
+        unless user_deps == cached_user_deps_fnames
+          if options[:debug]
+            puts "Target #{target} needs rebuilding because the set of user-specified dependency files has changed"
+          end
+          return false
+        end
 
         # 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"])
+          unless dep_cache["checksum"] == lookup_checksum(dep_cache["fname"])
+            if options[:debug]
+              puts "Target #{target} needs rebuilding because dependency file #{dep_cache["fname"]} has changed"
+            end
+            return false
+          end
         end
       end
 

lib/rscons/cli.rb

@@ -60,6 +60,12 @@ module Rscons
 
         end.parse!(argv)
 
+        argv.each do |arg|
+          if arg =~ /^([^=]+)=(.*)$/
+            Rscons.vars[$1] = $2
+          end
+        end
+
         if rsconsfile
           unless File.exists?(rsconsfile)
             $stderr.puts "Cannot read #{rsconsfile}"

lib/rscons/varset.rb

@@ -143,6 +143,13 @@ module Rscons
       end
     end
 
+    # Return a String representing the VarSet.
+    #
+    # @return [String] Representation of the VarSet.
+    def inspect
+      to_h.inspect
+    end
+
     # Return an array containing the values associated with the given keys.
     #
     # @param keys [Array<String, Symbol>]

lib/rscons/version.rb

@@ -1,4 +1,4 @@
 module Rscons
   # gem version
-  VERSION = "1.15.0"
+  VERSION = "1.16.0"
 end

rscons.gemspec

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

spec/build_tests_spec.rb

@@ -91,6 +91,7 @@ end
 $LOAD_PATH.unshift(#{@owd.inspect} + "/lib")
 # force color off
 ENV["TERM"] = nil
+#{options[:ruby_setup_code]}
 EOF
     end
     stdout, stderr, status = nil, nil, nil
@@ -125,7 +126,7 @@ EOF
     result = run_test(rsconsfile: "command.rb")
     expect(result.stderr).to eq ""
     expect(lines(result.stdout)).to eq [
-      'gcc -c -o build/simple.o -MMD -MF build/simple.mf simple.c',
+      'gcc -c -o build/simple.o -MMD -MF build/simple.mf -MT TARGET simple.c',
       "gcc -o simple.exe build/simple.o",
     ]
   end
@@ -194,7 +195,7 @@ EOF
     result = run_test(rsconsfile: "command.rb")
     expect(result.stderr).to eq ""
     expect(lines(result.stdout)).to eq [
-      'gcc -c -o build/simple.o -MMD -MF build/simple.mf simple.c',
+      'gcc -c -o build/simple.o -MMD -MF build/simple.mf -MT TARGET simple.c',
       "gcc -o simple.exe build/simple.o",
     ]
     result = run_test(rsconsfile: "link_flag_change.rb")
@@ -249,8 +250,8 @@ EOF
     result = run_test(rsconsfile: "carat.rb")
     expect(result.stderr).to eq ""
     expect(Set[*lines(result.stdout)]).to eq Set[
-      %q{gcc -c -o build_root/one.o -MMD -MF build_root/one.mf -Isrc/one/ -Isrc/two/ build_root/one.c},
-      %q{gcc -c -o build_root/src/two/two.o -MMD -MF build_root/src/two/two.mf -Isrc/one/ -Isrc/two/ src/two/two.c},
+      %q{gcc -c -o build_root/one.o -MMD -MF build_root/one.mf -MT TARGET -Isrc -Isrc/one -Isrc/two build_root/one.c},
+      %q{gcc -c -o build_root/src/two/two.o -MMD -MF build_root/src/two/two.mf -MT TARGET -Isrc -Isrc/one -Isrc/two src/two/two.c},
       %Q{gcc -o build_dir.exe build_root/src/two/two.o build_root/one.o},
     ]
   end
@@ -329,9 +330,9 @@ EOF
     result = run_test
     expect(result.stderr).to eq ""
     expect(Set[*lines(result.stdout)]).to eq Set[
-      %q{gcc -c -o debug/program.o -MMD -MF debug/program.mf '-DSTRING="Debug Version"' -O2 src/program.c},
+      %q{gcc -c -o debug/program.o -MMD -MF debug/program.mf -MT TARGET '-DSTRING="Debug Version"' -O2 src/program.c},
       %Q{gcc -o program-debug.exe debug/program.o},
-      %q{gcc -c -o release/program.o -MMD -MF release/program.mf '-DSTRING="Release Version"' -O2 src/program.c},
+      %q{gcc -c -o release/program.o -MMD -MF release/program.mf -MT TARGET '-DSTRING="Release Version"' -O2 src/program.c},
       %Q{gcc -o program-release.exe release/program.o},
     ]
   end
@@ -341,7 +342,7 @@ EOF
     result = run_test(rsconsfile: "clone_all.rb")
     expect(result.stderr).to eq ""
     expect(lines(result.stdout)).to eq [
-      %q{gcc -c -o build/program.o -MMD -MF build/program.mf -DSTRING="Hello" -O2 src/program.c},
+      %q{gcc -c -o build/program.o -MMD -MF build/program.mf -MT TARGET -DSTRING="Hello" -O2 src/program.c},
       %q{post build/program.o},
       %Q{gcc -o program.exe build/program.o},
       %q{post program.exe},
@@ -364,8 +365,8 @@ EOF
     result = run_test
     expect(result.stderr).to eq ""
     expect(Set[*lines(result.stdout)]).to eq Set[
-      'gcc -c -o one.o -MMD -MF one.mf -DONE one.c',
-      'gcc -c -o build/two.o -MMD -MF build/two.mf two.c',
+      'gcc -c -o one.o -MMD -MF one.mf -MT TARGET -DONE one.c',
+      'gcc -c -o build/two.o -MMD -MF build/two.mf -MT TARGET two.c',
       "gcc -o two_sources.exe one.o build/two.o",
     ]
     expect(File.exists?("two_sources.exe")).to be_truthy
@@ -377,10 +378,10 @@ EOF
     result = run_test
     expect(result.stderr).to eq ""
     expect(Set[*lines(result.stdout)]).to eq Set[
-      'gcc -c -o build/one.o -MMD -MF build/one.mf -Dmake_lib one.c',
-      'gcc -c -o build/two.o -MMD -MF build/two.mf -Dmake_lib two.c',
+      'gcc -c -o build/one.o -MMD -MF build/one.mf -MT TARGET -Dmake_lib one.c',
+      'gcc -c -o build/two.o -MMD -MF build/two.mf -MT TARGET -Dmake_lib two.c',
       'ar rcs lib.a build/one.o build/two.o',
-      'gcc -c -o build/three.o -MMD -MF build/three.mf three.c',
+      'gcc -c -o build/three.o -MMD -MF build/three.mf -MT TARGET three.c',
       "gcc -o library.exe lib.a build/three.o",
     ]
     expect(File.exists?("library.exe")).to be_truthy
@@ -392,8 +393,8 @@ EOF
     result = run_test(rsconsfile: "build_hooks.rb")
     expect(result.stderr).to eq ""
     expect(Set[*lines(result.stdout)]).to eq Set[
-      '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 -c -o build_one/one.o -MMD -MF build_one/one.mf -MT TARGET -Isrc/one -Isrc/two -O1 src/one/one.c',
+      'gcc -c -o build_two/two.o -MMD -MF build_two/two.mf -MT TARGET -Isrc/one -Isrc/two -O2 src/two/two.c',
       'gcc -o build_hook.exe build_one/one.o build_two/two.o',
     ]
     expect(`./build_hook.exe`).to eq "Hello from two()\n"
@@ -429,11 +430,31 @@ EOF
       test_dir("d")
       result = run_test
       expect(result.stderr).to eq ""
-      expect(lines(result.stdout)).to eq [
-        "gdc -c -o build/main.o main.d",
-        "gdc -o hello-d.exe build/main.o",
-      ]
-      expect(`./hello-d.exe`.rstrip).to eq "Hello from D!"
+      slines = lines(result.stdout)
+      expect(slines).to include("gdc -c -o build/main.o -MMD -MF build/main.mf -MT TARGET main.d")
+      expect(slines).to include("gdc -c -o build/mod.o -MMD -MF build/mod.mf -MT TARGET mod.d")
+      expect(slines.last).to eq("gdc -o hello-d.exe build/main.o build/mod.o")
+      expect(`./hello-d.exe`.rstrip).to eq "Hello from D, value is 42!"
+    end
+
+    it "does dependency generation for D sources" do
+      test_dir("d")
+      result = run_test
+      expect(result.stderr).to eq ""
+      slines = lines(result.stdout)
+      expect(slines).to include("gdc -c -o build/main.o -MMD -MF build/main.mf -MT TARGET main.d")
+      expect(slines).to include("gdc -c -o build/mod.o -MMD -MF build/mod.mf -MT TARGET mod.d")
+      expect(slines.last).to eq("gdc -o hello-d.exe build/main.o build/mod.o")
+      expect(`./hello-d.exe`.rstrip).to eq "Hello from D, value is 42!"
+      fcontents = File.read("mod.d", mode: "rb").sub("42", "33")
+      File.open("mod.d", "wb") {|fh| fh.write(fcontents)}
+      result = run_test
+      expect(result.stderr).to eq ""
+      slines = lines(result.stdout)
+      expect(slines).to include("gdc -c -o build/main.o -MMD -MF build/main.mf -MT TARGET main.d")
+      expect(slines).to include("gdc -c -o build/mod.o -MMD -MF build/mod.mf -MT TARGET mod.d")
+      expect(slines.last).to eq("gdc -o hello-d.exe build/main.o build/mod.o")
+      expect(`./hello-d.exe`.rstrip).to eq "Hello from D, value is 33!"
     end
 
     it "creates shared libraries using D" do
@@ -873,8 +894,8 @@ EOF
       result = run_test(rsconsfile: "backward_compatible_build_hooks.rb")
       expect(result.stderr).to eq ""
       expect(Set[*lines(result.stdout)]).to eq Set[
-        'gcc -c -o one.o -MMD -MF one.mf -Isrc/one/ -Isrc/two/ -O1 src/two/two.c',
-        'gcc -c -o two.o -MMD -MF two.mf -Isrc/one/ -Isrc/two/ -O2 src/two/two.c'
+        'gcc -c -o one.o -MMD -MF one.mf -MT TARGET -Isrc -Isrc/one -Isrc/two -O1 src/two/two.c',
+        'gcc -c -o two.o -MMD -MF two.mf -MT TARGET -Isrc -Isrc/one -Isrc/two -O2 src/two/two.c'
       ]
       expect(File.exists?('one.o')).to be_truthy
       expect(File.exists?('two.o')).to be_truthy
@@ -1241,6 +1262,81 @@ EOF
         "LD simple.exe",
       ]
     end
+
+    it "allows a VarSet to be passed in as the command parameter" do
+      test_dir("simple")
+      result = run_test(rsconsfile: "cache_varset.rb")
+      expect(result.stderr).to eq ""
+      expect(lines(result.stdout)).to eq [
+        "TestBuilder foo",
+      ]
+      result = run_test(rsconsfile: "cache_varset.rb")
+      expect(result.stderr).to eq ""
+      expect(result.stdout).to eq ""
+    end
+
+    context "debugging" do
+      it "prints a message when the target does not exist" do
+        test_dir("simple")
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        expect(result.stdout).to match /Target foo\.o needs rebuilding because it does not exist on disk/
+      end
+
+      it "prints a message when there is no cached build information for the target" do
+        test_dir("simple")
+        FileUtils.touch("foo.o")
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        expect(result.stdout).to match /Target foo\.o needs rebuilding because there is no cached build information for it/
+      end
+
+      it "prints a message when the target file has changed on disk" do
+        test_dir("simple")
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        File.open("foo.o", "wb") {|fh| fh.puts "hi"}
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        expect(result.stdout).to match /Target foo\.o needs rebuilding because it has been changed on disk since being built last/
+      end
+
+      it "prints a message when the command has changed" do
+        test_dir("simple")
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        result = run_test(rsconsfile: "cache_debugging.rb", rscons_args: %w[command_change=yes])
+        expect(result.stdout).to match /Target foo\.o needs rebuilding because the command used to build it has changed/
+      end
+
+      it "prints a message when strict_deps is in use and the set of dependencies does not match" do
+        test_dir("simple")
+        result = run_test(rsconsfile: "cache_debugging.rb", rscons_args: %w[strict_deps1=yes])
+        result = run_test(rsconsfile: "cache_debugging.rb", rscons_args: %w[strict_deps2=yes])
+        expect(result.stdout).to match /Target foo\.o needs rebuilding because the :strict_deps option is given and the set of dependencies does not match the previous set of dependencies/
+      end
+
+      it "prints a message when there is a new dependency" do
+        test_dir("simple")
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        result = run_test(rsconsfile: "cache_debugging.rb", rscons_args: %w[new_dep=yes])
+        expect(result.stdout).to match /Target foo\.o needs rebuilding because there are new dependencies/
+      end
+
+      it "prints a message when there is a new user-specified dependency" do
+        test_dir("simple")
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        result = run_test(rsconsfile: "cache_debugging.rb", rscons_args: %w[new_user_dep=yes])
+        expect(result.stdout).to match /Target foo\.o needs rebuilding because the set of user-specified dependency files has changed/
+      end
+
+      it "prints a message when a dependency file has changed" do
+        test_dir("simple")
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        f = File.read("simple.c", mode: "rb")
+        f += "\n"
+        File.open("simple.c", "wb") do |fh|
+          fh.write(f)
+        end
+        result = run_test(rsconsfile: "cache_debugging.rb")
+        expect(result.stdout).to match /Target foo\.o needs rebuilding because dependency file simple\.c has changed/
+      end
+    end
   end
 
   context "Object builder" do
@@ -1258,7 +1354,7 @@ EOF
       result = run_test(rsconsfile: "override_depfilesuffix.rb")
       expect(result.stderr).to eq ""
       expect(lines(result.stdout)).to eq [
-        "gcc -c -o simple.o -MMD -MF simple.deppy simple.c",
+        "gcc -c -o simple.o -MMD -MF simple.deppy -MT TARGET simple.c",
       ]
     end