v3.0.1

Document variants

CHANGELOG.md

@@ -1,3 +1,33 @@
+## v3.0.1
+
+### Fixes
+
+- #156 - Avoid running configure operation twice
+- #157 - Load configure task arguments before early configure operations
+- #158 - Do not configure for clean tasks when not yet configured
+
+## v3.0.0
+
+- #136 - Move rsconscache into build directory
+- #140 - Support naming environments
+- #143 - Add Size builder
+- #142 - Add 'sh' script DSL method
+- #144 - Add FileUtils class methods to script DSL
+- #145 - Support environment variable to set rscons build directory
+- #146 - Add ^^/ shortcut to top-level build directory
+- #139 - Add tasks
+- #147 - Add task options
+- #148 - Add license/copyright to distributable script
+- #150 - Add env.expand() shortcut method to expand paths and construction variables
+- #152 - Add download script method
+- #153 - Allow passing spawn options to sh
+- #154 - Record build directory absolute path
+- #149 - Add shortcut method for creating environments
+- #131 - Only configure if necessary
+- #151 - Store configure task parameters in configuration cache data
+- #137 - Add variants
+- #155 - Add build_dir script method
+
 ## v2.3.0
 
 ### New Features

Gemfile.lock

@@ -1,32 +1,38 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.4.4)
+    diff-lcs (1.5.0)
     docile (1.1.5)
-    json (2.5.1)
+    json (2.6.1)
+    psych (4.0.3)
+      stringio
     rake (13.0.6)
-    rdoc (6.3.2)
+    rdoc (6.4.0)
+      psych (>= 4.0.0)
     redcarpet (3.5.1)
-    rspec (3.10.0)
-      rspec-core (~> 3.10.0)
-      rspec-expectations (~> 3.10.0)
-      rspec-mocks (~> 3.10.0)
-    rspec-core (3.10.1)
-      rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.1)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.2)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-support (3.10.2)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
     simplecov (0.15.1)
       docile (~> 1.1.0)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
+    stringio (3.0.1)
     syntax (1.2.2)
-    yard (0.9.26)
+    webrick (1.7.0)
+    yard (0.9.27)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   ruby
@@ -43,4 +49,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.1.4
+   2.2.31

README.md

