Fix SimpleCov coverage results for multiple invocations from same build test

Fix up some macOS test cases

.github/workflows/run-tests.yml

@@ -0,0 +1,38 @@
+name: Run RScons Tests
+
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        ruby-version: ['2.7', '3.0', '3.4']
+    
+    steps:
+    - name: Install dependencies (Linux)
+      if: runner.os == 'Linux'
+      run: sudo apt-get update && sudo apt-get install -y gcc gdc ldc clang flex bison
+
+    - name: Install dependencies (macOS)
+      if: runner.os == 'macOS'
+      run: brew install gcc ldc flex bison
+
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+
+    - name: Install dependencies
+      run: bundle install
+
+    - name: Run tests
+      run: rake all

.gitignore

@@ -7,5 +7,5 @@
 /gen/
 /large_project/
 /pkg/
-/test/
+/test_run/
 /yard/

CHANGELOG.md

@@ -1,3 +1,39 @@
+## v3.3.0
+
+### New Features
+
+- Add support for Ruby 3.4.
+- Fix up some macOS test cases.
+- #177 - Remove dependency on base64
+- #175 - Add support for building object files from LLVM assembly sources
+
+## v3.2.0
+
+### New Features
+
+- #171 - Place object files next to source files for source files in build directory
+- #170 - Use top-level build directory as environment build directory for unnamed environments
+- #167 - Add upgrading instructions
+- #166 - Replace CFile builder with Yacc and Lex builders
+
+### Fixes
+
+- #172 - Fix configuration checks performed with ldc2 compiler
+- #169 - Output a better error when pkg-config is not found
+- #168 - Cannot output binary to an environment's build root with the same name as the top-level source directory
+- #164 - Improve DSL method documentation
+
+## v3.1.0
+
+### New Features
+
+- #162 - Improve configuration error messages
+- #163 - Ruby 3.2 compatibility
+
+### Fixes
+
+- #161 - builder registered during build hooks should increase build step count
+
 ## v3.0.2
 
 ### Fixes

DEVELOPING.md

@@ -9,6 +9,6 @@ To run the rscons specs, the following commands must be available:
 * g++
 * clang++
 * gdc
-* ldc
+* ldc2
 * flex
 * bison

Gemfile

@@ -1,8 +1,10 @@
 source 'https://rubygems.org'
 
+gem "base64"
 gem "rspec"
 gem "rake"
-gem "simplecov", "~> 0.15.0"
+gem "simplecov"
+gem "openssl"
 if RbConfig::CONFIG["host"]["msys"]
   gem "json", "2.1.0"
 else

Gemfile.lock

@@ -1,52 +1,61 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.5.0)
+    base64 (0.3.0)
-    docile (1.1.5)
+    date (3.5.1)
-    json (2.6.1)
+    diff-lcs (1.6.2)
-    psych (4.0.3)
+    docile (1.4.1)
+    erb (6.0.1)
+    json (2.18.0)
+    openssl (4.0.0)
+    psych (5.3.1)
+      date
       stringio
-    rake (13.0.6)
+    rake (13.3.1)
-    rdoc (6.4.0)
+    rdoc (7.1.0)
+      erb
       psych (>= 4.0.0)
-    redcarpet (3.5.1)
+      tsort
-    rspec (3.11.0)
+    redcarpet (3.6.1)
-      rspec-core (~> 3.11.0)
+    rspec (3.13.2)
-      rspec-expectations (~> 3.11.0)
+      rspec-core (~> 3.13.0)
-      rspec-mocks (~> 3.11.0)
+      rspec-expectations (~> 3.13.0)
-    rspec-core (3.11.0)
+      rspec-mocks (~> 3.13.0)
-      rspec-support (~> 3.11.0)
+    rspec-core (3.13.6)
-    rspec-expectations (3.11.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
+      rspec-support (~> 3.13.0)
-    rspec-mocks (3.11.0)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
+      rspec-support (~> 3.13.0)
-    rspec-support (3.11.0)
+    rspec-support (3.13.6)
-    simplecov (0.15.1)
+    simplecov (0.22.0)
-      docile (~> 1.1.0)
+      docile (~> 1.1)
-      json (>= 1.8, < 3)
+      simplecov-html (~> 0.11)
-      simplecov-html (~> 0.10.0)
+      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.10.2)
+    simplecov-html (0.13.2)
-    stringio (3.0.1)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.2.0)
     syntax (1.2.2)
-    webrick (1.7.0)
+    tsort (0.2.0)
-    yard (0.9.27)
+    yard (0.9.38)
-      webrick (~> 1.7.0)
 
 PLATFORMS
   ruby
   x86-mingw32
 
 DEPENDENCIES
+  base64
   json
+  openssl
   rake
   rdoc
   redcarpet
   rspec
-  simplecov (~> 0.15.0)
+  simplecov
   syntax
   yard
 
 BUNDLED WITH
-   2.2.31
+   2.6.2

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013-2022 Josh Holtrop
+Copyright (c) 2013-2025 Josh Holtrop
 
 MIT License
 

README.md

@@ -9,7 +9,7 @@ It supports the following features:
   * multi-threaded job execution
   * auto-configuration
   * built-in builders for several common operations
-  * out-of-the-box support for C, C++, and D languages
+  * out-of-the-box support for Assembly, C, C++, D, and LLVM
   * extensibility for other languages or custom builders
   * compatible with Windows, Linux, OS X, and FreeBSD
   * colorized output with build progress

Rakefile.rb

@@ -8,8 +8,10 @@ end
 require "rspec/core/rake_task"
 require "rake/clean"
 require "fileutils"
+require "simplecov"
+require "stringio"
 
-CLEAN.include %w[build_test_run .yardoc yard coverage test]
+CLEAN.include %w[build_test_run .yardoc yard coverage test_run]
 CLOBBER.include %w[dist gen large_project pkg]
 
 task :build_dist do
@@ -19,24 +21,43 @@ end
 RSpec::Core::RakeTask.new(:spec, :example_string) do |task, args|
   ENV["specs"] = "1"
   if args.example_string
-    ENV["partial_specs"] = "1"
     task.rspec_opts = %W[-e "#{args.example_string}" -f documentation]
   end
 end
-task :spec => :build_dist
 task :spec do
   ENV.delete("specs")
 end
+task :spec => :build_tests
+task :spec do
+  unless ENV["rscons_dist_specs"]
+    original_stdout = $stdout
+    sio = StringIO.new
+    $stdout = sio
+    SimpleCov.collate Dir["coverage/.resultset.json", "coverage/bt*/.resultset.json"]
+    $stdout = original_stdout
+    sio.string.lines.each do |line|
+      $stdout.write(line) unless line =~ /Coverage report generated for/
+    end
+  end
+end
+
+task :build_tests do |task, args|
+  ENV["specs"] = "1"
+  sh "ruby -Ilib build_tests/build_tests.rb"
+  ENV.delete("specs")
+end
 
 # dspec task is useful to test the distributable release script, but is not
 # useful for coverage information.
 desc "Dist Specs"
 task :dspec, [:example_string] => :build_dist do |task, args|
-  FileUtils.mkdir_p("test")
+  FileUtils.rm_rf("test_run")
-  FileUtils.cp("dist/rscons", "test/rscons.rb")
+  FileUtils.mkdir_p("test_run")
-  ENV["dist_specs"] = "1"
+  FileUtils.cp("dist/rscons", "test_run/rscons.rb")
+  ENV["rscons_dist_specs"] = "1"
   Rake::Task["spec"].execute(args)
-  ENV.delete("dist_specs")
+  Rake::Task["build_tests"].execute(args)
+  ENV.delete("rscons_dist_specs")
   FileUtils.rm_f(Dir.glob(".rscons-*"))
 end
 

UPGRADING.md

@@ -0,0 +1,10 @@
+# Upgrading
+
+## v3.2.0
+
+- Replace any calls to `env.CFile()` builder with `env.Lex()` or `env.Yacc()` as required.
+
+## v3.0.0
+
+- Move `build` block contents outside of `build` block and remove `build` call.
+- Replace `Environment.new()` calls with `env()`.

build_tests/cfile/Rsconscript

@@ -1,4 +0,0 @@
-env do |env|
-  env.CFile("lexer.c", "lexer.l")
-  env.CFile("parser.c", "parser.y")
-end

build_tests/cfile/error_unknown_extension.rb

@@ -1,3 +0,0 @@
-env do |env|
-  env.CFile("file.c", "foo.bar")
-end

build_tests/clone_env/Rsconscript

@@ -1,10 +1,10 @@
-debug = env(echo: :command) do |env|
+debug = env("dbg", echo: :command) do |env|
   env['CFLAGS'] = '-O2'
   env['CPPFLAGS'] = '-DSTRING="Debug Version"'
   env.Program('program-debug.exe', Dir['src/*.c'])
 end
 
-release = debug.clone do |env|
+release = debug.clone("rls") do |env|
   env["CPPFLAGS"] = '-DSTRING="Release Version"'
   env.Program('program-release.exe', Dir['src/*.c'])
 end

build_tests/clone_env/clone_all.rb

@@ -1,4 +1,4 @@
-env1 = env(echo: :command) do |env|
+env1 = env("e1", echo: :command) do |env|
   env['CFLAGS'] = '-O2'
   env.add_build_hook do |builder|
     builder.vars['CPPFLAGS'] = '-DSTRING="Hello"'
@@ -9,6 +9,6 @@ env1 = env(echo: :command) do |env|
   env.Program('program.exe', Dir['src/*.c'])
 end
 
-env2 = env1.clone do |env|
+env2 = env1.clone("e2") do |env|
   env.Program('program2.exe', Dir['src/*.c'])
 end

build_tests/configure/check_cfg_no_pkg_config.rb

@@ -0,0 +1,5 @@
+ENV["PATH"] = ""
+
+configure do
+  check_cfg package: "mypackage"
+end

build_tests/configure/check_d_compiler_find_first.rb

@@ -1,3 +1,3 @@
 configure do
-  check_d_compiler "gdc", "ldc2"
+  check_d_compiler "gdc", "ldc2", "ldc"
 end

build_tests/configure/check_lib_with_ldc.rb

@@ -0,0 +1,8 @@
+configure do
+  check_d_compiler "ldc2"
+  check_lib "z"
+end
+
+env(echo: :command) do |env|
+  env.Program("simple.exe", "simple.d")
+end

build_tests/lex_yacc/Rsconscript

@@ -0,0 +1,4 @@
+env do |env|
+  env.Lex("lexer.c", "lexer.l")
+  env.Yacc("parser.c", "parser.y")
+end

build_tests/llvm/Rsconscript

@@ -0,0 +1,4 @@
+env do |env|
+  env["LLVMAS_FLAGS"] += %w[-Wno-override-module]
+  env.Program("llvmtest.exe", %w[main.c one.ll])
+end

build_tests/llvm/direct.rb

@@ -0,0 +1,8 @@
+configure do
+  check_c_compiler "clang"
+end
+
+env do |env|
+  env["LLVMAS_FLAGS"] += %w[-Wno-override-module]
+  env.Program("llvmtest.exe", %w[one.ll two.ll main2.c], direct: true)
+end

build_tests/llvm/main.c

@@ -0,0 +1,6 @@
+extern int one(void);
+
+int main(int argc, char * argv[])
+{
+    return one();
+}

build_tests/llvm/main2.c

@@ -0,0 +1,9 @@
+extern int one(void);
+extern int two(void);
+
+int main(int argc, char * argv[])
+{
+    one();
+    two();
+    return 0;
+}

build_tests/llvm/one.ll

@@ -0,0 +1,9 @@
+@str = private unnamed_addr constant [12 x i8] c"hello world\00"
+
+declare i32 @puts(ptr nocapture) nounwind
+
+define i32 @one()
+{
+    call i32 @puts(ptr @str)
+    ret i32 0
+}

build_tests/llvm/two.ll

@@ -0,0 +1,9 @@
+@str = private unnamed_addr constant [12 x i8] c"hello again\00"
+
+declare i32 @puts(ptr nocapture) nounwind
+
+define i32 @two()
+{
+    call i32 @puts(ptr @str)
+    ret i32 0
+}

build_tests/simple/build_root_source_path.rb

@@ -0,0 +1,13 @@
+env("e", echo: :command) do |env|
+  source_file = "#{env.build_root}/src/foo.c"
+  FileUtils.mkdir_p(File.dirname(source_file))
+  File.open(source_file, "w") do |fh|
+    fh.puts(<<-EOF)
+    int main()
+    {
+      return 29;
+    }
+    EOF
+  end
+  env.Program("foo.exe", source_file)
+end

build_tests/simple/builder_wait_for_builder.rb

@@ -1,7 +1,7 @@
 class MyObject < Rscons::Builder
   def run(options)
     if @builder
-      if File.exists?(@target)
+      if File.exist?(@target)
         true
       else
         false

build_tests/simple/user_dep_build_order.rb

@@ -4,7 +4,7 @@ class TestBuilder < Rscons::Builder
       true
     else
       if @target == "two"
-        return false unless File.exists?("one")
+        return false unless File.exist?("one")
       end
       wait_time = @env.expand_varref("${wait_time}", @vars)
       @command = ["ruby", "-e", "require 'fileutils'; sleep #{wait_time}; FileUtils.touch('#{@target}');"]

build_tests/two_sources/assuffix.rb

@@ -3,5 +3,5 @@ env do |env|
   env["CFLAGS"] += %w[-S]
   env.Object("one.ssss", "one.c", "CPPFLAGS" => ["-DONE"])
   env.Object("two.sss", "two.c")
-  env.Program("two_sources.exe", %w[one.ssss two.sss], "ASFLAGS" => env["ASFLAGS"] + %w[-x assembler])
+  env.Program("two_sources.exe", %w[one.ssss two.sss], "ASFLAGS" => env["ASFLAGS"] + %w[-x assembler-with-cpp])
 end

build_tests/typical/binary_matching_folder.rb

@@ -0,0 +1,4 @@
+env "src" do |env|
+  env["CPPPATH"] += glob("src/**")
+  env.Program("^/src", glob("src/**/*.c"))
+end

build_tests/typical/phonies.rb