@@ -4,7 +4,39 @@
 
 Rscons (https://github.com/holtrop/rscons) is an open-source build system
 for developers.
+It supports the following features:
 
-Rscons is written in Ruby, and is inspired by [SCons](https://scons.org/) and [waf](https://waf.io/).
+  * multi-threaded job execution
+  * auto-configuration
+  * built-in builders for several common operations
+  * out-of-the-box support for C, C++, and D languages
+  * extensibility for other languages or custom builders
+  * compatible with Windows, Linux, OS X, and FreeBSD
+  * colorized output with build progress
+  * build hooks
+  * user-defined tasks with dependencies and custom parameters
+  * build variants
+
+At its core, Rscons is mainly an engine to:
+
+  * determine the proper order to perform build steps,
+  * determine whether each build target is up to date or in need of rebuild, and
+  * schedule those build steps across multiple threads as efficiently as possible.
+
+Along the way, Rscons provides a concise syntax for specifying common types of
+build steps, but also provides an extensible framework for performing
+custom build operations as well.
+
+Rscons takes inspiration from:
+
+  * [SCons](https://scons.org/)
+  * [waf](https://waf.io/)
+  * [rake](https://github.com/ruby/rake)
+  * [CMake](https://cmake.org/)
+  * [Autoconf](https://www.gnu.org/software/autoconf/)
+
+Rscons is written in Ruby.
+The only requirement to run Rscons is that the system has a Ruby interpreter
+installed.
 
 See [https://holtrop.github.io/rscons/index.html](https://holtrop.github.io/rscons/index.html) for User Guide and Installation instructions.

Rakefile.rb

@@ -35,7 +35,7 @@ task :dspec, [:example_string] => :build_dist do |task, args|
   FileUtils.mkdir_p("test")
   FileUtils.cp("dist/rscons", "test/rscons.rb")
   ENV["dist_specs"] = "1"
-  Rake::Task["spec"].execute(args.example_string)
+  Rake::Task["spec"].execute(args)
   ENV.delete("dist_specs")
   FileUtils.rm_f(Dir.glob(".rscons-*"))
 end

build_tests/configure/configure_with_top_level_env.rb

@@ -0,0 +1,6 @@
+configure do
+  check_c_compiler
+end
+env do |env|
+  puts "Prefix is #{Task["configure"]["prefix"]}"
+end

build_tests/library/Rsconscript

@@ -1,4 +1,7 @@
 env(echo: :command) do |env|
-  env.Program('library.exe', ['lib.a', 'three.c'])
-  env.Library("lib.a", ['one.c', 'two.c'], 'CPPFLAGS' => ['-Dmake_lib'])
+  env["LIBS"] << "mylib"
+  env["LIBPATH"] << "."
+  env.Program("library.exe", "one.c")
+  env.depends("library.exe", "libmylib.a")
+  env.Library("libmylib.a", ["two.c", "three.c"], "CPPFLAGS" => ["-Dmake_lib"])
 end

build_tests/library/one.c

@@ -1,8 +1,11 @@
 #include <stdio.h>
 
-#ifdef make_lib
+void two();
+void three();
+
 int main(int argc, char *argv[])
 {
+    two();
     printf("Library\n");
+    three();
 }
-#endif

build_tests/library/override_arcmd.rb

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

build_tests/library/three.c

@@ -0,0 +1,3 @@
+void three(void)
+{
+}

build_tests/library/two.c

@@ -0,0 +1,3 @@
+void two(void)
+{
+}

build_tests/simple/clean.rb

@@ -0,0 +1,7 @@
+env do |env|
+  env.Program('simple.exe', Dir['*.c'])
+end
+
+clean do
+  puts "custom clean action"
+end

build_tests/simple/env_in_task.rb

@@ -0,0 +1,5 @@
+default do
+  env do |env|
+    env.Program('simple.exe', Dir['*.c'])
+  end
+end

build_tests/simple/link_flag_change.rb

@@ -1,5 +1,6 @@
 env(echo: :command) do |env|
   env["LD"] = "gcc"
+  mkdir_p("libdir")
   env["LIBPATH"] += ["libdir"]
   env.Program('simple.exe', Dir['*.c'])
 end

build_tests/two_sources/two.c

@@ -1,3 +1,6 @@
 #ifdef ONE
 #error ONE should not be defined
 #endif
+void two(void)
+{
+}

build_tests/typical/build_dir.rb

@@ -0,0 +1,3 @@
+default do
+  touch "#{build_dir}/a.file"
+end

build_tests/variants/default.rb

@@ -0,0 +1,8 @@
+variant "debug", default: false
+variant "release"
+
+with_variants do
+  env "prog" do |env|
+    env.Program("^/prog.exe", "prog.c")
+  end
+end

build_tests/variants/variant_enabled.rb

@@ -0,0 +1,14 @@
+variant "one"
+variant "two", default: false
+
+configure do
+  if variant_enabled?("one")
+    puts "one enabled"
+  end
+  if variant_enabled?("two")
+    puts "two enabled"
+  end
+  if variant_enabled?("three")
+    puts "three enabled"
+  end
+end

doc/user_guide.md

@@ -12,6 +12,7 @@ It supports the following features:
   * colorized output with build progress
   * build hooks
   * user-defined tasks with dependencies and custom parameters
+  * build variants
 
 At its core, Rscons is mainly an engine to:
 
@@ -67,8 +68,8 @@ incorrect decision being made to not rebuild when a rebuild is necessary.
 ### Build Flexibility
 
 Rscons supports multiple configurations of compilation flags or build options
-across multiple environments to build output files in different ways according
-to the user's desire.
+across multiple environments or build variants to build output files in
+different ways according to the user's desire.
 For example, the same source files can be built into a release executable, but
 also compiled with different compilation flags or build options into a test
 executable.
@@ -143,17 +144,52 @@ different version control systems):
 
 Rscons is typically invoked from the command-line as `./rscons`.
 
-    ./rscons [global options] [[task] [task options] ...]
+    Usage: ./rscons [global options] [[task] [task options] ...]
 
     Global options:
-      -b BUILD, --build=BUILD     Set build directory (default: build)
-      -f FILE                     Use FILE as Rsconscript
-      -F, --show-failure          Show failed command log from previous build and exit
-      -h, --help                  Show rscons help and exit
-      -j N, --nthreads=N          Set number of threads
-      -r COLOR, --color=COLOR     Set color mode (off, auto, force)
-      -v, --verbose               Run verbosely
-      --version                   Show rscons version and exit
+      -A, --all
+        Show all tasks (even those without descriptions) in task list. Use in
+        conjunction with the -T argument.
+
+      -b BUILD, --build=BUILD
+        Set build directory (default: build).
+
+      -e VS, --variants=VS
+        Enable or disable variants. VS is a comma-separated list of variant
+        entries. If the entry begins with "-" the variant is disabled instead of
+        enabled. If the full list begins with "+" or "-" then it modifies the
+        variants that are enabled by default by only enabling or disabling the
+        listed variants. Otherwise, the enabled set of variants is as given and
+        any variants not listed are disabled. The set of enabled variants is
+        remembered from when the project is configured.
+
+      -f FILE
+        Use FILE as Rsconscript.
+
+      -F, --show-failure
+        Show failed command log from previous build and exit (does not load build
+        script).
+
+      -h, --help
+        Show rscons help and exit (does not load build script).
+
+      -j N, --nthreads=N
+        Set number of threads (local default: 16).
+
+      -r COLOR, --color=COLOR
+        Set color mode (off, auto, force).
+
+      -T, --tasks
+        Show task list and parameters and exit (loads build script). By default
+        only tasks with a description are listed. Use -AT to show all tasks whether
+        they have a description or not.
+
+      -v, --verbose
+        Run verbosely. This causes Rscons to print the full build command used by
+        each builder.
+
+      --version
+        Show rscons version and exit (does not load build script).
 
 The user can list any number of tasks on the command line.
 Any parameters beginning with a "-" that follow a task are interpreted as task
@@ -181,6 +217,19 @@ Rscons execution.
 The user can also invoke Rscons with the `-v` global command-line option which
 will cause Rscons to print each command it is executing.
 
+## Rscons Operation Phases
+
+When Rscons executes, it performs the following phases:
+
+  - Parse the command line.
+    - This is the last step if --help, --version, or --show-failure is specified.
+  - Load the build script.
+    - This is the last step if --tasks is specified.
+  - Configure the project by running the `configure` task if necessary (the
+    project has not yet been configured, autoconf is set to true, and the user
+    is requesting to execute a task that is marked with autoconf set to true)
+  - Execute user-requested tasks.
+
 #> The Build Script
 
 Rscons looks for instructions for what to build by reading a build script file
@@ -188,10 +237,8 @@ called `Rsconscript` (or `Rsconscript.rb`).
 Here is a simple example `Rsconscript` file:
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env.Program("myprog.exe", glob("src/**/*.c"))
-  end
 end
 ```
 
@@ -203,7 +250,7 @@ The `Rsconscript` file is a Ruby script.
 
 ##> Tasks
 
-Tasks are the high-level user interface for performing functionality in a build
+Tasks are a high-level user interface for performing functionality in a build
 script.
 Tasks can create Environments that perform compilation/linking steps.
 Tasks can also execute arbitrary commands or perform any miscellaneous logic.
@@ -219,7 +266,7 @@ Example:
 
 ```ruby
 task "build" do
-  Environment.new do |env|
+  env do |env|
     env.Program("^^/proj.elf", glob("src/**/*.c"))
   end
 end
@@ -240,9 +287,13 @@ 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.
 
+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}).
+
 ###> Task Parameters
 
-Tasks can also take parameters.
+Tasks can accept parameters.
 Parameters are defined by the build script author, and have default values.
 The user can override parameter values on the command line.
 
@@ -261,7 +312,7 @@ task "build", params: [
   param("myparam", "defaultvalue", true, "My special parameter"),
   param("xyz", nil, false, "Enable the xyz feature"),
 ] do |task, params|
-  Environment.new do |env|
+  env do |env|
     env["CPPDEFINES"] << "SOMEMACRO=#{params["myparam"]}"
     if params["flag"]
       env["CPPDEFINES"] << "ENABLE_FEATURE_XYZ"
@@ -395,12 +446,13 @@ end
 See ${#Configuring the Project} for more details on how to make use of the
 configuration functionality that Rscons provides.
 
+Configure blocks must be defined in the Rsconscript file before any
+environments are created.
+
 ####> Default Task
 
 The `default` task is special in that Rscons will execute it if no other task
 has been requested by the user on the command line.
-It is entirely feasible for the default task to be the only task defined for a
-project, and simple projects may wish to do just that.
 
 The default task can also be used to declare a dependency on another task that
 would effectively become the default.
@@ -432,7 +484,8 @@ It will not remove the cached configuration options.
 The `distclean` task is built-in to Rscons.
 It removes all built target files and all cached configuration options.
 Generally it will get the project directory back to the state it was in when
-unpacked before any configuration or build operations took place.
+unpacked or checked out, before any configuration or build operations took
+place.
 It will not remove items installed by an Install builder.
 
 ####> Install Task
@@ -734,17 +787,18 @@ If set, a build define of the specified String will be added to the
 ##> Building Targets
 
 Building target files is accomplished by using Environments.
-Environments are typically created within the default task or any user-defined
-tasks.
+Environments can be created at the top level of the build script, or from
+within a task action block.
 
-Here is an example `default` task block demonstrating how to create an
-Environment and register a build target:
+Environments are created with the
+[`env`](../yard/Rscons/Script/GlobalDsl.html#env-instance_method) build script
+method.
+Here is an example build script that creates an Environment and registers a
+Program build target:
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env.Program("myprog.exe", glob("src/**/*.c"))
-  end
 end
 ```
 
@@ -759,24 +813,21 @@ An Environment includes:
   - a collection of construction variables
   - a collection of build hooks
   - a collection of user-registered build targets
-  - a build root
+  - a build root directory
 
 All build targets must be registered within an `Environment`.
 If the user does not specify a name for the environment, a name will be
 automatically generated based on the Environment's internal ID, for example
 "e.1".
-The Environment's build root is a directory created within the top-level
-Rscons build directory.
-It is based on the Environment name.
+The Environment's build root is a directory with the same name as the
+Environment, created within the top-level Rscons build directory.
 By default it holds all intermediate files generated by Rscons that are needed
 to produce a user-specified build target.
 For example, for the `Rsconscript`:
 
 ```ruby
-default do
-  Environment.new(name: "myproj") do |env|
+env "myproj" do |env|
   env.Program("myprog.exe", glob("src/**/*.c"))
-  end
 end
 ```
 
@@ -786,6 +837,12 @@ Assuming a top-level build directory of "build", the Environment's build root
 would be "build/myproj".
 This keeps the intermediate generated build artifacts separate from the source
 files.
+Source and target paths passed to a Builder (e.g. Program) can begin with "^/"
+to indicate that Rscons should expand those paths to be relative to the
+Environment's build root.
+If a source or target path passed to a Builder begins with "^^/", it is
+expanded to be relative to the Rscons top-level build directory (but outside
+the Environment's build root).
 
 ###> Construction Variables
 
@@ -797,11 +854,9 @@ construction variables.
 Example:
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env["CCFLAGS"] += %w[-O2 -Wall]
   env["LIBS"] += %w[m]
-  end
 end
 ```
 
@@ -813,6 +868,7 @@ It also instructs the linker to link against the `m` library.
 
   * uppercase strings - the default construction variables that Rscons uses
   * strings beginning with "_" - set and used internally by builders
+  * lowercase strings with a ":" as "#{task_name}:#{parameter_name}" - set to task parameter values
   * symbols, lowercase strings - reserved as user-defined construction variables
 
 ###> Builders
@@ -834,7 +890,8 @@ The `target` parameter is the path to the output file or directory.
 The `sources` parameter is the path or paths to the input file(s) to be used
 by the builder.
 In the `target` and `sources` parameters, the user can explicitly refer to a
-path within the Environment's build root by beginning the path with "^/".
+path within the Environment's build root by beginning the path with "^/", or to
+a path within the Rscons top-level built directory by beginning with "^^/".
 The `vars` parameter is an optional Hash which can include construction
 variables to be used for this build target.
 Any construction variable values specified in this parameter will override
@@ -1099,7 +1156,7 @@ and flags can be specified with `SIZEFLAGS`.
 
 ###> Phony Targets
 
-rscons supports phony build targets.
+Rscons supports phony build targets.
 Normally, a builder produces an output file, and executes whenever the input
 files or command have changed.
 A phony build target can be used to register a builder that does not produce
@@ -1142,8 +1199,7 @@ build target or source file names.
 Example:
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env["CFLAGS"] << "-Wall"
   env.add_build_hook do |builder|
     # Compile sources from under src/tests without the -Wall flag.
@@ -1152,7 +1208,6 @@ default do
     end
   end
   env.Program("program.exe", glob("src/**/*.c"))
-  end
 end
 ```
 
@@ -1166,7 +1221,7 @@ Build hooks and post-build hooks can register new build targets.
 
 ###> Barriers
 
-Normally Rscons will parallelize all builders.
+Normally Rscons will parallelize all builders executed within an Environment.
 A barrier can be used to separate sets of build targets.
 All build targets registered before the barrier is created will be built before
 Rscons will schedule any build targets after the barrier.
@@ -1176,14 +1231,117 @@ In other words, build targets are not parallelized across a barrier.
 env.barrier
 ```
 
+##> Variants
+
+Rscons supports build variants.
+Variants can be used to built multiple variations of the same item with a
+specific change.
+For example, a desktop application with the same sources could be built to
+target KDE or GNOME using build variants.
+It is up to the build script author to define the variants and what effect they
+have on the build.
+
+This build script defines "kde" and "gnome" variants:
+
+```ruby
+variant "kde"
+variant "gnome"
+
+with_variants do
+  env "prog" do |env|
+    if variant "kde"
+      env["CPPDEFINES"] << "KDE"
+    end
+    if variant "gnome"
+      env["CPPDEFINES"] << "GNOME"
+    end
+    env.Program("^/prog.exe", "src/**/*.cpp")
+  end
+end
+```
+
+The `variant` build script method has two uses:
+
+  * At the top of the build script, it defines a variant.
+  * Within a `with_variants` block, it queries for whether the given variant is
+    active.
+
+The `with_variants` build script method allows the power of variants to be
+harnessed.
+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.
+When an Environment is created within a `with_variants` block, the
+Environment's name has the active variant(s) appended to the given Environment
+name (if any), 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
+source.
+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.
+
+Variants are enabled by default, but can be disabled by passing a `false` value
+to the `:default` option of the `variant` method.
+For example:
+
+```ruby
+${include build_tests/variants/default.rb}
+```
+
+The `rscons` command line interface provides a `-e`/`--variants` argument which
+allows the user to enable a different set of variants from those enabled by
+default according to the build script author.
+This argument accepts a comma-separated list of variants to enable.
+Each entry in the list can begin with "-" to disable the variant instead of
+enable it.
+If the list begins with "+" or "-", then the entire given list modifies the
+defaults given in the build script.
+Otherwise, it exactly specifies which variants should be enabled, and any
+variant not listed is disabled.
+
+When the project is configured, the set of enabled variants is recorded and
+remembered for later Rscons invocations.
+This way, a user working on a single variant of a project does not need to
+specify the `-e`/`--variants` option on each build operation.
+
+The `variant_enabled?` build script method can be called to query whether the
+given variant is enabled.
+
+###> Variant Groups
+
+Variants may be grouped, which allows the build script author to define
+multiple combinations of desired variations to build with.
+For example:
+
+```ruby
+${include build_tests/variants/multiple_groups.rb}
+```
+
+This build script executes the block given to `with_variants` four times and
+results in four Environments being created:
+
+  * prog-kde-debug
+  * prog-kde-release
+  * prog-gnome-debug
+  * prog-gnome-release
+
+The command `./rscons -e-debug` would build just "prog-kde-release" and "prog-gnome-release".
+The command `./rscons --variants kde,release` would build just "prog-kde-release".
+
 ##> Build Script Methods
 
 `rscons` provides several methods that a build script can use.
 
   * `autoconf` (see ${#Configure Task})
+  * `build_dir` which returns the path to the top-level Rscons build directory
   * `clean` (see ${#Clean Task})
   * `configure` (see ${#Configure Task})
   * `default` (see ${#Default Task})
+  * `download` (see ${#Downloading Files: The download Method})
   * `distclean` (see ${#Distclean Task})
   * `glob` (see ${#Finding Files: The glob Method})
   * `install` (see ${#Install Task})
@@ -1197,6 +1355,10 @@ env.barrier
   * `sh` (see (${#Executing Commands: The sh Method})
   * `task` (see ${#Tasks})
   * `uninstall` (see ${#Uninstall Task})
+  * `variant` (see ${#Variants})
+  * `variant_enabled?` (see ${#Variant Groups})
+  * `variant_group` (see ${#Variant Groups})
+  * `with_variants` (see ${#Variant Groups})
 
 Additionally, the following methods from the Ruby
 [FileUtils](https://ruby-doc.org/stdlib-3.1.0/libdoc/fileutils/rdoc/FileUtils.html)
@@ -1237,16 +1399,39 @@ rather than file system directory ordering).
 Example use:
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env.Program("mytests", glob("src/**/*.cc", "test/**/*.cc"))
-  end
 end
 ```
 
 This example would build the `mytests` executable from all `.cc` source files
 found recursively under the `src` or `test` directory.
 
+###> Downloading Files: The download Method
+
+The [`download`](../yard/Rscons/Script/GlobalDsl.html#download-instance_method)
+method can be used to download a file from a given URL.
+
+Example use:
+
+```ruby
+default do
+  download "https://ftp.gnu.org/gnu/gcc/gcc-#{gcc_version}/gcc-#{gcc_version}.tar.xz",
+    "#{build_dir}/gcc-#{gcc_version}.tar.xz",
+    sha256_sum: gcc_checksum
+end
+```
+
+The `download` method downloads the file specified by the URL in the first
+parameter, and writes it to the local file specified by the second parameter.
+If the `:sha256sum` option is given, this causes two changes to the default
+behavior:
+
+  * If Rscons finds the local file and it already has this checksum, then the
+    file will not be downloaded again.
+  * After downloading, Rscons verifies that the checksum matches what is given
+    and exits with an error if it does not.
+
 ###> PATH Management
 
 `rscons` provides methods for management of the `PATH` environment variable.
@@ -1354,6 +1539,18 @@ default do
 end
 ```
 
+Options that Ruby's `spawn` method accepts can also be passed in to the `sh`
+method.
+For example, to execute the given command with a different working directory,
+the `:chdir` option can be specified:
+
+```ruby
+default do
+  # Execute 'ls' from within the 'src' directory:
+  sh "ls", chdir: "src"
+end
+```
+
 ##> Extending Rscons
 
 ### Adding New Languages
@@ -1406,7 +1603,7 @@ class Rscons::Builders::Mine < Rscons::Builder
 end
 
 default do
-  Environment.new do |env|
+  env do |env|
     env.add_builder(Rscons::Builders::Mine)
   end
 end
@@ -1429,7 +1626,7 @@ Rscons::DEFAULT_BUILDERS << :Special
 load "SpecialBuilder.rb"
 
 default do
-  Environment.new do |env|
+  env do |env|
     # A build target using the "Special" builder can be registered.
     env.Special("target", "source")
   end
@@ -1656,40 +1853,36 @@ ${include lib/rscons/default_construction_variables.rb}
 ### Example: Building a C Program
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env["CFLAGS"] << "-Wall"
   env.Program("program", glob("src/**/*.c"))
-  end
 end
 ```
 
 ### Example: Building a D Program
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env["DFLAGS"] << "-Wall"
   env.Program("program", glob("src/**/*.d"))
-  end
 end
 ```
 
 ### Example: Cloning an Environment
 
 ```ruby
-default do
-  main_env = Environment.new do |env|
-    env["CFLAGS"] = ["-DSOME_DEFINE", "-O3"]
+main_env = env do |env|
+  env["CFLAGS"] = ["-fshort-enums", "-O3"]
+  env["CPPDEFINES"] << "SOME_DEFINE"
   env["LIBS"] = ["SDL"]
   env.Program("program", glob("src/**/*.cc"))
-  end
+end
 
-  debug_env = main_env.clone do |env|
+test_env = main_env.clone do |env|
   env["CFLAGS"] -= ["-O3"]
   env["CFLAGS"] += ["-g", "-O0"]
-    env.Program("program-debug", glob("src/**/*.cc"))
-  end
+  env["CPPDEFINES"] = "ENABLE_TESTS"
+  env.Program("program-test", glob("src/**/*.cc"))
 end
 ```
 
@@ -1709,20 +1902,17 @@ EOF
   end
 end
 
-default do
-  Environment.new do |env|
+env do |env|
   env.add_builder(GenerateFoo)
   env.GenerateFoo("foo.h", [])
   env.Program("a.out", glob("*.c"))
-  end
 end
 ```
 
 ### Example: Using different compilation flags for some sources
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env["CFLAGS"] = ["-O3", "-Wall"]
   env.add_build_hook do |builder|
     if builder.sources.first =~ %r{src/third-party/}
@@ -1730,27 +1920,104 @@ default do
     end
   end
   env.Program("program", glob("**/*.cc"))
-  end
 end
 ```
 
 ### Example: Creating a static library
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env.Library("mylib.a", glob("src/**/*.c"))
-  end
 end
 ```
 
 ### Example: Creating a C++ parser source from a Yacc/Bison input file
 
 ```ruby
-default do
-  Environment.new do |env|
+env do |env|
   env.CFile("^/parser.tab.cc", "parser.yy")
+end
+```
+
+### Example: GCC Cross Compiler
+
+```ruby
+binutils_version = "2.35"
+binutils_checksum = "1b11659fb49e20e18db460d44485f09442c8c56d5df165de9461eb09c8302f85"
+gcc_version = "10.2.0"
+gcc_checksum = "b8dd4368bb9c7f0b98188317ee0254dd8cc99d1e3a18d0ff146c855fe16c1d8c"
+install_path = File.expand_path("i686-elf-gcc")
+target = "i686-elf"
+path_prepend "#{install_path}/bin"
+
+configure do
+  check_c_compiler "gcc"
+  check_program "make"
+  check_program "bison"
+  check_program "flex"
+  check_program "texi2any", on_fail: "Install the texinfo package"
+  check_program "wget"
+  check_lib "gmp", on_fail: "Install the libgmp-dev package"
+  check_lib "mpc", on_fail: "Install the libmpc-dev package"
+  check_lib "mpfr", on_fail: "Install the libmpfr-dev package"
+end
+
+default do
+  unless Dir.exist?(install_path)
+
+    # Download archives.
+    download "https://ftp.gnu.org/gnu/binutils/binutils-#{binutils_version}.tar.xz",
+      "#{build_dir}/binutils-#{binutils_version}.tar.xz",
+      sha256sum: binutils_checksum
+
+    download "https://ftp.gnu.org/gnu/gcc/gcc-#{gcc_version}/gcc-#{gcc_version}.tar.xz",
+      "#{build_dir}/gcc-#{gcc_version}.tar.xz",
+      sha256sum: gcc_checksum
+
+    # Extract archives.
+    sh "tar", "xJf", "binutils-#{binutils_version}.tar.xz",
+      chdir: build_dir
+
+    sh "tar", "xJf", "gcc-#{gcc_version}.tar.xz",
+      chdir: build_dir
+
+    # Build binutils.
+    rm_rf "#{build_dir}/build-binutils"
+    mkdir_p "#{build_dir}/build-binutils"
+    cd "#{build_dir}/build-binutils" do
+      sh %W[../binutils-#{binutils_version}/configure
+        --target=#{target} --prefix=#{install_path} --with-sysroot --disable-nls
+        --disable-werror]
+      sh "make"
+      sh "make install"
     end
+
+    # Build gcc.
+    rm_rf "#{build_dir}/build-gcc"
+    mkdir_p "#{build_dir}/build-gcc"
+    cd "#{build_dir}/build-gcc" do
+      sh %W[../gcc-#{gcc_version}/configure
+        --target=#{target} --prefix=#{install_path} --disable-nls
+        --enable-languages=c,c++ --without-headers]
+      sh "make all-gcc"
+      sh "make all-target-libgcc"
+      sh "make install-gcc"
+      sh "make install-target-libgcc"
+    end
+  end
+end
+
+clean do
+  rm_f "#{build_dir}/binutils-#{binutils_version}.tar.xz"
+  rm_rf "#{build_dir}/binutils-#{binutils_version}"
+  rm_rf "#{build_dir}/build-binutils"
+  rm_f "#{build_dir}/gcc-#{gcc_version}.tar.xz"
+  rm_rf "#{build_dir}/gcc-#{gcc_version}"
+  rm_rf "#{build_dir}/build-gcc"
+end
+
+distclean do
+  rm_rf install_path
 end
 ```
 

lib/rscons/application.rb

@@ -42,6 +42,16 @@ module Rscons
       @variant_groups = []
     end
 
+    # Return if Rscons is in the task execution phase.
+    #
+    # @api private
+    #
+    # @return [Boolean]
+    #   If Rscons is in the task execution phase.
+    def task_execution_phase?
+      @task_execution_phase
+    end
+
     # Run the application.
     #
     # Execute user-specified tasks.
@@ -54,13 +64,16 @@ module Rscons
     #   List of task(s) to execute.
     # @param show_tasks [Boolean]
     #   Flag to show tasks and exit.
+    # @param all_tasks [Boolean]
+    #   Flag to show all tasks (not just those with a description).
     # @param enabled_variants [String]
     #   User-specified variants list.
     #
     # @return [Integer]
     #   Process exit code (0 on success).
-    def run(rsconscript, tasks_and_params, show_tasks, enabled_variants)
+    def run(rsconscript, tasks_and_params, show_tasks, all_tasks, enabled_variants)
       Cache.instance["failed_commands"] = []
+      @tasks_and_params = tasks_and_params
       @enabled_variants = enabled_variants
       if enabled_variants == "" && !tasks_and_params.include?("configure")
         if cache_enabled_variants = Cache.instance["configuration_data"]["enabled_variants"]
@@ -68,13 +81,16 @@ module Rscons
         end
       end
       @script = Script.new
+      if should_load_script
         @script.load(rsconscript)
+        enable_variants
+      end
       if show_tasks
-        show_script_tasks
+        show_script_tasks(all_tasks)
         return 0
       end
-      apply_task_params(tasks_and_params)
-      enable_variants
+      apply_task_params(false)
+      @task_execution_phase = true
       if tasks_and_params.empty?
         check_process_environments
         if Task.tasks["default"]
@@ -156,8 +172,8 @@ module Rscons
     def distclean
       cache = Cache.instance
       clean
-      FileUtils.rm_rf(@build_dir)
       cache.clear
+      FileUtils.rm_rf(@build_dir)
     end
 
     # Check if the project needs to be configured.
@@ -166,6 +182,7 @@ module Rscons
     #
     # @return [void]
     def check_configure
+      apply_task_params(true)
       enable_variants
       unless Cache.instance["configuration_data"]["configured"]
         if @script.autoconf
@@ -192,11 +209,10 @@ module Rscons
     #
     # @api private
     #
-    # @param options [Hash]
-    #   Options.
-    #
     # @return [void]
     def configure
+      unless @_configured
+        @_configured = true
         co = ConfigureOp.new(@script)
         begin
           @script.configure(co)
@@ -207,6 +223,7 @@ module Rscons
         Cache.instance["configuration_data"]["enabled_variants"] = @enabled_variants
         co.close(true)
       end
+    end
 
     # Remove installed files.
     #
@@ -305,13 +322,8 @@ module Rscons
           block[]
           @active_variants = nil
         else
-          enabled_variants = @variant_groups[iter_variants.size][:variants].select do |variant|
-            variant[:enabled]
-          end
-          if enabled_variants.empty?
-            iter_vgs[iter_variants + [nil]]
-          else
-            enabled_variants.each do |variant|
+          @variant_groups[iter_variants.size][:variants].each do |variant|
+            if variant[:enabled]
               iter_vgs[iter_variants + [variant]]
             end
           end
@@ -327,15 +339,8 @@ module Rscons
         enabled_count = variant_group[:variants].count do |variant|
           variant[:enabled]
         end
-        if enabled_count == 0 && !variant_group[:optional]
-          message = "No variants enabled for non-optional variant group"
-          if variant_group[:name]
-            message += " #{variant_group[:name].inspect}"
-          end
-          raise RsconsError.new(message)
-        end
-        if enabled_count > 1 && variant_group[:exclusive]
-          message = "Multiple variants enabled for exclusive variant group"
+        if enabled_count == 0
+          message = "No variants enabled for variant group"
           if variant_group[:name]
             message += " #{variant_group[:name].inspect}"
           end
@@ -352,10 +357,10 @@ module Rscons
       end
     end
 
-    def show_script_tasks
+    def show_script_tasks(all_tasks)
       puts "Tasks:"
       Task[].sort.each do |task_name, task|
-        if task.description
+        if task.description || all_tasks
           puts %[  #{sprintf("%-27s", task_name)} #{task.description}]
           task.params.each do |param_name, param|
             arg_text = "--#{param_name}"
@@ -366,10 +371,20 @@ module Rscons
           end
         end
       end
+
+      unless @variant_groups.empty?
+        @variant_groups.each do |variant_group|
+          puts "\nVariant group#{variant_group[:name] ? " '#{variant_group[:name]}'" : ""}:"
+          variant_group[:variants].each do |variant|
+            puts "  #{variant[:name]}#{variant[:enabled] ? " (enabled)" : ""}"
+          end
+        end
+      end
     end
 
-    def apply_task_params(tasks_and_params)
-      tasks_and_params.each do |task_name, task_params|
+    def apply_task_params(only_configure)
+      @tasks_and_params.each do |task_name, task_params|
+        unless only_configure && task_name != "configure"
           task_params.each do |param_name, param_value|
             if param = Task[task_name].params[param_name]
               Task[task_name].set_param_value(param_name, param_value)
@@ -379,6 +394,14 @@ module Rscons
           end
         end
       end
+    end
+
+    def should_load_script
+      return true if @tasks_and_params.empty?
+      return true if Cache.instance["configuration_data"]["configured"]
+      return false if (@tasks_and_params.keys - %w[distclean clean uninstall]).empty?
+      true
+    end
 
   end
 

lib/rscons/cache.rb

@@ -101,6 +101,7 @@ module Rscons
     #
     # @return [void]
     def write
+      return unless Dir.exist?(File.dirname(cache_file))
       @cache["version"] = VERSION
       File.open(cache_file, "w") do |fh|
         fh.puts(JSON.dump(@cache))

lib/rscons/cli.rb

@@ -54,10 +54,15 @@ module Rscons
     def run_toplevel(argv)
       rsconscript = nil
       show_tasks = false
+      all_tasks = false
       enabled_variants = ""
 
       OptionParser.new do |opts|
 
+        opts.on("-A", "--all") do
+          all_tasks = true
+        end
+
         opts.on("-b", "--build DIR") do |build_dir|
           Rscons.application.build_dir = build_dir
         end
@@ -132,7 +137,7 @@ module Rscons
       end
 
       begin
-        Rscons.application.run(rsconscript, tasks_and_params, show_tasks, enabled_variants)
+        Rscons.application.run(rsconscript, tasks_and_params, show_tasks, all_tasks, enabled_variants)
       rescue RsconsError => e
         Ansi.write($stderr, :red, e.message, :reset, "\n")
         1
@@ -144,16 +149,49 @@ module Rscons
 Usage: #{$0} [global options] [[task] [task options] ...]
 
 Global options:
-  -b BUILD, --build=BUILD     Set build directory (default: build)
-  -e VS, --variants=VS        Enable or disable variants
-  -f FILE                     Use FILE as Rsconscript
-  -F, --show-failure          Show failed command log from previous build and exit
-  -h, --help                  Show rscons help and exit
-  -j N, --nthreads=N          Set number of threads (local default: #{Rscons.application.n_threads})
-  -r COLOR, --color=COLOR     Set color mode (off, auto, force)
-  -T, --tasks                 Show task list and parameters and exit
-  -v, --verbose               Run verbosely
-  --version                   Show rscons version and exit
+  -A, --all
+    Show all tasks (even those without descriptions) in task list. Use in
+    conjunction with the -T argument.
+
+  -b BUILD, --build=BUILD
+    Set build directory (default: build).
+
+  -e VS, --variants=VS
+    Enable or disable variants. VS is a comma-separated list of variant
+    entries. If the entry begins with "-" the variant is disabled instead of
+    enabled. If the full list begins with "+" or "-" then it modifies the
+    variants that are enabled by default by only enabling or disabling the
+    listed variants. Otherwise, the enabled set of variants is as given and
+    any variants not listed are disabled. The set of enabled variants is
+    remembered from when the project is configured.
+
+  -f FILE
+    Use FILE as Rsconscript.
+
+  -F, --show-failure
+    Show failed command log from previous build and exit (does not load build
+    script).
+
+  -h, --help
+    Show rscons help and exit (does not load build script).
+
+  -j N, --nthreads=N
+    Set number of threads (local default: #{Rscons.application.n_threads}).
+
+  -r COLOR, --color=COLOR
+    Set color mode (off, auto, force).
+
+  -T, --tasks
+    Show task list and parameters and exit (loads build script). By default
+    only tasks with a description are listed. Use -AT to show all tasks whether
+    they have a description or not.
+
+  -v, --verbose
+    Run verbosely. This causes Rscons to print the full build command used by
+    each builder.
+
+  --version
+    Show rscons version and exit (does not load build script).
 EOF
     end
 

lib/rscons/environment.rb

@@ -72,24 +72,6 @@ module Rscons
     attr_reader :name
 
     # Create an Environment object.
-    #
-    # @overload initialize(name, options)
-    # @overload initialize(options)
-    #
-    # @param name [String]
-    #   Environment name. This determines the folder name used to store all
-    #   environment build files under the top-level build directory.
-    # @param options [Hash]
-    # @option options [Symbol] :echo
-    #   :command, :short, or :off (default :short)
-    # @option options [Boolean] :exclude_builders
-    #   Whether to omit adding default builders (default false)
-    # @option options [String, Array<String>] :use
-    #   Use flag(s). If specified, any configuration flags which were saved
-    #   with a corresponding `:use` value will be applied to this Environment.
-    #
-    # If a block is given, the Environment object is yielded to the block and
-    # when the block returns, the {#process} method is automatically called.
     def initialize(*args, &block)
       @id = self.class.get_id
       if args.first.is_a?(String)
@@ -102,7 +84,6 @@ module Rscons
       end.compact
       @name = [base_name, *variant_keys].join("-")
       options = args.first || {}
-      Rscons.application.check_configure
       unless Cache.instance["configuration_data"]["configured"]
         raise "Project must be configured before creating an Environment"
       end

lib/rscons/script.rb

@@ -10,6 +10,14 @@ module Rscons
         @script = script
       end
 
+      # Get the Rscons build directory path.
+      #
+      # @return [String]
+      #   Rscons build directory path.
+      def build_dir
+        Rscons.application.build_dir
+      end
+
       # Return a list of paths matching the specified pattern(s).
       #
       # A pattern can contain a "/**" component to recurse through directories.
@@ -94,8 +102,49 @@ module Rscons
       end
 
       # Create an environment.
+      #
+      # @overload env(name, options)
+      #   @param name [String]
+      #     Environment name. This determines the folder name used to store all
+      #     environment build files under the top-level build directory.
+      #   @param options [Hash]
+      #   @option options [Symbol] :echo
+      #     :command, :short, or :off (default :short)
+      #   @option options [Boolean] :exclude_builders
+      #     Whether to omit adding default builders (default false)
+      #   @option options [String, Array<String>] :use
+      #     Use flag(s). If specified, any configuration flags which were saved
+      #     with a corresponding `:use` value will be applied to this
+      #     Environment.
+      #
+      # @overload env(options)
+      #   @param options [Hash]
+      #   @option options [Symbol] :echo
+      #     :command, :short, or :off (default :short)
+      #   @option options [Boolean] :exclude_builders
+      #     Whether to omit adding default builders (default false)
+      #   @option options [String, Array<String>] :use
+      #     Use flag(s). If specified, any configuration flags which were saved
+      #     with a corresponding `:use` value will be applied to this
+      #     Environment.
+      #
+      # If a block is given it is immediately executed and passed the newly
+      # created Environment object as an argument.
+      # If the Environment is created in task context, the +process+ method is
+      # immediately called.
+      # Otherwise, the Environment is not processed until the task execution
+      # phase.
+      #
+      # @yield [env]
+      # @yieldparam env [Environment]
+      #   The created environment.
       def env(*args, &block)
-        Environment.new(*args, &block)
+        Rscons.application.check_configure
+        e = Environment.new(*args, &block)
+        if Rscons.application.task_execution_phase?
+          e.process
+        end
+        e
       end
 
       # Construct a task parameter.

lib/rscons/version.rb

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

rb/build_dist.rb

@@ -60,7 +60,13 @@ combined_file.each do |line|
   end
 end
 
-license = File.read("LICENSE.txt").gsub(/^/, "# ")
+license = File.read("LICENSE.txt").gsub(/^(.*?)$/) do |line|
+  if line.size > 0
+    "# #{line}"
+  else
+    "#"
+  end
+end
 
 require "zlib"
 require "base64"

spec/build_tests_spec.rb

@@ -195,6 +195,14 @@ EOF
     expect(nr(`./simple.exe`)).to eq "This is a simple C program\n"
   end
 
+  it "processes the environment when created within a task" do
+    test_dir("simple")
+    result = run_rscons(args: %w[-f env_in_task.rb])
+    expect(result.stderr).to eq ""
+    expect(File.exists?("build/e.1/simple.c.o")).to be_truthy
+    expect(nr(`./simple.exe`)).to eq "This is a simple C program\n"
+  end
+
   it "uses the build directory specified with -b" do
     test_dir("simple")
     result = run_rscons(args: %w[-b b])
@@ -350,7 +358,7 @@ EOF
     expect(result.stderr).to match /Could not find a registered build target "foo"/
   end
 
-  context "clean operation" do
+  context "clean task" do
     it 'cleans built files' do
       test_dir("simple")
       result = run_rscons
@@ -364,6 +372,28 @@ EOF
       expect(File.exists?('simple.c')).to be_truthy
     end
 
+    it "executes custom clean action blocks" do
+      test_dir("simple")
+      result = run_rscons(args: %w[-f clean.rb])
+      expect(result.stderr).to eq ""
+      expect(File.exists?("build/e.1/simple.c.o")).to be_truthy
+      result = run_rscons(args: %w[-f clean.rb clean])
+      expect(result.stderr).to eq ""
+      expect(result.stdout).to match %r{custom clean action}
+      expect(File.exists?("build/e.1/simple.c.o")).to be_falsey
+    end
+
+    it "does not process environments" do
+      test_dir("simple")
+      result = run_rscons(args: %w[clean])
+      expect(result.stderr).to eq ""
+      expect(File.exists?('build/e.1/simple.c.o')).to be_falsey
+      expect(File.exists?('build/e.1')).to be_falsey
+      expect(File.exists?('simple.exe')).to be_falsey
+      expect(File.exists?('simple.c')).to be_truthy
+      expect(result.stdout).to eq ""
+    end
+
     it 'does not clean created directories if other non-rscons-generated files reside there' do
       test_dir("simple")
       result = run_rscons
@@ -546,14 +576,16 @@ EOF
     result = run_rscons
     expect(result.stderr).to eq ""
     verify_lines(lines(result.stdout), [
-      %r{gcc -c -o build/e.1/one.c.o -MMD -MF build/e.1/one.c.o.mf -Dmake_lib one.c},
       %r{gcc -c -o build/e.1/two.c.o -MMD -MF build/e.1/two.c.o.mf -Dmake_lib two.c},
-      %r{ar rcs lib.a build/e.1/one.c.o build/e.1/two.c.o},
-      %r{gcc -c -o build/e.1/three.c.o -MMD -MF build/e.1/three.c.o.mf three.c},
-      %r{gcc -o library.exe lib.a build/e.1/three.c.o},
+      %r{gcc -c -o build/e.1/three.c.o -MMD -MF build/e.1/three.c.o.mf -Dmake_lib three.c},
+      %r{ar rcs libmylib.a build/e.1/two.c.o build/e.1/three.c.o},
+      %r{gcc -c -o build/e.1/one.c.o -MMD -MF build/e.1/one.c.o.mf one.c},
+      %r{gcc -o library.exe build/e.1/one.c.o -L. -lmylib},
     ])
     expect(File.exists?("library.exe")).to be_truthy
-    expect(nr(`ar t lib.a`)).to eq "one.c.o\ntwo.c.o\n"
+    ar_t = nr(`ar t libmylib.a`)
+    expect(ar_t).to match %r{\btwo.c.o\b}
+    expect(ar_t).to match %r{\bthree.c.o\b}
   end
 
   it 'supports build hooks to override construction variables' do
@@ -1645,7 +1677,7 @@ EOF
       test_dir("library")
       result = run_rscons(args: %w[-f override_arcmd.rb])
       expect(result.stderr).to eq ""
-      verify_lines(lines(result.stdout), [%r{ar rcf lib.a build/e.1/one.c.o build/e.1/three.c.o build/e.1/two.c.o}])
+      verify_lines(lines(result.stdout), [%r{ar rc lib.a build/e.1/one.c.o build/e.1/three.c.o build/e.1/two.c.o}])
     end
 
     it "allows passing object files as sources" do
@@ -1690,7 +1722,7 @@ EOF
       ])
       expect(File.exist?("simple.exe")).to be_truthy
       expect(File.exist?("simple.size")).to be_truthy
-      expect(File.read("simple.size")).to match /text.*data.*bss/
+      expect(File.read("simple.size")).to match /text.*data/i
     end
   end
 
@@ -1788,7 +1820,7 @@ EOF
     end
   end
 
-  context "configure operation" do
+  context "configure task" do
     it "does not print configuring messages when no configure block and configure task not called" do
       test_dir "configure"
       result = run_rscons(args: %w[-f no_configure_output.rb])
@@ -1804,7 +1836,52 @@ EOF
       expect(result.status).to_not eq 0
     end
 
-    it "automatically runs the configure operation if the project is not yet configured in the given build directory" do
+    it "only runs the configure operation once" do
+      test_dir "configure"
+
+      result = run_rscons(args: %w[-f configure_with_top_level_env.rb configure])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(result.stdout).to_not match %r{Configuring project.*Configuring project}m
+    end
+
+    it "loads configure parameters before invoking configure" do
+      test_dir "configure"
+
+      result = run_rscons(args: %w[-f configure_with_top_level_env.rb configure --prefix=/yodabob])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(result.stdout).to match "Prefix is /yodabob"
+    end
+
+    it "does not configure for distclean operation" do
+      test_dir "configure"
+
+      result = run_rscons(args: %w[-f configure_with_top_level_env.rb distclean])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(result.stdout).to_not match %r{Configuring project}
+    end
+
+    it "does not configure for clean operation" do
+      test_dir "configure"
+
+      result = run_rscons(args: %w[-f configure_with_top_level_env.rb clean])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(result.stdout).to_not match %r{Configuring project}
+    end
+
+    it "does not configure for uninstall operation" do
+      test_dir "configure"
+
+      result = run_rscons(args: %w[-f configure_with_top_level_env.rb uninstall])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(result.stdout).to_not match %r{Configuring project}
+    end
+
+    it "automatically runs the configure task if the project is not yet configured in the given build directory" do
       test_dir "configure"
 
       result = run_rscons(args: %w[-f check_c_compiler.rb])
@@ -2228,7 +2305,7 @@ EOF
 
     context "check_cfg" do
       context "when passed a package" do
-        it "stores flags and uses them during a build operation" do
+        it "stores flags and uses them during a build" do
           test_dir "configure"
           create_exe "pkg-config", "echo '-DMYPACKAGE'"
           result = run_rscons(args: %w[-f check_cfg_package.rb configure])
@@ -2265,7 +2342,7 @@ EOF
       end
 
       context "when passed a program" do
-        it "stores flags and uses them during a build operation" do
+        it "stores flags and uses them during a build" do
           test_dir "configure"
           create_exe "my-config", "echo '-DMYCONFIG -lm'"
           result = run_rscons(args: %w[-f check_cfg.rb configure])
@@ -2504,15 +2581,15 @@ EOF
     end
   end
 
-  context "install operation" do
-    it "invokes a configure operation if the project is not yet configured" do
+  context "install task" do
+    it "invokes the configure task if the project is not yet configured" do
       test_dir "typical"
 
       result = run_rscons(args: %w[-f install.rb install])
       expect(result.stdout).to match /Configuring install_test/
     end
 
-    it "invokes a build operation" do
+    it "invokes a build dependency" do
       test_dir "typical"
 
       Dir.mktmpdir do |prefix|
@@ -2572,7 +2649,7 @@ EOF
     end
   end
 
-  context "uninstall operation" do
+  context "uninstall task" do
     it "removes installed files but not built files" do
       test_dir "typical"
 
@@ -2956,6 +3033,26 @@ EOF
       expect(result.stdout).to_not match /^\s*one\b/
       expect(result.stdout).to_not match /^\s*two\b/
     end
+
+    context "with -A flag" do
+      it "displays all tasks and their parameters" do
+        test_dir "tasks"
+        result = run_rscons(args: %w[-f tasks.rb -AT])
+        expect(result.stderr).to eq ""
+        expect(result.status).to eq 0
+        verify_lines(lines(result.stdout), [
+          "Tasks:",
+          /\bone\b/,
+          /\btwo\b/,
+          /\bthree\b\s+Task three/,
+          /\bfour\b\s+Task four/,
+          /--myparam=MYPARAM\s+My special parameter/,
+          /--myp2\s+My parameter 2/,
+          /\bfive\b/,
+          /\bsix\b/,
+        ])
+      end
+    end
   end
 
   context "download script method" do
@@ -3132,6 +3229,108 @@ EOF
       expect(File.exist?("build/prog-gnome-debug/prog.exe")).to be_truthy
       expect(File.exist?("build/prog-gnome-release/prog.exe")).to be_truthy
     end
+
+    it "allows turning off variants by default" do
+      test_dir "variants"
+      result = run_rscons(args: %w[-v -f default.rb])
+      expect(File.exist?("build/prog-debug/prog.exe")).to be_falsey
+      expect(File.exist?("build/prog-release/prog.exe")).to be_truthy
+    end
+
+    it "allows turning on an off-by-default-variant from the command line" do
+      test_dir "variants"
+      result = run_rscons(args: %w[-v -f default.rb -e +debug])
+      expect(File.exist?("build/prog-debug/prog.exe")).to be_truthy
+      expect(File.exist?("build/prog-release/prog.exe")).to be_truthy
+    end
+
+    it "allows only turning on an off-by-default-variant from the command line" do
+      test_dir "variants"
+      result = run_rscons(args: %w[-v -f default.rb -e debug])
+      expect(File.exist?("build/prog-debug/prog.exe")).to be_truthy
+      expect(File.exist?("build/prog-release/prog.exe")).to be_falsey
+    end
+
+    it "exits with an error if no variant in a variant group is activated" do
+      test_dir "variants"
+      result = run_rscons(args: %w[-v -f multiple_groups.rb --variants=kde])
+      expect(result.stderr).to match %r{No variants enabled for variant group}
+      expect(result.status).to_not eq 0
+    end
+
+    it "allows querying if a variant is enabled" do
+      test_dir "variants"
+
+      result = run_rscons(args: %w[-f variant_enabled.rb configure])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(result.stdout).to match %r{one enabled}
+      expect(result.stdout).to_not match %r{two enabled}
+      expect(result.stdout).to_not match %r{three enabled}
+
+      result = run_rscons(args: %w[-f variant_enabled.rb --variants=+two configure])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(result.stdout).to match %r{one enabled}
+      expect(result.stdout).to match %r{two enabled}
+      expect(result.stdout).to_not match %r{three enabled}
+
+      result = run_rscons(args: %w[-f variant_enabled.rb --variants=two configure])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(result.stdout).to_not match %r{one enabled}
+      expect(result.stdout).to match %r{two enabled}
+      expect(result.stdout).to_not match %r{three enabled}
+    end
+
+    it "shows available variants with -T" do
+      test_dir "variants"
+
+      result = run_rscons(args: %w[-f multiple_groups.rb -T])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      verify_lines(lines(result.stdout), [
+        "Variant group 'desktop-environment':",
+        "  kde (enabled)",
+        "  gnome (enabled)",
+        "Variant group 'debug':",
+        "  debug (enabled)",
+        "  release (enabled)",
+      ])
+
+      result = run_rscons(args: %w[-f multiple_groups.rb -e gnome,release configure])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      result = run_rscons(args: %w[-f multiple_groups.rb -T])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      verify_lines(lines(result.stdout), [
+        "Variant group 'desktop-environment':",
+        "  kde",
+        "  gnome (enabled)",
+        "Variant group 'debug':",
+        "  debug",
+        "  release (enabled)",
+      ])
+    end
+  end
+
+  context "build_dir method" do
+    it "returns the top-level build directory path 1" do
+      test_dir "typical"
+      result = run_rscons(args: %w[-f build_dir.rb])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(File.exist?("build/a.file")).to be_truthy
+    end
+
+    it "returns the top-level build directory path 2" do
+      test_dir "typical"
+      result = run_rscons(args: %w[-f build_dir.rb -b bb])
+      expect(result.stderr).to eq ""
+      expect(result.status).to eq 0
+      expect(File.exist?("bb/a.file")).to be_truthy
+    end
   end
 
 end