@@ -0,0 +1,15 @@
+class Custom < Rscons::Builder
+  def run(options)
+    print_run_message("#{name} #{target}", nil)
+    true
+  end
+end
+
+env do |env|
+  env.add_builder(Custom)
+  env.Custom("t3", :phony1)
+  env.Custom(:phony1, "t2")
+  env.Custom("t2", :phony2)
+  env.Custom(:phony2, "t1")
+  env.Custom("t1", [])
+end

build_tests/variants/error_unnamed_environment.rb

@@ -0,0 +1,13 @@
+variant "debug"
+variant "release"
+
+with_variants do
+  env do |env|
+    if variant("debug")
+      env["CPPDEFINES"] << "DEBUG"
+    else
+      env["CPPDEFINES"] << "NDEBUG"
+    end
+    env.Program("^/prog.exe", "prog.c")
+  end
+end

doc/user_guide.md

@@ -6,7 +6,7 @@ It supports the following features:
   * multi-threaded job execution
   * auto-configuration
   * built-in builders for several common operations
-  * out-of-the-box support for C, C++, and D languages
+  * out-of-the-box support for Assembly, C, C++, D, and LLVM
   * extensibility for other languages or custom builders
   * compatible with Windows, Linux, OS X, and FreeBSD
   * colorized output with build progress
@@ -265,21 +265,17 @@ which they were added.
 Example:
 
 ```ruby
-task "build" do
+proj_env = env do |env|
-  env do |env|
+  env.Program("^/proj.elf", glob("src/**/*.c"))
-    env.Program("^^/proj.elf", glob("src/**/*.c"))
-  end
 end
 
-task "flash", deps: "build" do
+task "flash" do
-  sh "nrfjprog", "-f", "NRF52", "--program", env.expand("^^/proj.elf")
+  sh "nrfjprog", "-f", "NRF52", "--program", proj_env.expand("^/proj.elf")
 end
 ```
 
-In this example, the `flash` task depends on the `build` task.
+In this example, the `flash` task would first build the proj.elf target and
-So if the project had not yet been built, and the user executes
+then flash it to target with the nrfjprog program.
-`./rscons flash`, the project would first be built and then flashed to the
-target.
 
 If the `task` method is called again with the name of an already existing task,
 the task is not overwritten, but rather modified.
@@ -287,6 +283,34 @@ Any newly specified dependencies are added to the current dependencies.
 Any action block is appended to the task's list of action blocks to execute
 when the task is executed.
 
+For example, with the `Rsconscript`:
+
+```ruby
+task "a" do
+  puts "A"
+end
+
+task "b" do
+  puts "B"
+end
+
+task "c", depends: "a" do
+  puts "C1"
+end
+
+task "c", depends: "b" do
+  puts "C2"
+end
+```
+
+The following behavior is observed:
+
+    $ ./rscons c
+    A
+    B
+    C1
+    C2
+
 Note that for a simple project, the build script may not need to define any
 tasks at all and could just make use of the Rscons built-in default task (see
 ${#Default Task}).
@@ -378,7 +402,7 @@ argument (task name) automatically filled in by the shortcut method.
 For example:
 
 ```ruby
-default deps: "unpack_compiler" do
+default depends: "unpack_compiler" do
   puts "default task"
 end
 ```
@@ -386,7 +410,7 @@ end
 is equivalent to:
 
 ```ruby
-task "default", deps: "unpack_compiler" do
+task "default", depends: "unpack_compiler" do
   puts "default task"
 end
 ```
@@ -463,11 +487,11 @@ task "build" do
   ...
 end
 
-task "flash" do
+task "flash", depends: "build" do
   ...
 end
 
-default deps: "build"
+default depends: "build"
 ```
 
 Then when the user runs `./rscons` the "build" task will be executed.
@@ -901,11 +925,11 @@ There are several default builders that are built-in to Rscons:
 
   * `Command`, which executes a user-defined command to produce the target.
   * `Copy`, which copies files or directories to a specified destination.
-  * `CFile`, which builds a C or C++ source file from a lex or yacc input file.
   * `Directory`, which creates a directory.
   * `Disassemble`, which disassembles an object file to a disassembly listing.
   * `Install`, which installs files or directories to a specified destination.
   * `InstallDirectory`, which creates a directory in an install destination.
+  * `Lex`, which builds a source file from a lex input file.
   * `Library`, which collects object files into a static library archive file.
   * `Object`, which compiles source files to produce an object file.
   * `Preprocess`, which invokes the C/C++ preprocessor on a source file.
@@ -915,6 +939,7 @@ There are several default builders that are built-in to Rscons:
   * `SharedObject`, which compiles source files to produce an object file, in a
     way that is able to be used to create a shared library.
   * `Size`, which runs the 'size' utility on an executable file.
+  * `Yacc`, which builds a source file from a yacc input file.
 
 ####> The Command Builder
 
@@ -941,17 +966,6 @@ The `Command` builder supports the following construction variables:
     `CMD_STDOUT` is expanded for variable references, so the token `${_TARGET}`
     can be used, for example.
 
-####> The CFile Builder
-
-```ruby
-env.CFile(target, source)
-# Example
-env.CFile("^/parser/parser.c", "parser.y")
-```
-
-The `CFile` builder will generate a C or C++ source file from a lex (.l, .ll)
-or yacc (.y, .yy) input file.
-
 ####> The Copy Builder
 
 ```ruby
@@ -1024,6 +1038,17 @@ the `InstallDirectory` builder.
 The `uninstall` task removes targets created by the `InstallDirectory` builder
 but not by the `Directory` builder.
 
+####> The Lex Builder
+
+```ruby
+env.Lex(target, source)
+# Example
+env.Lex("^/lexer.c", "lexer.l")
+```
+
+The `Lex` builder will generate a source file from a lex (.l, .ll)
+input file.
+
 ####> The Library Builder
 
 ```ruby
@@ -1154,6 +1179,17 @@ stores its output in the target file.
 The size executable can be specified with the `SIZE` construction variable,
 and flags can be specified with `SIZEFLAGS`.
 
+####> The Yacc Builder
+
+```ruby
+env.Yacc(target, source)
+# Example
+env.Yacc("^/parser.c", "parser.y")
+```
+
+The `Yacc` builder will generate a source file from a yacc (.y, .yy)
+input file.
+
 ###> Phony Targets
 
 Rscons supports phony build targets.
@@ -1272,10 +1308,10 @@ It iterates through each enabled variant and calls the given block.
 In this example, the block would be called twice, once with the "kde" variant
 active, and the second time with the "gnome" variant active.
 
-Each `env()` call creates an Environment, so two environments are created.
+Each `env` method call creates an Environment, so two environments are created.
 When an Environment is created within a `with_variants` block, the
-Environment's name has the active variant(s) appended to the given Environment
+Environment's build directory name has the active variant(s) keys appended to
-name (if any), and separated by a "-".
+the given Environment name, and separated by a "-".
 
 In this example, a "prog-kde" Environment would be created with build root
 build/prog-kde and -DKDE would be passed to the compiler when compiling each
@@ -1284,6 +1320,29 @@ Next a "prog-gnome" Environment would be created with build root
 build/prog-gnome and -DGNOME would be passed to the compiler when compiling
 the sources.
 
+The key for a variant is the variant's name by default but can be overridden by
+passing a `:key` value to the `variant` method.
+A `nil` value for the `:key` parameter will omit that variant from appearing
+in the environment's build directory name.
+For example:
+
+```ruby
+variant "debug"
+variant "release", key: nil
+
+with_variants do
+  env "prog" do |env|
+  end
+end
+```
+
+In this example, one "prog" environment will be created for the "debug" variant
+with the build directory "prog-debug", and another "prog" environment will be
+created for the "release" variant with the build directory "prog".
+The build directory for the release variant of the "prog" environment is just
+"prog" instead of "prog-release" because the key for the "release" variant is
+set to `nil`.
+
 Variants are enabled by default, but can be disabled by passing a `false` value
 to the `:default` option of the `variant` method.
 For example:
@@ -1558,8 +1617,8 @@ end
 The `Object` and `SharedObject` builders that ship with Rscons have an API that
 allows the user to register extra languages that can be suppored by the
 builders.
-In fact, the built-in support for assembly, C, C++, and D compilation all make
+In fact, the built-in support for assembly, C, C++, D, and LLVM compilation
-use of this built-in API.
+all make use of this built-in API.
 To see an example of how this API is used, see the
 `lib/rscons/builders/lang/*.rb` files in the Rscons source repository.
 For example, here is how the C++ language is registered:
@@ -1868,6 +1927,15 @@ env do |env|
 end
 ```
 
+### Example: Building a Program from C and LLVM Sources
+
+```ruby
+env do |env|
+  env["CFLAGS"] << "-Wall"
+  env.Program("program", glob("src/**/*.{c,ll}"))
+end
+```
+
 ### Example: Cloning an Environment
 
 ```ruby
@@ -1935,7 +2003,7 @@ end
 
 ```ruby
 env do |env|
-  env.CFile("^/parser.tab.cc", "parser.yy")
+  env.Yacc("^/parser.tab.cc", "parser.yy")
 end
 ```
 

lib/rscons.rb

@@ -23,13 +23,14 @@ module Rscons
   # Names of the default builders which will be added to all newly created
   # {Environment} objects.
   DEFAULT_BUILDERS = [
-    :CFile,
+    :Barrier,
     :Command,
     :Copy,
     :Directory,
     :Disassemble,
     :Install,
     :InstallDirectory,
+    :Lex,
     :Library,
     :Object,
     :Preprocess,
@@ -37,6 +38,7 @@ module Rscons
     :SharedLibrary,
     :SharedObject,
     :Size,
+    :Yacc,
   ]
 
   # Class to represent a fatal error during an Rscons operation.
@@ -65,6 +67,13 @@ module Rscons
       target.is_a?(Symbol)
     end
 
+    # Generate a random phony target name.
+    #
+    # @return [Symbol] Phony target name.
+    def gen_phony_target
+      ("t" + sprintf("%08x", rand(1_000_000..4_000_000_000))).to_sym
+    end
+
     # Return the system shell and arguments for executing a shell command.
     #
     # @return [Array<String>] The shell and flag.
@@ -135,11 +144,12 @@ require_relative "rscons/builders/mixins/object_deps"
 require_relative "rscons/builders/mixins/program"
 
 # default builders
-require_relative "rscons/builders/cfile"
+require_relative "rscons/builders/barrier"
 require_relative "rscons/builders/command"
 require_relative "rscons/builders/copy"
 require_relative "rscons/builders/directory"
 require_relative "rscons/builders/disassemble"
+require_relative "rscons/builders/lex"
 require_relative "rscons/builders/library"
 require_relative "rscons/builders/object"
 require_relative "rscons/builders/preprocess"
@@ -148,12 +158,14 @@ require_relative "rscons/builders/shared_library"
 require_relative "rscons/builders/shared_object"
 require_relative "rscons/builders/simple_builder"
 require_relative "rscons/builders/size"
+require_relative "rscons/builders/yacc"
 
 # language support
 require_relative "rscons/builders/lang/asm"
 require_relative "rscons/builders/lang/c"
 require_relative "rscons/builders/lang/cxx"
 require_relative "rscons/builders/lang/d"
+require_relative "rscons/builders/lang/llvm_asm"
 
 # Unbuffer $stdout
 $stdout.sync = true

lib/rscons/application.rb

@@ -237,7 +237,7 @@ module Rscons
       cache = Cache.instance
       cache.targets(true).each do |target|
         cache.remove_target(target)
-        next unless File.exists?(target)
+        next unless File.exist?(target)
         puts "Removing #{target}" if verbose
         FileUtils.rm_f(target)
       end
@@ -258,6 +258,14 @@ module Rscons
     #
     # @param name [String]
     #   Variant name.
+    # @param options [Hash]
+    #   Optional parameters.
+    # @option options [String] :default
+    #   Whether the variant is enabled by default (default: true).
+    # @option options [String] :key
+    #   Variant key, used to name an Environment's build directory. If nil,
+    #   this variant will not contribute to the Environment's build directory
+    #   name.
     def variant(name, options = {})
       if @active_variants
         !!@active_variants.find {|variant| variant[:name] == name}
@@ -294,6 +302,15 @@ module Rscons
     end
 
     # Create a variant group.
+    #
+    # @overload variant_group(name, options = {})
+    #   @param name [String]
+    #     Variant group name (optional).
+    #   @param options [Hash]
+    #     Optional variant group parameters.
+    # @overload variant_group(options = {})
+    #   @param options [Hash]
+    #     Optional variant group parameters.
     def variant_group(*args, &block)
       if args.first.is_a?(String)
         name = args.slice!(0)

lib/rscons/builder_set.rb

@@ -37,7 +37,7 @@ module Rscons
     #   The number of remaining build steps.
     def build_steps_remaining
       self.reduce(0) do |result, (target, builders)|
-        result + builders.size
+        result + builders.count {|b| !b.is_a?(Rscons::Builders::Barrier)}
       end
     end
 

lib/rscons/builders/barrier.rb

@@ -0,0 +1,15 @@
+module Rscons
+  module Builders
+    # The Barrier builder does not perform any action. It exists as a builder
+    # on which to place dependencies to ensure that each of its sources are
+    # built before any build targets which depend on the barrier build target.
+    class Barrier < Builder
+
+      # Run the builder.
+      def run(options)
+        true
+      end
+
+    end
+  end
+end

lib/rscons/builders/cfile.rb

@@ -1,35 +0,0 @@
-module Rscons
-  module Builders
-    # Build a C or C++ source file given a lex (.l, .ll) or yacc (.y, .yy)
-    # input file.
-    #
-    # Examples::
-    #   env.CFile("parser.tab.cc", "parser.yy")
-    #   env.CFile("lex.yy.cc", "parser.ll")
-    class CFile < Builder
-
-      # Run the builder to produce a build target.
-      def run(options)
-        if @command
-          finalize_command
-        else
-          @vars["_TARGET"] = @target
-          @vars["_SOURCES"] = @sources
-          case
-          when @sources.first.end_with?(*@env.expand_varref("${LEXSUFFIX}"))
-            cmd = "LEX"
-            message = "Generating lexer"
-          when @sources.first.end_with?(*@env.expand_varref("${YACCSUFFIX}"))
-            cmd = "YACC"
-            message = "Generating parser"
-          else
-            raise "Unknown source file #{@sources.first.inspect} for CFile builder"
-          end
-          command = @env.build_command("${#{cmd}_CMD}", @vars)
-          standard_command("#{message} from <source>#{Util.short_format_paths(@sources)}<reset> => <target>#{@target}<reset>", command)
-        end
-      end
-
-    end
-  end
-end

lib/rscons/builders/copy.rb

@@ -14,14 +14,14 @@ module Rscons
       # Run the builder to produce a build target.
       def run(options)
         target_is_dir = (@sources.length > 1) ||
-                        Dir.exists?(@sources.first) ||
+                        Dir.exist?(@sources.first) ||
-                        Dir.exists?(@target)
+                        Dir.exist?(@target)
         outdir = target_is_dir ? @target : File.dirname(@target)
         # Collect the list of files to copy over.
         file_map = {}
         if target_is_dir
           @sources.each do |src|
-            if Dir.exists? src
+            if Dir.exist? src
               Dir.glob("#{src}/**/*", File::FNM_DOTMATCH).select do |f|
                 File.file?(f)
               end.each do |subfile|
@@ -50,7 +50,7 @@ module Rscons
           end
           @cache.register_build(dest, :Copy, [src], @env, install: @install_builder)
         end
-        (target_is_dir ? Dir.exists?(@target) : File.exists?(@target)) ? true : false
+        (target_is_dir ? Dir.exist?(@target) : File.exist?(@target)) ? true : false
       end
 
     end

lib/rscons/builders/directory.rb

@@ -14,7 +14,7 @@ module Rscons
       def run(options)
         if File.directory?(@target)
           true
-        elsif File.exists?(@target)
+        elsif File.exist?(@target)
           Ansi.write($stderr, :red, "Error: `#{@target}' already exists and is not a directory", :reset, "\n")
           false
         else

lib/rscons/builders/lang/llvm_asm.rb

@@ -0,0 +1,10 @@
+Rscons::Builders::Object.register(
+  command: "${LLVMAS_CMD}",
+  direct_command: "${LLVMAS_CMD:direct}",
+  suffix: "${LLVMAS_SUFFIX}",
+  short_description: "Assembling")
+Rscons::Builders::SharedObject.register(
+  command: "${LLVMAS_CMD}",
+  direct_command: "${LLVMAS_CMD:direct}",
+  suffix: "${LLVMAS_SUFFIX}",
+  short_description: "Assembling")

lib/rscons/builders/lex.rb

@@ -0,0 +1,24 @@
+module Rscons
+  module Builders
+    # Build a source file given a lex input file.
+    #
+    # Examples::
+    #   env.Lex("lex.c", "parser.l")
+    #   env.Lex("lex.cc", "parser.ll")
+    class Lex < Builder
+
+      # Run the builder to produce a build target.
+      def run(options)
+        if @command
+          finalize_command
+        else
+          @vars["_TARGET"] = @target
+          @vars["_SOURCES"] = @sources
+          command = @env.build_command("${LEX_CMD}", @vars)
+          standard_command("Generating lexer source from <source>#{Util.short_format_paths(@sources)}<reset> => <target>#{@target}<reset>", command)
+        end
+      end
+
+    end
+  end
+end

lib/rscons/builders/mixins/depfile.rb

@@ -8,7 +8,7 @@ module Rscons
         # dependency file.
         def finalize_command_with_depfile
           deps = @sources
-          if File.exists?(@vars["_DEPFILE"])
+          if File.exist?(@vars["_DEPFILE"])
             deps += Util.parse_dependency_file(@vars["_DEPFILE"])
           end
           @cache.register_build(@target, @command, deps.uniq, @env)

lib/rscons/builders/yacc.rb

@@ -0,0 +1,24 @@
+module Rscons
+  module Builders
+    # Build a source file given a yacc input file.
+    #
+    # Examples::
+    #   env.Yacc("parser.c", "parser.y")
+    #   env.Yacc("parser.cc", "parser.yy")
+    class Yacc < Builder
+
+      # Run the builder to produce a build target.
+      def run(options)
+        if @command
+          finalize_command
+        else
+          @vars["_TARGET"] = @target
+          @vars["_SOURCES"] = @sources
+          command = @env.build_command("${YACC_CMD}", @vars)
+          standard_command("Generating parser source from <source>#{Util.short_format_paths(@sources)}<reset> => <target>#{@target}<reset>", command)
+        end
+      end
+
+    end
+  end
+end

lib/rscons/cache.rb

@@ -147,7 +147,7 @@ module Rscons
 
         unless Rscons.phony_target?(target)
           # target file must exist on disk
-          unless File.exists?(target)
+          unless File.exist?(target)
             if options[:debug]
               puts "Target #{target} needs rebuilding because it does not exist on disk"
             end
@@ -307,7 +307,7 @@ module Rscons
       parts.each_index do |i|
         next if parts[i] == ""
         subpath = File.join(*parts[0, i + 1])
-        unless File.exists?(subpath)
+        unless File.exist?(subpath)
           FileUtils.mkdir_p(subpath)
           @cache["directories"][subpath] = !!options[:install]
         end

lib/rscons/cli.rb

@@ -118,13 +118,13 @@ module Rscons
 
       # Find the build script.
       if rsconscript
-        unless File.exists?(rsconscript)
+        unless File.exist?(rsconscript)
           $stderr.puts "Cannot read #{rsconscript}"
           return 1
         end
       else
         rsconscript = DEFAULT_RSCONSCRIPTS.find do |f|
-          File.exists?(f)
+          File.exist?(f)
         end
       end
 

lib/rscons/configure_op.rb

@@ -1,5 +1,6 @@
 require "fileutils"
 require "open3"
+require "set"
 
 module Rscons
   # Class to manage a configure operation.
@@ -10,9 +11,11 @@ module Rscons
     # @param script [Script]
     #   Build script.
     def initialize(script)
+      @tested_compilers = {}
       @work_dir = "#{Rscons.application.build_dir}/_configure"
       FileUtils.mkdir_p(@work_dir)
-      @log_fh = File.open("#{@work_dir}/config.log", "wb")
+      @log_file_name = "#{@work_dir}/config.log"
+      @log_fh = File.open(@log_file_name, "wb")
       cache = Cache.instance
       cache["failed_commands"] = []
       cache["configuration_data"] = {}
@@ -64,7 +67,13 @@ module Rscons
       cc = ccc.find do |cc|
         test_c_compiler(cc, options)
       end
-      complete(cc ? 0 : 1, options.merge(success_message: cc))
+      if cc
+        @tested_compilers["c"] ||= Set.new
+        @tested_compilers["c"] << cc
+      end
+      complete(cc ? 0 : 1, options.merge(
+        success_message: cc,
+        fail_message: "not found (checked #{ccc.join(", ")})"))
     end
 
     # Check for a working C++ compiler.
@@ -86,7 +95,13 @@ module Rscons
       cc = ccc.find do |cc|
         test_cxx_compiler(cc, options)
       end
-      complete(cc ? 0 : 1, options.merge(success_message: cc))
+      if cc
+        @tested_compilers["cxx"] ||= Set.new
+        @tested_compilers["cxx"] << cc
+      end
+      complete(cc ? 0 : 1, options.merge(
+        success_message: cc,
+        fail_message: "not found (checked #{ccc.join(", ")})"))
     end
 
     # Check for a working D compiler.
@@ -103,12 +118,18 @@ module Rscons
       end
       if cdc.empty?
         # Default D compiler search array.
-        cdc = %w[gdc ldc2]
+        cdc = %w[gdc ldc2 ldc]
       end
       dc = cdc.find do |dc|
         test_d_compiler(dc, options)
       end
-      complete(dc ? 0 : 1, options.merge(success_message: dc))
+      if dc
+        @tested_compilers["d"] ||= Set.new
+        @tested_compilers["d"] << dc
+      end
+      complete(dc ? 0 : 1, options.merge(
+        success_message: dc,
+        fail_message: "not found (checked #{cdc.join(", ")})"))
     end
 
     # Check for a package or configure program output.
@@ -118,7 +139,12 @@ module Rscons
       elsif program = options[:program]
         Ansi.write($stdout, "Checking '", :cyan, program, :reset, "'... ")
       end
-      program ||= "pkg-config"
+      unless program
+        program = "pkg-config"
+        unless Util.find_executable(program)
+          raise RsconsError.new("Error: executable '#{program}' not found")
+        end
+      end
       args = options[:args] || %w[--cflags --libs]
       command = [program, *args, package].compact
       stdout, _, status = log_and_test_command(command)
@@ -240,17 +266,36 @@ module Rscons
     def check_lib(lib, options = {})
       check_libpath = [nil] + (options[:check_libpath] || [])
       Ansi.write($stdout, "Checking for library '", :cyan, lib, :reset, "'... ")
-      File.open("#{@work_dir}/cfgtest.c", "wb") do |fh|
+      if @tested_compilers["d"]
-        fh.puts <<-EOF
+        source_file = "#{@work_dir}/cfgtest.d"
-          int main(int argc, char * argv[]) {
+        File.open(source_file, "wb") do |fh|
-            return 0;
+          fh.puts <<-EOF
-          }
+            int main() {
-        EOF
+              return 0;
+            }
+          EOF
+        end
+      else
+        source_file = "#{@work_dir}/cfgtest.c"
+        File.open(source_file, "wb") do |fh|
+          fh.puts <<-EOF
+            int main(int argc, char * argv[]) {
+              return 0;
+            }
+          EOF
+        end
+      end
+      ld = "${CC}"
+      %w[d cxx c].each do |language|
+        if @tested_compilers[language]
+          ld = @tested_compilers[language].first
+          break
+        end
       end
       vars = {
-        "LD" => "${CC}",
+        "LD" => ld,
         "LIBS" => [lib],
-        "_SOURCES" => "#{@work_dir}/cfgtest.c",
+        "_SOURCES" => source_file,
         "_TARGET" => "#{@work_dir}/cfgtest.exe",
       }
       status = 1
@@ -375,6 +420,8 @@ module Rscons
     #   A define to set (in CPPDEFINES) if the requested item is found.
     # @option options [String] :success_message
     #   Message to print on success (default "found").
+    # @option options [String] :fail_message
+    #   Message to print on failure (default "not found").
     def complete(status, options)
       success_message = options[:success_message] || "found"
       fail_message = options[:fail_message] || "not found"
@@ -398,7 +445,7 @@ module Rscons
           options[:on_fail].call
         end
         if should_fail
-          raise RsconsError.new("Configuration failed")
+          raise RsconsError.new("Configuration failed; log file written to #{@log_file_name}")
         end
       end
     end
@@ -482,8 +529,10 @@ module Rscons
           env = BasicEnvironment.new
           merge = {
             "DC" => dc,
-            "DCCMD" => env["DCCMD"].map {|e| e.sub(/^-o$/, "-of")},
+            "DC:-o" => "-of",
-            "LDCMD" => env["LDCMD"].map {|e| e.sub(/^-o$/, "-of")},
+            "LD:-o" => "-of",
+            "LIBDIRPREFIX" => "-L-L",
+            "LIBLINKPREFIX" => "-L-l",
             "DDEPGEN" => ["-deps=${_DEPFILE}"],
           }
           merge["OBJSUFFIX"] = [ldc_objsuffix]

lib/rscons/default_construction_variables.rb

@@ -35,8 +35,9 @@ module Rscons
     "CXXFLAGS" => [],
     "CXXSUFFIX" => %w[.cc .cpp .cxx .C],
     "DC" => "gdc",
-    "DCCMD" => %w[${DC} -c -o ${_TARGET} ${DDEPGEN} ${INCPREFIX}${D_IMPORT_PATH} ${DFLAGS} ${_SOURCES}],
+    "DC:-o" => "-o",
-    "DCCMD:direct" => %w[${DC} -o ${_TARGET} ${DDEPGEN} ${INCPREFIX}${D_IMPORT_PATH} ${DFLAGS} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
+    "DCCMD" => %w[${DC} -c ${DC:-o} ${_TARGET} ${DDEPGEN} ${INCPREFIX}${D_IMPORT_PATH} ${DFLAGS} ${_SOURCES}],
+    "DCCMD:direct" => %w[${DC} ${DC:-o} ${_TARGET} ${DDEPGEN} ${INCPREFIX}${D_IMPORT_PATH} ${DFLAGS} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
     "DDEPGEN" => %w[-MMD -MF ${_DEPFILE}],
     "DEPFILESUFFIX" => ".mf",
     "DFLAGS" => [],
@@ -46,10 +47,10 @@ module Rscons
     "D_IMPORT_PATH" => [],
     "INCPREFIX" => "-I",
     "LD" => nil,
-    "LDCMD" => %w[${LD} -o ${_TARGET} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
+    "LD:-o" => "-o",
+    "LDCMD" => %w[${LD} ${LD:-o} ${_TARGET} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
     "LDFLAGS" => [],
     "LEX" => "flex",
-    "LEXSUFFIX" => %w[.l .ll],
     "LEX_CMD" => %w[${LEX} ${LEX_FLAGS} -o ${_TARGET} ${_SOURCES}],
     "LEX_FLAGS" => [],
     "LIBDIRPREFIX" => "-L",
@@ -57,6 +58,11 @@ module Rscons
     "LIBPATH" => [],
     "LIBS" => [],
     "LIBSUFFIX" => ".a",
+    "LLVMAS" => "clang",
+    "LLVMAS_CMD" => %w[${LLVMAS} -c -o ${_TARGET} ${LLVMAS_FLAGS} ${_SOURCES}],
+    "LLVMAS_CMD:direct" => %w[${LLVMAS} -o ${_TARGET} ${LLVMAS_FLAGS} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
+    "LLVMAS_FLAGS" => [],
+    "LLVMAS_SUFFIX" => ".ll",
     "OBJDUMP" => "objdump",
     "OBJSUFFIX" => %w[.o],
     "PROGSUFFIX" => on_windows ? ".exe" : "",
@@ -84,7 +90,6 @@ module Rscons
     "SIZECMD" => %w[${SIZE} ${SIZEFLAGS} ${_SOURCES}],
     "SIZEFLAGS" => [],
     "YACC" => "bison",
-    "YACCSUFFIX" => %w[.y .yy],
     "YACC_CMD" => %w[${YACC} ${YACC_FLAGS} -o ${_TARGET} ${_SOURCES}],
     "YACC_FLAGS" => %w[-d],
   }

lib/rscons/environment.rb

@@ -74,15 +74,19 @@ module Rscons
     # Create an Environment object.
     def initialize(*args, &block)
       @id = self.class.get_id
-      if args.first.is_a?(String)
-        base_name = args.slice!(0)
-      else
-        base_name = "e.#{@id}"
-      end
       variant_keys = (Rscons.application.active_variants || []).map do |variant|
         variant[:key]
       end.compact
-      @name = [base_name, *variant_keys].join("-")
+      if args.first.is_a?(String)
+        base_name = args.slice!(0)
+        @name = [base_name, *variant_keys].join("-")
+        @build_root = "#{Rscons.application.build_dir}/#{@name}"
+      else
+        if variant_keys.size > 0
+          raise RsconsError.new("Error: an Environment with active variants must be given a name")
+        end
+        @build_root = Rscons.application.build_dir
+      end
       options = args.first || {}
       unless Cache.instance["configuration_data"]["configured"]
         raise "Project must be configured before creating an Environment"
@@ -114,8 +118,8 @@ module Rscons
         else
           :short
         end
-      @build_root = "#{Rscons.application.build_dir}/#{@name}"
       @n_threads = Rscons.application.n_threads
+      @build_steps = 0
       self.class.register(self)
       if block
         Environment.running_environment = self
@@ -276,7 +280,15 @@ module Rscons
       if extra_path = builder_class.extra_path
         extra_path = "/#{extra_path}"
       end
-      "#{@build_root}#{extra_path}/#{Util.make_relative_path("#{source_fname}#{suffix}")}".gsub("\\", "/")
+      source_fname = source_fname.gsub("\\", "/")
+      if extra_path.nil? && source_fname.start_with?("#{@build_root}/")
+        # If the source file is in the environment's build directory and no
+        # builder "extra path" is present, then just place the output file
+        # next to the source file.
+        "#{source_fname}#{suffix}"
+      else
+        "#{@build_root}/o#{extra_path}/#{Util.make_relative_path("#{source_fname}#{suffix}")}"
+      end
     end
 
     # Build all build targets specified in the Environment.
@@ -359,6 +371,7 @@ module Rscons
           @builder_sets << build_builder_set
         end
         @builder_sets.last << builder
+        @build_steps += 1
         @build_targets[target] = builder
         builder
       else
@@ -384,7 +397,11 @@ module Rscons
         expand(ud)
       end
       @user_deps[target] ||= []
-      @user_deps[target] = (@user_deps[target] + user_deps).uniq
+      (@user_deps[target] + user_deps).each do |ud|
+        unless Rscons.phony_target?(ud) || @user_deps[target].include?(ud)
+          @user_deps[target] << ud
+        end
+      end
       build_after(target, user_deps)
     end
 
@@ -610,7 +627,9 @@ module Rscons
     #
     # @return [void]
     def run_builder(builder)
-      builder.build_step ||= get_next_build_step
+      unless builder.is_a?(Rscons::Builders::Barrier)
+        builder.build_step ||= get_next_build_step
+      end
       case result = builder.run({})
       when Array
         result.each do |waititem|
@@ -636,8 +655,10 @@ module Rscons
           Cache.instance.register_build(side_effect, nil, [], self, side_effect: true)
           @side_effects.delete(side_effect)
         end
-        @build_hooks[:post].each do |build_hook_block|
+        unless builder.is_a?(Rscons::Builders::Barrier)
-          build_hook_block.call(builder)
+          @build_hooks[:post].each do |build_hook_block|
+            build_hook_block.call(builder)
+          end
         end
         process_remove_wait(builder)
       else
@@ -714,8 +735,10 @@ module Rscons
       if @builder_sets.size > 0
         if builder = @builder_sets[0].get_next_builder_to_run(targets_still_building)
           builder.vars = @varset.merge(builder.vars)
-          @build_hooks[:pre].each do |build_hook_block|
+          unless builder.is_a?(Rscons::Builders::Barrier)
-            build_hook_block.call(builder)
+            @build_hooks[:pre].each do |build_hook_block|
+              build_hook_block.call(builder)
+            end
           end
           return run_builder(builder)
         end

lib/rscons/script.rb

@@ -289,27 +289,80 @@ module Rscons
       end
 
       # Create or modify a task.
+      #
+      # @overload task(name, options = {}, &block)
+      #   @param name [String]
+      #     Task name.
+      #   @param options [Hash]
+      #     Optional task attributes.
+      #   @option options [Boolean] :autoconf
+      #     Whether to automatically configure before running this task
+      #     (default: true).
+      #   @option options [String] :desc
+      #     Description for the task.
+      #   @option options [Array<String>] :depends
+      #     Dependencies of the task.
+      #   @option options [Array<Task::Param>] :params
+      #     Task parameter definitions.
+      #
+      # The action block given will be invoked by Rscons when the task
+      # executes. It will be passed two arguments:
+      #   1) The Task object.
+      #   2) A Hash of task parameter names and values.
       def task(*args, &block)
         Util.task(*args, &block)
       end
 
       # Define a variant, or within a with_variants block, query if it is
       # active.
-      def variant(*args)
+      #
-        Rscons.application.variant(*args)
+      # @param name [String]
+      #   Variant name.
+      # @param options [Hash]
+      #   Optional parameters.
+      # @option options [String] :default
+      #   Whether the variant is enabled by default (default: true).
+      # @option options [String] :key
+      #   Variant key, used to name an Environment's build directory. If nil,
+      #   this variant will not contribute to the Environment's build directory
+      #   name.
+      def variant(name, options = {})
+        Rscons.application.variant(name, options)
       end
 
       # Check if a variant is enabled.
-      def variant_enabled?(*args)
+      #
-        Rscons.application.variant_enabled?(*args)
+      # This can be used, for example, in a configuration block to omit or
+      # include configuration checks based on which variants have been
+      # configured.
+      #
+      # @param variant_name [String]
+      #   Variant name.
+      #
+      # @return [Boolean]
+      #   Whether the requested variant is enabled.
+      def variant_enabled?(variant_name)
+        Rscons.application.variant_enabled?(variant_name)
       end
 
       # Create a variant group.
+      #
+      # @overload variant_group(name, options = {})
+      #   @param name [String]
+      #     Variant group name (optional).
+      #   @param options [Hash]
+      #     Optional variant group parameters.
+      # @overload variant_group(options = {})
+      #   @param options [Hash]
+      #     Optional variant group parameters.
       def variant_group(*args, &block)
         Rscons.application.variant_group(*args, &block)
       end
 
-      # Iterate through variants.
+      # Iterate through enabled variants.
+      #
+      # The given block is called for each combination of enabled variants
+      # across the defined variant groups.
       def with_variants(&block)
         Rscons.application.enable_variants
         Rscons.application.with_variants(&block)
@@ -349,11 +402,17 @@ module Rscons
     # Top-level DSL available to the Rsconscript.
     class TopLevelDsl < GlobalDsl
       # Set the project name.
+      #
+      # @param project_name [String]
+      #   Project name.
       def project_name(project_name)
         @script.project_name = project_name
       end
 
-      # Whether to automatically configure (default true).
+      # Set whether to automatically configure (default true).
+      #
+      # @param autoconf [Boolean]
+      #   Whether to automatically configure.
       def autoconf(autoconf)
         @script.autoconf = autoconf
       end

lib/rscons/version.rb

@@ -1,4 +1,4 @@
 module Rscons
   # Project version.
-  VERSION = "3.0.2"
+  VERSION = "3.3.0"
 end

rb/build_dist.rb

@@ -1,7 +1,10 @@
 #!/usr/bin/env ruby
 
-require "fileutils"
+require "base64"
 require "digest/md5"
+require "fileutils"
+require "stringio"
+require "zlib"
 
 if File.read("lib/rscons/version.rb") =~ /VERSION = "(.+)"/
   VERSION = $1
@@ -22,7 +25,7 @@ combine_files = lambda do |file|
       require_name = $1
       if require_name =~ %r{^#{PROG_NAME}(?:/.*)?$}
         path = "#{LIB_DIR}/#{require_name}.rb"
-        if File.exists?(path)
+        if File.exist?(path)
           unless files_processed[path]
             files_processed[path] = true
             combine_files[path]
@@ -68,11 +71,15 @@ license = File.read("LICENSE.txt").gsub(/^(.*?)$/) do |line|
   end
 end
 
-require "zlib"
-require "base64"
 compressed_script = Zlib::Deflate.deflate(stripped.join)
+hash = Digest::MD5.hexdigest(compressed_script)
 encoded_compressed_script = Base64.encode64(compressed_script).gsub("\n", "")
-hash = Digest::MD5.hexdigest(encoded_compressed_script)
+encoded_compressed_script_io = StringIO.new(encoded_compressed_script)
+commented_encoded_compressed_script = ""
+until encoded_compressed_script_io.eof?
+  line = encoded_compressed_script_io.read(64)
+  commented_encoded_compressed_script += "##{line}\n"
+end
 
 FileUtils.rm_rf(DIST)
 FileUtils.mkdir_p(DIST)
@@ -82,25 +89,53 @@ File.open("#{DIST}/#{PROG_NAME}", "wb", 0755) do |fh|
 
 #{license}
 
+BASE64CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+def base64_decode(s)
+  out = ""
+  v = 0
+  bits = 0
+  s.each_char do |c|
+    if cv = BASE64CHARS.index(c)
+      v = (v << 6) | cv
+      bits += 6
+    elsif c == "="
+      break
+    end
+    if bits >= 8
+      out += (v >> (bits - 8)).chr
+      v &= 0xFFFFFFFF >> (32 - (bits - 8))
+      bits -= 8
+    end
+  end
+  out
+end
+
 script = File.join(File.dirname(__FILE__), ".rscons-#{VERSION}-#{hash}.rb")
-unless File.exists?(script)
+unless File.exist?(script)
-  if File.read(__FILE__, mode: "rb") =~ /^#==>(.*)/
+  if File.read(__FILE__, mode: "rb") =~ /^#==>(.*)/m
     require "zlib"
-    require "base64"
     encoded_compressed = $1
-    unescaped_compressed = Base64.decode64(encoded_compressed)
+    compressed = base64_decode(encoded_compressed)
-    inflated = Zlib::Inflate.inflate(unescaped_compressed)
+    if ENV["rscons_dist_specs"]
+      require "digest/md5"
+      if Digest::MD5.hexdigest(compressed) != "#{hash}"
+        raise "Hash mismatch when decompressing rscons executable"
+      end
+    end
+    inflated = Zlib::Inflate.inflate(compressed)
     File.open(script, "wb") do |fh|
       fh.write(inflated)
     end
   else
-    raise "Could not decompress."
+    raise "Error expanding rscons executable"
   end
 end
 load script
 if __FILE__ == $0
   Rscons::Cli.new.run(ARGV)
 end
-#==>#{encoded_compressed_script}
+#==>
+#{commented_encoded_compressed_script}
 EOF
 end

rb/gen_user_guide.rb

@@ -99,7 +99,7 @@ class Generator
     end
 
     template = File.read("rb/assets/user_guide.html.erb")
-    erb = ERB.new(template, nil, "<>")
+    erb = ERB.new(template, trim_mode: "<>")
 
     if multi_page
       @pages.each_with_index do |page, page_index|

spec/rscons/cache_spec.rb

@@ -17,14 +17,14 @@ module Rscons
       it "makes directories and records any created in the cache" do
         _cache = {}
         cache = build_from(_cache)
-        expect(File).to receive(:exists?).with("one").and_return(true)
+        expect(File).to receive(:exist?).with("one").and_return(true)
-        expect(File).to receive(:exists?).with("one/two").and_return(false)
+        expect(File).to receive(:exist?).with("one/two").and_return(false)
         expect(FileUtils).to receive(:mkdir_p).with("one/two")
-        expect(File).to receive(:exists?).with("one/two/three").and_return(false)
+        expect(File).to receive(:exist?).with("one/two/three").and_return(false)
         expect(FileUtils).to receive(:mkdir_p).with("one/two/three")
-        expect(File).to receive(:exists?).with("one").and_return(true)
+        expect(File).to receive(:exist?).with("one").and_return(true)
-        expect(File).to receive(:exists?).with("one/two").and_return(true)
+        expect(File).to receive(:exist?).with("one/two").and_return(true)
-        expect(File).to receive(:exists?).with("one/two/four").and_return(false)
+        expect(File).to receive(:exist?).with("one/two/four").and_return(false)
         expect(FileUtils).to receive(:mkdir_p).with("one/two/four")
         cache.mkdir_p("one/two/three")
         cache.mkdir_p("one\\two\\four")
@@ -34,8 +34,8 @@ module Rscons
       it "handles absolute paths" do
         _cache = {}
         cache = build_from(_cache)
-        expect(File).to receive(:exists?).with("/one").and_return(true)
+        expect(File).to receive(:exist?).with("/one").and_return(true)
-        expect(File).to receive(:exists?).with("/one/two").and_return(false)
+        expect(File).to receive(:exist?).with("/one/two").and_return(false)
         expect(FileUtils).to receive(:mkdir_p).with("/one/two")
         cache.mkdir_p("/one/two")
         expect(cache.directories(false)).to eq ["/one/two"]

spec/spec_helper.rb

@@ -1,8 +1,12 @@
-if ENV["dist_specs"]
+if ENV["rscons_dist_specs"]
-  require_relative "../test/rscons"
+  require_relative "../test_run/rscons"
 else
   require "simplecov"
 
+  class MyFormatter
+    def format(*args)
+    end
+  end
   SimpleCov.start do
     add_filter "/spec/"
     add_filter "/.bundle/"
@@ -11,14 +15,10 @@ else
     else
       command_name "RSpec"
     end
-    if ENV["dist_specs"]
+    add_filter "test_run/rscons.rb"
-      add_filter "/bin/"
-      add_filter "/lib/"
-    else
-      add_filter "test/rscons.rb"
-    end
     project_name "Rscons"
     merge_timeout 3600
+    formatter(MyFormatter)
   end
 
   require "rscons"