wip for precompile phase for D

wip
Add Barrier builder
2026-01-18 21:23:50 -05:00 · 2026-01-18 11:14:29 -05:00 · 2026-01-16 22:54:22 -05:00 · 2026-01-16 20:21:13 -05:00 · 2026-01-15 21:07:18 -05:00 · 2025-11-22 00:14:26 -05:00
318 changed files with 11653 additions and 4373 deletions
@@ -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
@@ -3,5 +3,9 @@
 /_yardoc/
 /build_test_run/
 /coverage/
-/doc/
+/dist/
+/gen/
+/large_project/
 /pkg/
+/test/
+/yard/
@@ -1,109 +1,229 @@
-## ChangeLog
+## v3.3.0

-### v1.19.1
+### New Features

-#### Fixes
+- 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

- #123 - Install builder: remove target file before copying to avoid errors due to overwriting read-only files
+## v3.2.0

-### v1.19.0
+### New Features

-#### 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
+
+- #159 - Compiler check configure methods should respect :use flag
+- #160 - Configure parameters should not be stored as unscoped construction variables
+
+## 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
+
+- #125 - Support subsidiary Rsconscript files
+- #126 - Add PATH manipulation methods
+
+### Fixes
+
+- #121 - env.depends() does not work with build-root-relative "^/" paths
+- #130 - Document -f command line option
+- #133 - Clarify failed command error message indicating to run -F
+- #134 - Document CMD_STDOUT variable for Command builder
+- #135 - Write dependency file to build directory when user invokes Object builder directly
+- #141 - Document phony targets
+
+## v2.2.0
+
+### New Features
+
+- #120 - improve support for MSYS2
+- #119 - add failure messages for failed configuration checks
+- #118 - compiler checks should support cross-compilers and freestanding compilers
+
+## v2.1.0
+
+### New Features

 - #117 - ruby 2.7 compatibility

-#### Fixes
+## v2.0.2

- #115 - Check that user dependencies exist before running builders.
+### Fixes

-### v1.18.0
+- #113 - distinguish object files built from multiple sources with the same base name but different extensions

-#### Performance Improvements
+## v2.0.1

- Backport 2.x VarSet performance improvements to 1.x branch.
- Remove Cache dirty-tracking
- Reduce recursion of VarSet#expand_varref by expanding vars earlier.
+### Fixes

-#### Fixes
+- #112 - Install builder cannot replace a currently executing binary on Linux

- #73 - fix inconsistent type handling in VarSet#expand_varref
- #75 - avoid mkdir() race conditions
+## v2.0.0

-### v1.17.0
+- convert rscons from a Ruby gem to a standalone script
+- compress rscons distributable script
+- add configure operation to detect compilers, check for headers/libraries, etc... (invoked automatically if needed)
+- Environments store builder classes instead of instances of builder classes
+- use a separate Builder instance for each build operation
+- load Rsconscript from Rsconscript/Rsconscript.rb instead of Rsconsfile
+- drop support for builder run methods using the old 5 parameter signature
+- remove Environment#build_dir
+- set Environment build root in configure step
+- remove Builder#finalize (now #run called repeatedly until builder completes)
+- remove Builder#setup
+- remove Builder#features and Builder#produces?
+- add functionality to allow builders to wait on Ruby threads or other builders
+- add install/uninstall/distclean command-line operations
+- preserve makefile dependency files under build directory
+- remove a few deprecated methods
+- pass a Builder instance to build hooks instead of a build operation Hash
+- support a basic markup syntax in builder run messages to colorize target/source files
+- hide (but store) failed compilation command by default so the user doesn't have to scroll back as much to see compiler output
+- refactor to remove some redundancy among built-in builders
+- track object file source language (correctly determine linker when only passed object files previously built by particular toolchains)
+- add barriers
+- add InstallDirectory builder
+- change Install builder to copy files on 'install' operation
+- add "prefix" construction variable based on configured installation prefix
+- allow passing builder objects as sources to build targets
+- differentiate 'build' targets from 'install' targets in cache contents
+- add verbose mode
+- show build progress as a percentage in builder output messages
+- various performance improvements
+- wrote a new user guide
+- added new website ([https://holtrop.github.io/rscons/](https://holtrop.github.io/rscons/))
+- added new logo

-#### New Features
+## v1.17.0
+
+### New Features

 - allow construction variable expansion on `true` and `false` values.
 - remove makefile target name check when parsing dependencies

-### v1.16.0
+## v1.16.0

-#### New Features
+### New Features

 - Add `Rscons.glob`
 - Support command-line variables
- improve debuggability of cache.up_to_date?
+- improve debuggability of `cache.up_to_date?`
 - allow passing a VarSet into cache methods

-#### Fixes
+### Fixes

 - generate dependencies for D builds

-### v1.15.0
+## v1.15.0

 - allow json 1.x or 2.x

-### v1.14.0
+## v1.14.0

-#### New Features
+### New Features

- #45 - Add Rscons::VarSet#values_at
+- #45 - Add `Rscons::VarSet#values_at`

-#### Fixes
+### Fixes

- #44 - Environment#print_builder_run_message should support string commands
+- #44 - `Environment#print_builder_run_message` should support string commands

-### v1.13.0
+## v1.13.0

-#### New Features
+### New Features

 - #43 - Add ability to record side-effect file production

-### v1.12.0
+## v1.12.0

-#### New Features
+### New Features

- #40 - env.depends should imply env.build_after
+- #40 - env.depends should imply `env.build_after`
 - #41 - be more colorful

-#### Fixes
+### Fixes

 - #39 - wait for in-progress subcommands to complete on build failure
- #42 - cloned Environments should inherit n_threads
+- #42 - cloned Environments should inherit `n_threads`

-### v1.11.1
+## v1.11.1

-#### Fixes
+### Fixes

 - fix the circular build dependency detection logic

-### v1.11.0
+## v1.11.0

-#### New Features
+### New Features

 - Change default Environment :clone option to :all to clone all attributes
 - #38 - raise error when circular dependencies are found
- #34 - Allow overriding n_threads on a per-Environment level
+- #34 - Allow overriding `n_threads` on a per-Environment level

-#### Fixes
+### Fixes

- #35 - env.build_after should expand paths
- #36 - SHCFLAGS and SHCXXFLAGS should inherit non-SH flags by default
- #37 - Fix non-blocking thread-wait if Rscons.n_threads is set to 0
+- #35 - `env.build_after` should expand paths
+- #36 - `SHCFLAGS` and `SHCXXFLAGS` should inherit non-SH flags by default
+- #37 - Fix non-blocking thread-wait if `Rscons.n_threads` is set to 0

-### v1.10.0
+## v1.10.0

-#### New Features
+### New Features

 - #23 - add parallelization - builds are now parallelized by default
 - #31 - add LEXSUFFIX, YACCSUFFIX construction variables
@@ -113,100 +233,100 @@
 - Add builder features
 - #8 - add SharedObject and SharedLibrary builders

-#### Fixes
+### Fixes

- expand target and source paths before calling Builder#create_build_target
- #29 - fix PROGSUFFIX handling
+- expand target and source paths before calling `Builder#create_build_target`
+- #29 - fix `PROGSUFFIX` handling
 - #32 - Pre-build hooks do not respect modified key values

-### v1.9.3
+## v1.9.3

- Environment#parse_flags should put -std=XXX flags in CCFLAGS, not CFLAGS
+- `Environment#parse_flags` should put -std=XXX flags in CCFLAGS, not CFLAGS

-### v1.9.2
+## v1.9.2

 - allow phony targets in conjunction with build roots

-### v1.9.1
+## v1.9.1

 - change *SUFFIX defaults to arrays
 - add various C++ file suffixes
 - use ${INCPREFIX} instead of hard-coded "-I" in Preprocess builder

-### v1.9.0
+## v1.9.0

-#### New Features
+### New Features

 - #6 - add Install and Copy builders
- #22 - allow overriding Command builder short description with CMD_DESC variable
+- #22 - allow overriding Command builder short description with `CMD_DESC` variable
 - #24 - add "rscons" executable
 - #25 - add support for phony targets given as Symbols instead of Strings
 - #26 - support registering multiple build targets with the same target name
 - #27 - add Directory builder

-#### Fixes
+### Fixes

 - #20 - fix variable references that expand to arrays in build target sources
 - #21 - rework Preprocess builder to consider deep dependencies
- fix Rscons.set_suffix to append the given suffix if the filename has none
- remove ${CFLAGS} from default CPP_CMD
+- fix `Rscons.set_suffix` to append the given suffix if the filename has none
+- remove ${CFLAGS} from default `CPP_CMD`

-### v1.8.1
+## v1.8.1

 - fix Environment#dump when construction variables are symbols

-### v1.8.0
+## v1.8.0

 - new Command builder to execute arbitrary user commands
 - new SimpleBuilder class
-  - create new builders quickly by passing a block to Environment#add_builder
+  - create new builders quickly by passing a block to `Environment#add_builder`
 - improved YARD documentation
 - add Environment#dump to debug Environment construction variables

-### v1.7.0
+## v1.7.0

 - allow build hooks to register new build targets
- add post-build hooks (register with Environment#add_post_build_hook)
+- add post-build hooks (register with `Environment#add_post_build_hook`)
 - clear all build targets after processing an Environment
- allow trailing slashes in arguments to Environment#build_dir
+- allow trailing slashes in arguments to `Environment#build_dir`

-### v1.6.1
+## v1.6.1

 - add DEPFILESUFFIX construction variable to override dependency file suffix
 - fix Environment#depends to expand its arguments for construction variables

-### v1.6.0
+## v1.6.0

 - support lambdas as construction variable values

-### v1.5.0
+## v1.5.0

 - add "json" as a runtime dependency
 - update construction variables to match SCons more closely
-  - add CPPDEFPREFIX, INCPREFIX, CPPDEFINES, CCFLAGS, LIBDIRPREFIX, and LIBLINKPREFIX
- add Environment#shell
- add Environment#parse_flags, #parse_flags!, #merge_flags
- unbuffer $stdout by default
- add PROGSUFFIX construction variable (defaults to .exe on MinGW/Cygwin)
- add Rscons::BuildTarget and Builder#create_build_target
+  - add `CPPDEFPREFIX`, `INCPREFIX`, `CPPDEFINES`, `CCFLAGS`, `LIBDIRPREFIX`, and `LIBLINKPREFIX`
+- add `Environment#shell`
+- add `Environment#parse_flags`, `#parse_flags!`, `#merge_flags`
+- unbuffer `$stdout` by default
+- add `PROGSUFFIX` construction variable (defaults to `.exe` on MinGW/Cygwin)
+- add `Rscons::BuildTarget` and `Builder#create_build_target`
 - update specs to RSpec 3.x and fix to run on MinGW/Cygwin/Linux
 - add YARD documentation to get to 100% coverage

-### v1.4.3
+## v1.4.3

 - fix builders properly using construction variable overrides
 - expand nil construction variables to empty strings

-### v1.4.2
+## v1.4.2

- add Environment#expand_path
+- add `Environment#expand_path`
 - expand construction variable references in builder targets and sources before invoking builder

-### v1.4.1
+## v1.4.1

 - fix invoking a builder with no sources while a build root defined

-### v1.4.0
+## v1.4.0

 - add CFile builder
 - add Disassemble builder
@@ -219,21 +339,21 @@
  - implement copy-on-write semantics for construction variables when cloning Environments
  - only load the cache once instead of on each Environment#process
  - only write the cache when something has changed
- fix Cache#mkdir_p to handle relative paths (Issue #5)
+- fix `Cache#mkdir_p` to handle relative paths (Issue #5)
 - flush the cache to disk if a builder raises an exception (Issue #4)

-### v1.3.0
+## v1.3.0

 - change Environment#execute() options parameter to accept the following options keys:
  - :env to pass an environment Hash to Kernel#system
  - :options to pass an options Hash to Kernel#system

-### v1.2.0
+## v1.2.0

 - add :clone option to Environment#clone to control exactly which Environment attributes are cloned
- allow nil to be passed in to Environment#build_root=
+- allow nil to be passed in to `Environment#build_root=`

-### v1.1.0
+## v1.1.0

- Change Cache#up_to_date?() and #register_build() to accept a single target
+- Change `Cache#up_to_date?` and `#register_build` to accept a single target
  file or an array of target file names
@@ -0,0 +1,14 @@
+# Developing
+
+# Specs
+
+To run the rscons specs, the following commands must be available:
+
+* gcc
+* clang
+* g++
+* clang++
+* gdc
+* ldc2
+* flex
+* bison
@@ -1,4 +1,16 @@
 source 'https://rubygems.org'

-# Specify your gem's dependencies in rscons.gemspec
-gemspec
+gem "base64"
+gem "rspec"
+gem "rake"
+gem "simplecov", "~> 0.15.0"
+gem "openssl"
+if RbConfig::CONFIG["host"]["msys"]
+  gem "json", "2.1.0"
+else
+  gem "json"
+  gem "yard"
+  gem "rdoc"
+  gem "redcarpet"
+  gem "syntax"
+end
@@ -1,48 +1,60 @@
-PATH
-  remote: .
-  specs:
-    rscons (1.19.1)
-      json (>= 1.8, < 3.0)
-
 GEM
  remote: https://rubygems.org/
  specs:
-    diff-lcs (1.3)
+    base64 (0.3.0)
+    date (3.5.1)
+    diff-lcs (1.6.2)
    docile (1.1.5)
-    json (2.3.0)
-    rake (13.0.1)
-    rdoc (6.2.1)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.1)
-      rspec-support (~> 3.9.1)
-    rspec-expectations (3.9.1)
+    erb (6.0.1)
+    json (2.18.0)
+    openssl (4.0.0)
+    psych (5.3.1)
+      date
+      stringio
+    rake (13.3.1)
+    rdoc (7.1.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    redcarpet (3.6.1)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.2)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
    simplecov (0.15.1)
      docile (~> 1.1.0)
      json (>= 1.8, < 3)
      simplecov-html (~> 0.10.0)
    simplecov-html (0.10.2)
-    yard (0.9.24)
+    stringio (3.2.0)
+    syntax (1.2.2)
+    tsort (0.2.0)
+    yard (0.9.38)

 PLATFORMS
  ruby
  x86-mingw32

 DEPENDENCIES
+  base64
+  json
+  openssl
  rake
  rdoc
-  rscons!
+  redcarpet
  rspec
  simplecov (~> 0.15.0)
+  syntax
  yard

 BUNDLED WITH
-   2.1.4
+   2.6.2
@@ -1,4 +1,4 @@
-Copyright (c) 2013 Josh Holtrop
+Copyright (c) 2013-2025 Josh Holtrop

 MIT License

@@ -19,4 +19,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -1,591 +1,42 @@
 # Rscons

-Rscons (https://github.com/holtrop/rscons) is a software construction framework
-inspired by SCons and implemented in Ruby.
-
-[![Gem Version](https://badge.fury.io/rb/rscons.png)](http://badge.fury.io/rb/rscons)
-
-## Installation
-
-    $ gem install rscons
-
-## Usage
-
-### Standalone
-
-Rscons provides a standalone executable ("rscons") with a command-line
-interface. The rscons executable will read a build script (by default named
-Rsconsfile or Rsconsfile.rb) and execute its contents.
-
-### With Rake
-
-Rscons can be used with rake as well. The same content that would be written
-in Rsconsfile can be placed in a Rakefile. It could be placed within a rake
-task block or split among multiple tasks.
-
-## Example Build Scripts
-
-### Example: Building a C Program
-
-```ruby
-Rscons::Environment.new do |env|
-  env["CFLAGS"] << "-Wall"
-  env.Program("program", Rscons.glob("src/**/*.c"))
-end
-```
-
-### Example: Building a D Program
-
-```ruby
-Rscons::Environment.new do |env|
-  env["DFLAGS"] << "-Wall"
-  env.Program("program", Rscons.glob("src/**/*.d"))
-end
-```
-
-### Example: Cloning an Environment
-
-```ruby
-main_env = Rscons::Environment.new do |env|
-  # Store object files from sources under "src" in "build/main"
-  env.build_dir("src", "build/main")
-  env["CFLAGS"] = ["-DSOME_DEFINE", "-O3"]
-  env["LIBS"] = ["SDL"]
-  env.Program("program", Rscons.glob("src/**/*.cc"))
-end
-
-debug_env = main_env.clone do |env|
-  # Store object files from sources under "src" in "build/debug"
-  env.build_dir("src", "build/debug")
-  env["CFLAGS"] -= ["-O3"]
-  env["CFLAGS"] += ["-g", "-O0"]
-  env.Program("program-debug", Rscons.glob("src/**/*.cc"))
-end
-```
-
-### Example: Custom Builder
-
-Custom builders are implemented as classes which extend from `Rscons::Builder`.
-The builder must have a `run` method which is called to invoke the builder.
-The `run` method should return the name of the target built on success, and
-`false` on failure.
-
-```ruby
-class GenerateFoo < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    cache.mkdir_p(File.dirname(target))
-    File.open(target, "w") do |fh|
-      fh.puts <<EOF
-#define GENERATED 42
-EOF
-    end
-    target
-  end
-end
-
-Rscons::Environment.new do |env|
-  env.add_builder(GenerateFoo.new)
-  env.GenerateFoo("foo.h", [])
-  env.Program("a.out", Rscons.glob("*.c"))
-end
-```
-
-### Example: Custom Builder That Only Regenerates When Necessary
-
-```ruby
-class CmdBuilder < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    cmd = ["cmd", "-i", sources.first, "-o", target]
-    unless cache.up_to_date?(target, cmd, sources, env)
-      cache.mkdir_p(File.dirname(target))
-      system(cmd)
-      cache.register_build(target, cmd, sources, env)
-    end
-    target
-  end
-end
-
-Rscons::Environment.new do |env|
-  env.add_builder(CmdBuilder.new)
-  env.CmdBuilder("foo.gen", "foo_gen.cfg")
-end
-```
-
-The `Cache#up_to_date?` method accepts an optional 5th parameter which is an
-options Hash. The `:debug` option can be specified in this Hash with a value
-of `true` to aid in debugging builders while developing them. For example:
-
-```ruby
-unless cache.up_to_date?(target, cmd, sources, env, debug: true)
-end
-```
-
-### Example: Custom Builder That Generates Multiple Output Files
-
-```ruby
-class CModuleGenerator < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    c_fname = target
-    h_fname = target.sub(/\.c$/, ".h")
-    cmd = ["generate_c_and_h", sources.first, c_fname, h_fname]
-    unless cache.up_to_date?([c_fname, h_fname], cmd, sources, env)
-      cache.mkdir_p(File.dirname(target))
-      system(cmd)
-      cache.register_build([c_fname, h_fname], cmd, sources, env)
-    end
-    target
-  end
-end
-
-Rscons::Environment.new do |env|
-  env.add_builder(CModuleGenerator.new)
-  env.CModuleGenerator("build/foo.c", "foo_gen.cfg")
-end
-```
-
-### Example: Custom Builder Using Builder#standard_build()
-
-The `standard_build` method from the `Rscons::Builder` base class can be used
-when the builder needs to execute a system command to produce the target file.
-The `standard_build` method will return the correct value so its return value
-can be used as the return value from the `run` method.
-
-```ruby
-class CmdBuilder < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    cmd = ["cmd", "-i", sources.first, "-o", target]
-    standard_build("CmdBld #{target}", target, cmd, sources, env, cache)
-  end
-end
-
-Rscons::Environment.new do |env|
-  env.add_builder(CmdBuilder.new)
-  env.CmdBuilder("foo.gen", "foo_gen.cfg")
-end
-```
-
-### Example: Custom Builder Using Environment#add_builder()
-
-The `add_builder` method of the `Rscons::Environment` class optionally allows
-you to define and register a builder by providing a name and action block. This
-can be useful if the builder you are trying to define is easily expressed as a
-short ruby procedure. When `add_builder` is called in this manner a new builder
-will be registered with the environment with the given name. When this builder
-is used it will call the provided block in order to build the target.
-
-```ruby
-Rscons::Environment.new do |env|
-  env.add_builder(:JsonToYaml) do |target, sources, cache, env, vars|
-    unless cache.up_to_date?(target, :JsonToYaml, sources, env)
-      cache.mkdir_p(File.dirname(target))
-      File.open(target, 'w') do |f|
-        f.write(YAML.dump(JSON.load(IO.read(sources.first))))
-      end
-      cache.register_build(target, :JsonToYaml, sources, env)
-    end
-    target
-  end
-  env.JsonToYaml('foo.yml','foo.json')
-end
-```
-
-### Example: Using different compilation flags for some sources
-
-```ruby
-Rscons::Environment.new do |env|
-  env["CFLAGS"] = ["-O3", "-Wall", "-DDEFINE"]
-  env.add_build_hook do |build_op|
-    if build_op[:target] =~ %r{build/third-party}
-      build_op[:vars]["CFLAGS"] -= ["-Wall"]
-    end
-  end
-  env.build_dir("src", "build")
-  env.Program("program", Rscons.glob("**/*.cc"))
-end
-```
-
-### Example: Creating a static library
-
-```ruby
-Rscons::Environment.new do |env|
-  env.Library("mylib.a", Rscons.glob("src/**/*.c"))
-end
-```
-
-### Example: Creating a C++ parser source from a Yacc/Bison input file
-
-```ruby
-Rscons::Environment.new do |env|
-  env.CFile("#{env.build_root}/parser.tab.cc", "parser.yy")
-end
-```
-
-## Details
-
-### Environments
-
-The Environment is the main top-level object that Rscons operates with. An
-Environment must be created by the user in order to build anything. All build
-targets are registered within an Environment. In many cases only a single
-Environment will be needed, but more than one can be created (either from
-scratch or by cloning another existing Environment) if needed.
-
-An Environment consists of:
-
-* a collection of builders
-* a collection of construction variables used by those builders
-* a mapping of build directories from source directories
-* a default build root to apply if no specific build directories are matched
-* a collection of user-defined build targets
-* a collection of user-defined build hooks
-
-When cloning an environment, by default the construction variables, builders,
-build hooks, build directories, and build root are cloned, but the new
-environment does not inherit any of the registered build targets.
-
-The set of environment attributes that are cloned is controllable via the
-`:clone` option to the `#clone` method.
-For example, `env.clone(clone: [:variables, :builders])` will include
-construction variables, and builders but not build hooks, build directories, or
-the build root.
-
-The set of pending targets is never cloned.
-
-Cloned environments contain "deep copies" of construction variables.
-For example, in:
-
-```ruby
-base_env = Rscons::Environment.new
-base_env["CPPPATH"] = ["one", "two"]
-cloned_env = base_env.clone
-cloned_env["CPPPATH"] << "three"
-```
-
-`base_env["CPPPATH"]` will not include "three".
-
-### Builders
-
-Builders are the workhorses that Rscons uses to execute build operations.
-Each builder is specialized to perform a particular operation.
-
-Rscons ships with a number of builders:
-
-* Command, which executes a user-defined command to produce the target.
-* Copy, which is identical to Install.
-* CFile, which builds a C or C++ source file from a lex or yacc input file.
-* Disassemble, which disassembles an object file to a disassembly listing.
-* Install, which installs files or directories to a specified destination.
-* Library, which collects object files into a static library archive file.
-* Object, which compiles source files to produce an object file.
-* Preprocess, which invokes the C/C++ preprocessor on a source file.
-* Program, which links object files to produce an executable.
-* SharedLibrary, which links object files to produce a dynamically loadable
-  library.
-* SharedObject, which compiles source files to produce an object file, in a way
-  that is able to be used to create a shared library.
-
-If you want to create an Environment that does not contain any builders,
-you can use the `:exclude_builders` key to the Environment constructor.
-
-#### Command
-
-```ruby
-env.Command(target, sources, "CMD" => command)
-# Example
-env.Command("docs.html", "docs.md",
-    "CMD" => ["pandoc", "-fmarkdown", "-thtml", "-o${_TARGET}", "${_SOURCES}"],
-    "CMD_DESC" => "PANDOC")
-```
-
-The command builder executes a user-defined command in order to produce the
-desired target file based on the provided source files.
-
-#### CFile
-
-```ruby
-env.CFile(target, source)
-# Example
-env.CFile("parser.c", "parser.y")
-```
-
-The CFile builder will generate a C or C++ source file from a lex (.l, .ll)
-or yacc (.y, .yy) input file.
-
-#### Disassemble
-
-```ruby
-env.Disassemble(target, source)
-# Example
-env.Disassemble("module.dis", "module.o")
-```
-
-The Disassemble builder generates a disassembly listing using objdump from
-and object file.
-
-#### Install
-
-```ruby
-env.Install(destination, sources)
-# Example
-env.Install("dist/bin", "app.exe")
-env.Install("dist/share", "share")
-```
-
-#### Library
-
-```ruby
-env.Library(target, sources)
-# Example
-env.Library("lib.a", Rscons.glob("src/**/*.c"))
-```
-
-The Library builder creates a static library archive from the given source
-files.
-
-#### Object
-
-```ruby
-env.Object(target, sources)
-# Example
-env.Object("module.o", "module.c")
-```
-
-The Object builder compiles the given sources to an object file. Although it
-can be called explicitly, it is more commonly implicitly called by the Program
-builder.
-
-#### Preprocess
-
-```ruby
-env.Preprocess(target, source)
-# Example
-env.Preprocess("module-preprocessed.cc", "module.cc")
-```
-
-The Preprocess builder invokes either `${CC}` or `${CXX}` (depending on if the
-source contains an extension in `${CXXSUFFIX}` or not) and writes the
-preprocessed output to the target file.
-
-#### Program
-
-```ruby
-env.Program(target, sources)
-# Example
-env.Program("myprog", Rscons.glob("src/**/*.cc"))
-```
-
-The Program builder compiles and links the given sources to an executable file.
-Object files or source files can be given as `sources`. A platform-dependent
-program suffix will be appended to the target name if one is not specified.
-This can be controlled with the `PROGSUFFIX` construction variable.
-
-#### SharedLibrary
-
-```ruby
-env.SharedLibrary(target, sources)
-# Example
-env.SharedLibrary("mydll", Rscons.glob("src/**/*.cc"))
-```
-
-The SharedLibrary builder compiles and links the given sources to a dynamically
-loadable library. Object files or source files can be given as `sources`.
-A platform-dependent prefix and suffix will be appended to the target name if
-they are not specified by the user. These values can be controlled by
-overriding the `SHLIBPREFIX` and `SHLIBSUFFIX` construction variables.
-
-#### SharedObject
-
-```ruby
-env.SharedObject(target, sources)
-# Example
-env.SharedObject("lib_module.o", "lib_module.c")
-```
-
-The SharedObject builder compiles the given sources to an object file. Any
-compilation flags necessary to build the object file in a manner that allows it
-to be used to create a shared library are added. Although it can be called
-explicitly, it is more commonly implicitly called by the SharedLibrary builder.
-
-### Construction Variables
-
-Construction variables are used to define the toolset and any build options
-that Rscons will use to build a project. The default construction variable
-values are configured to build applications using gcc. However, all
-construction variables can be overridden by the user.
-
-| Name | Type | Description | Default |
-| --- | --- | --- | --- |
-| AR | String | Static library archiver executable | "ar" |
-| ARCMD | Array | Static library archiver command line | ["${AR}", "${ARFLAGS}", "${_TARGET}", "${_SOURCES}"] |
-| ARFLAGS | Array | Static library archiver flags | ["rcs"] |
-| AS | String | Assembler executable | "${CC}" |
-| ASCMD | Array | Assembler command line | ["${AS}", "-c", "-o", "${_TARGET}", "${ASDEPGEN}", "${INCPREFIX}${ASPPPATH}", "${ASPPFLAGS}", "${ASFLAGS}", "${_SOURCES}"] |
-| ASDEPGEN | Array | Assembly dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}", "-MT", "TARGET"] |
-| ASFLAGS | Array | Assembler flags | [] |
-| ASPPFLAGS | Array | Assembler preprocessor flags | ["${CPPFLAGS}"] |
-| ASPPPATH | Array | Assembler preprocessor path | ["${CPPPATH}"] |
-| ASSUFFIX | Array | Assembly file suffixes | [".S"] |
-| CC | String | C compiler executable | "gcc" |
-| CCCMD | Array | C compiler command line | ["${CC}", "-c", "-o", "${_TARGET}", "${CCDEPGEN}", "${INCPREFIX}${CPPPATH}", "${CPPFLAGS}", "${CFLAGS}", "${CCFLAGS}", "${_SOURCES}"] |
-| CCDEPGEN | Array | C compiler dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}", "-MT", "TARGET"] |
-| CCFLAGS | Array | Common flags for both C and C++ compiler | [] |
-| CFLAGS | Array | C compiler flags | [] |
-| CPP_CMD | Array | Preprocess command line | ["${_PREPROCESS_CC}", "-E", "${_PREPROCESS_DEPGEN}", "-o", "${_TARGET}", "${INCPREFIX}${CPPPATH}", "${CPPFLAGS}", "${_SOURCES}"] |
-| CPP_TARGET_SUFFIX | String | Suffix used for crt:preprocess target filename. | ".c" |
-| CPPDEFINES | Array | C preprocessor defines | [] |
-| CPPDEFPREFIX | String | Prefix used for C preprocessor to introduce a define | "-D" |
-| CPPFLAGS | Array | C preprocessor flags | ["${CPPDEFPREFIX}${CPPDEFINES}"] |
-| CPPPATH | Array | C preprocessor path | [] |
-| CSUFFIX | Array | C source file suffixes | [".c"] |
-| CXX | String | C++ compiler executable | "g++" |
-| CXXCMD | Array | C++ compiler command line | ["${CXX}", "-c", "-o", "${_TARGET}", "${CXXDEPGEN}", "${INCPREFIX}${CPPPATH}", "${CPPFLAGS}", "${CXXFLAGS}", "${CCFLAGS}", "${_SOURCES}"] |
-| CXXDEPGEN | Array | C++ compiler dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}", "-MT", "TARGET"] |
-| CXXFLAGS | Array | C++ compiler flags | [] |
-| CXXSUFFIX | Array | C++ source file suffixes | [".cc", ".cpp", ".cxx", ".C"] |
-| D_IMPORT_PATH | Array | D compiler import path | [] |
-| DC | String | D compiler executable | "gdc" |
-| DCCMD | Array | D compiler command line | ["${DC}", "-c", "-o", "${_TARGET}", "${DDEPGEN}", "${INCPREFIX}${D_IMPORT_PATH}", "${DFLAGS}", "${_SOURCES}"] |
-| DDEPGEN | Array | D compiler dependency generation flags | ["-MMD", "-MF", "${_DEPFILE}", "-MT", "TARGET"] |
-| DEPFILESUFFIX | String | Dependency file suffix for Makefile-style dependency rules emitted by the compiler (used internally for temporary dependency files used to determine a source file's dependencies) | ".mf" |
-| DFLAGS | Array | D compiler flags | [] |
-| DISASM_CMD | Array | Disassemble command line | ["${OBJDUMP}", "${DISASM_FLAGS}", "${_SOURCES}"] |
-| DISASM_FLAGS | Array | Disassemble flags | ["--disassemble", "--source"] |
-| DSUFFIX | String/Array | Default D source file suffix | ".d" |
-| INCPREFIX | String | Prefix used for C preprocessor to add an include path | "-I" |
-| LD | String |  nil | Linker executable (automatically determined when nil) | nil (if nil, ${CC}, ${CXX}, or ${DC} is used depending on the sources being linked) |
-| LDCMD | Array | Link command line | ["${LD}", "-o", "${_TARGET}", "${LDFLAGS}", "${_SOURCES}", "${LIBDIRPREFIX}${LIBPATH}", "${LIBLINKPREFIX}${LIBS}"] |
-| LDFLAGS | Array | Linker flags | [] |
-| LEX | String | Lex executable | "flex" |
-| LEX_CMD | Array | Lex command line | ["${LEX}", "${LEX_FLAGS}", "-o", "${_TARGET}", "${_SOURCES}"] |
-| LEX_FLAGS | Array | Lex flags | [] |
-| LEXSUFFIX | Array | Lex input file suffixes | [".l", ".ll"] |
-| LIBDIRPREFIX | String | Prefix given to linker to add a library search path | "-L" |
-| LIBLINKPREFIX | String | Prefix given to linker to add a library to link with | "-l" |
-| LIBPATH | Array | Library load path | [] |
-| LIBS | Array | Libraries to link with | [] |
-| LIBSUFFIX | String/Array | Default static library file suffix | ".a" |
-| OBJDUMP | String | Objdump executable | "objdump" |
-| OBJSUFFIX | String/Array | Default object file suffix | ".o" |
-| PROGSUFFIX | String | Default program suffix. | Windows: ".exe", POSIX: "" |
-| SHCC | String | Shared object C compiler | "${CC}" |
-| SHCCCMD | Array | Shared object C compiler command line | ["${SHCC}", "-c", "-o", "${_TARGET}", "${CCDEPGEN}", "${INCPREFIX}${CPPPATH}", "${CPPFLAGS}", "${SHCFLAGS}", "${SHCCFLAGS}", "${_SOURCES}"] |
-| SHCCFLAGS | Array | Shared object C and C++ compiler flags | Windows: ["${CCFLAGS}"], POSIX: ["${CCFLAGS}", -fPIC"] |
-| SHCFLAGS | Array | Shared object C compiler flags | ["${CFLAGS}"] |
-| SHCXX | String | Shared object C++ compiler | "${CXX}" |
-| SHCXXCMD | Array | Shared object C++ compiler command line | ["${SHCXX}", "-c", "-o", "${_TARGET}", "${CXXDEPGEN}", "${INCPREFIX}${CPPPATH}", "${CPPFLAGS}", "${SHCXXFLAGS}", "${SHCCFLAGS}", "${_SOURCES}"] |
-| SHCXXFLAGS | Array | Shared object C++ compiler flags | ["${CXXFLAGS}"] |
-| SHDC | String | Shared object D compiler | "gdc" |
-| SHDCCMD | Array | Shared object D compiler command line | ["${SHDC}", "-c", "-o", "${_TARGET}", "${INCPREFIX}${D_IMPORT_PATH}", "${SHDFLAGS}", "${_SOURCES}"] |
-| SHDFLAGS | Array | Shared object D compiler flags | Windows: ["${DFLAGS}"], POSIX: ["${DFLAGS}", "-fPIC"] |
-| SHLD | String | Shared library linker | nil (if nil, ${SHCC}, ${SHCXX}, or ${SHDC} is used depending on the sources being linked) |
-| SHLDCMD | Array | Shared library linker command line | ["${SHLD}", "-o", "${_TARGET}", "${SHLDFLAGS}", "${_SOURCES}", "${SHLIBDIRPREFIX}${LIBPATH}", "${SHLIBLINKPREFIX}${LIBS}"] |
-| SHLDFLAGS | Array | Shared library linker flags | ["${LDFLAGS}", "-shared"] |
-| SHLIBDIRPREFIX | String | Prefix given to shared library linker to add a library search path | "-L" |
-| SHLIBLINKPREFIX | String | Prefix given to shared library linker to add a library to link with | "-l" |
-| SHLIBPREFIX | String | Shared library file name prefix | Windows: "", POSIX: "lib" |
-| SHLIBSUFFIX | String | Shared library file name suffix | Windows: ".dll", POSIX: ".so" |
-| SIZE | String | Size executable. | "size" |
-| YACC | String | Yacc executable | "bison" |
-| YACC_CMD | Array | Yacc command line | ["${YACC}", "${YACC_FLAGS}", "-o", "${_TARGET}", "${_SOURCES}"] |
-| YACC_FLAGS | Array | Yacc flags | ["-d"] |
-| YACCSUFFIX | Array | Yacc input file suffixes | [".y", ".yy"] |
-
-### Build Hooks
-
-Environments can have build hooks which are added with `env.add_build_hook()`.
-Build hooks are invoked immediately before a builder executes.
-Build hooks can modify the construction variables in use for the build
-operation.
-They can also register new build targets.
-
-Environments can also have post-build hooks added with `env.add_post_build_hook()`.
-Post-build hooks are only invoked if the build operation was a success.
-Post-build hooks can invoke commands using the newly-built files, or register
-new build targets.
-
-Each build hook block will be invoked for every build operation, so the block
-should test the target or sources if its action should only apply to some
-subset of build targets or source files.
-
-Example build hook:
-
-```ruby
-Rscons::Environment.new do |env|
-  # Build third party sources without -Wall
-  env.add_build_hook do |build_op|
-    if build_op[:builder].name == "Object" and
-      build_op[:sources].first =~ %r{src/third-party}
-      build_op[:vars]["CFLAGS"] -= ["-Wall"]
-    end
-  end
-end
-```
-
-The `build_op` parameter to the build hook block is a Hash describing the
-build operation with the following keys:
-* `:builder` - `Builder` instance in use
-* `:env` - `Environment` calling the build hook; note that this may be
-  different from the Environment that the build hook was added to in the case
-  that the original Environment was cloned with build hooks!
-* `:target` - `String` name of the target file
-* `:sources` - `Array` of the source files
-* `:vars` - `Rscons::VarSet` containing the construction variables to use.
-  The build hook can overwrite entries in `build_op[:vars]` to alter the
-  construction variables in use for this specific build operation.
-
-### Phony Targets
-
-A build target name given as a Symbol instead of a String is interpreted as a
-"phony" target.
-Phony targets operate similarly to normal build targets, except that a file is
-not expected to be produced by the builder.
-Phony targets will still be "rebuilt" if any source or the command is out of
-date.
-
-### Explicit Dependencies
-
-A target can be marked as depending on another file that Rscons would not
-otherwise know about via the `Environment#depends` function. For example,
-to force the linker to re-link a Program output when a linker script changes:
-
-```ruby
-Rscons::Environment.new do |env|
-  env.Program("a.out", "foo.c", "LDFLAGS" => %w[-T linker_script.ld])
-  env.depends("a.out", "linker_script.ld")
-end
-```
-
-You can pass multiple dependency files to `Environment#depends`:
-
-```ruby
-env.depends("my_app", "config/link.ld", "README.txt", *Rscons.glob("assets/**/*"))
-```
-
-### Command-Line Variables
-
-Variables can be specified on the rscons command line. For example:
-
-```
-rscons VAR=val
-```
-
-These variables are accessible in a global VarSet called `Rscons.vars`.
-
-### Construction Variable Naming
-
-* uppercase strings - the default construction variables that Rscons uses
-* strings beginning with "_" - set and used internally by builders
-* symbols, lowercase strings - reserved as user-defined construction variables
-
-### API documentation
-
-Documentation for the complete Rscons API can be found at
-http://www.rubydoc.info/github/holtrop/rscons/master.
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+![rscons logo](img/rscons_logo_1000.png)
+
+Rscons (https://github.com/holtrop/rscons) is an open-source build system
+for developers.
+It supports the following features:
+
+  * multi-threaded job execution
+  * auto-configuration
+  * built-in builders for several common operations
+  * 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
+  * 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.
@@ -5,23 +5,107 @@ rescue Bundler::BundlerError => e
  raise LoadError.new("Unable to setup Bundler; you might need to `bundle install`: #{e.message}")
 end

-require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-require "yard"
 require "rake/clean"
+require "fileutils"

-CLEAN.include %w[build_test_run .yardoc doc coverage]
-CLOBBER.include %w[pkg]
+CLEAN.include %w[build_test_run .yardoc yard coverage test]
+CLOBBER.include %w[dist gen large_project pkg]
+
+task :build_dist do
+  sh "ruby rb/build_dist.rb"
+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

-YARD::Rake::YardocTask.new do |yard|
-  yard.files = ['lib/**/*.rb']
+# 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.rm_rf("test")
+  FileUtils.mkdir_p("test")
+  FileUtils.cp("dist/rscons", "test/rscons.rb")
+  ENV["rscons_dist_specs"] = "1"
+  Rake::Task["spec"].execute(args)
+  ENV.delete("rscons_dist_specs")
+  FileUtils.rm_f(Dir.glob(".rscons-*"))
+end
+
+task :gen_large_project, [:size] => :build_dist do |task, args|
+  size = (args.size || 10000).to_i
+  FileUtils.rm_rf("large_project")
+  FileUtils.mkdir_p("large_project/src")
+  size.times do |i|
+    File.open("large_project/src/fn#{i}.c", "w") do |fh|
+      fh.puts(<<-EOF)
+        int fn#{i}(void)
+        {
+          return #{i};
+        }
+      EOF
+    end
+    File.open("large_project/src/fn#{i}.h", "w") do |fh|
+      fh.puts %[int fn#{i}(void);]
+    end
+  end
+  File.open("large_project/src/main.c", "w") do |fh|
+    size.times do |i|
+      fh.puts %[#include "fn#{i}.h"]
+    end
+    fh.puts <<-EOF
+      int main(int argc, char * argv[])
+      {
+        int result = 0;
+    EOF
+    size.times do |i|
+      fh.puts %[result += fn#{i}();]
+    end
+    fh.puts <<-EOF
+        return result;
+      }
+    EOF
+  end
+  File.open("large_project/Rsconscript", "w") do |fh|
+    fh.puts <<EOF
+default do
+  Environment.new do |env|
+    env.Program("project", glob("src/*.c"))
+  end
+end
+EOF
+  end
+  FileUtils.cp("dist/rscons", "large_project")
+end
+
+unless RbConfig::CONFIG["host"]["msys"]
+  require "yard"
+  YARD::Rake::YardocTask.new do |yard|
+    yard.files = ['lib/**/*.rb']
+    yard.options = ["-ogen/yard"]
+  end
+
+  desc "Build user guide"
+  task :user_guide do
+    system("ruby", "-Ilib", "rb/gen_user_guide.rb")
+  end
 end

 task :default => :spec
+
+task :all => [
+  :build_dist,
+  :spec,
+  :dspec,
+  :yard,
+  :user_guide,
+]
@@ -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()`.
@@ -2,4 +2,6 @@

 require "rscons/cli"

-Rscons::Cli.run(ARGV)
+if __FILE__ == $0
+  Rscons::Cli.new.run(ARGV)
+end
@@ -1,5 +0,0 @@
-Rscons::Environment.new do |env|
-  env.append('CPPPATH' => Rscons.glob('src/**'))
-  env.build_dir(%r{^src/([^/]+)/}, 'build_\\1/')
-  env.Program('build_dir.exe', Rscons.glob('src/**/*.c'))
-end
@@ -1,22 +0,0 @@
-class MyObject < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    env.run_builder(env.builders["Object"], target, sources, cache, vars)
-  end
-end
-
-Rscons::Environment.new(echo: :command) do |env|
-  env.add_builder(MyObject.new)
-  env.append('CPPPATH' => Rscons.glob('src/**'))
-  env.add_build_hook do |build_op|
-    if build_op[:builder].name == "MyObject" && build_op[:sources].first =~ %r{one\.c}
-      build_op[:vars]["CFLAGS"] << "-O1"
-      build_op[:sources] = ['src/two/two.c']
-    elsif build_op[:builder].name == "MyObject" && build_op[:target] =~ %r{two\.o}
-      new_vars = build_op[:vars].clone
-      new_vars["CFLAGS"] << "-O2"
-      build_op[:vars] = new_vars
-    end
-  end
-  env.MyObject('one.o', 'src/one/one.c')
-  env.MyObject('two.o', 'src/two/two.c')
-end
@@ -1,6 +0,0 @@
-env = Rscons::Environment.new do |env|
-  env.append('CPPPATH' => Rscons.glob('src/**/*/'))
-  env.build_dir("src", "build")
-  env.build_root = "build_root"
-  env.Program('build_dir.exe', Rscons.glob('src/**/*.c'))
-end
@@ -1,12 +0,0 @@
-Rscons::Environment.new(echo: :command) do |env|
-  env.append('CPPPATH' => Rscons.glob('src/**/*/'))
-  env.build_dir(%r{^src/([^/]+)/}, 'build_\\1/')
-  env.add_build_hook do |build_op|
-    if build_op[:target] =~ %r{build_one/.*\.o}
-      build_op[:vars]["CFLAGS"] << "-O1"
-    elsif build_op[:target] =~ %r{build_two/.*\.o}
-      build_op[:vars]["CFLAGS"] << "-O2"
-    end
-  end
-  env.Program('build_hook.exe', Rscons.glob('src/**/*.c'))
-end
@@ -1,8 +0,0 @@
-Rscons::Environment.new(echo: :command) do |env|
-  env.append('CPPPATH' => Rscons.glob('src/**').sort)
-  env.build_root = "build_root"
-  FileUtils.mkdir_p(env.build_root)
-  FileUtils.mv("src/one/one.c", "build_root")
-  env.Object("^/one.o", "^/one.c")
-  env.Program("build_dir.exe", Rscons.glob('src/**/*.c') + ["^/one.o"])
-end
@@ -1,6 +0,0 @@
-Rscons::Environment.new do |env|
-  env["CSUFFIX"] = %w[.yargh .c]
-  env["CFLAGS"] += %w[-x c]
-  env["CPPPATH"] += Rscons.glob("src/**")
-  env.Program("build_dir.exe", Rscons.glob("src/**/*.{c,yargh}"))
-end
@@ -1,5 +0,0 @@
-Rscons::Environment.new do |env|
-  env.echo = :command
-  env.Install("inst.exe", "install.rb")
-end
-
@@ -1,13 +0,0 @@
-class MyBuilder < Rscons::Builder
-  def run(options)
-    env, target = options.values_at(:env, :target)
-    env.print_builder_run_message("MyBuilder #{target}", "MyBuilder #{target} command")
-    target
-  end
-end
-
-Rscons::Environment.new do |env|
-  env.echo = :command
-  env.add_builder(MyBuilder.new)
-  env.MyBuilder("foo")
-end
@@ -1,3 +0,0 @@
-Rscons::Environment.new do |env|
-  env.Install("inst.exe", "install.rb")
-end
@@ -1,9 +0,0 @@
-Rscons::Environment.new do |env|
-  env.Directory("inst")
-  env.Install("inst", "install_directory.rb")
-
-  env.Install("noexist/src", "src")
-
-  env.Directory("exist/src")
-  env.Install("exist/src", "src")
-end
@@ -1,3 +0,0 @@
-Rscons::Environment.new do |env|
-  env.Install("dest", "install.rb")
-end
@@ -1,6 +0,0 @@
-Rscons::Environment.new do |env|
-  env.append('CPPPATH' => Rscons.glob('src/**'))
-  env.build_dir("src2", "build")
-  env.build_root = "build_root"
-  env.Program('build_dir.exe', Rscons.glob('src/**/*.c'))
-end
@@ -1,6 +0,0 @@
-Rscons::Environment.new do |env|
-  env.append("CPPPATH" => Rscons.glob("src/**"))
-  env.build_dir("src/one/", "build_one/")
-  env.build_dir("src/two", "build_two")
-  env.Program("build_dir.exe", Rscons.glob("src/**/*.c"))
-end
@@ -1,4 +0,0 @@
-Rscons::Environment.new do |env|
-  env.CFile("lexer.c", "lexer.l")
-  env.CFile("parser.c", "parser.y")
-end
@@ -1,3 +0,0 @@
-Rscons::Environment.new do |env|
-  env.CFile("file.c", "foo.bar")
-end
@@ -1,12 +1,10 @@
-debug = Rscons::Environment.new(echo: :command) do |env|
-  env.build_dir('src', 'debug')
+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.build_dir('src', 'release')
  env.Program('program-release.exe', Dir['src/*.c'])
 end
@@ -1,15 +1,14 @@
-env1 = Rscons::Environment.new(echo: :command) do |env|
-  env.build_dir('src', 'build')
+env1 = env("e1", echo: :command) do |env|
  env['CFLAGS'] = '-O2'
-  env.add_build_hook do |build_op|
-    build_op[:vars]['CPPFLAGS'] = '-DSTRING="Hello"'
+  env.add_build_hook do |builder|
+    builder.vars['CPPFLAGS'] = '-DSTRING="Hello"'
  end
-  env.add_post_build_hook do |build_op|
-    $stdout.puts "post #{build_op[:target]}"
+  env.add_post_build_hook do |builder|
+    $stdout.puts "post #{builder.target}"
  end
  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
@@ -0,0 +1,4 @@
+configure do
+  check_c_compiler "nope.nope"
+end
+default
@@ -0,0 +1,3 @@
+autoconf false
+env do |env|
+end
@@ -0,0 +1,8 @@
+configure do
+  check_c_compiler
+  check_c_header "stdio.h"
+end
+
+env do |env|
+  env.Program("simple.exe", "simple.c")
+end
@@ -0,0 +1,4 @@
+configure do
+  check_c_compiler
+end
+default
@@ -0,0 +1,3 @@
+configure do
+  check_c_compiler "mycompiler"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_c_compiler "gcc", "clang"
+end
@@ -0,0 +1,6 @@
+configure do
+  check_c_compiler "clang"
+end
+env do |env|
+  env.Program("simple.exe", "simple.c")
+end
@@ -0,0 +1,12 @@
+configure do
+  check_c_compiler "clang", use: "clang"
+  check_c_compiler
+end
+
+env "t1" do |env|
+  env.Program("test_gcc.exe", "simple.c")
+end
+
+env "t2", use: "clang" do |env|
+  env.Program("test_clang.exe", "simple.c")
+end
@@ -0,0 +1,8 @@
+configure do
+  check_c_header "string.h", check_cpppath: ["./usr1"]
+  check_c_header "frobulous.h", check_cpppath: ["./usr2"]
+end
+
+env do |env|
+  env.Object("test.o", "test.c")
+end
@@ -0,0 +1,3 @@
+configure do
+  check_c_header "not___found.h"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_c_header "not___found.h", fail: false
+end
@@ -0,0 +1,7 @@
+configure do
+  check_c_header "not___found.h", set_define: "HAVE_NOT___FOUND_H"
+end
+
+env(echo: :command) do |env|
+  env.Object("simple.o", "simple.c")
+end
@@ -0,0 +1,3 @@
+configure do
+  check_c_header "string.h"
+end
@@ -0,0 +1,7 @@
+configure do
+  check_c_header "string.h", set_define: "HAVE_STRING_H"
+end
+
+env(echo: :command) do |env|
+  env.Object("simple.o", "simple.c")
+end
@@ -0,0 +1,7 @@
+configure do
+  check_cfg program: "my-config"
+end
+
+env(echo: :command) do |env|
+  env.Program("myconfigtest", "simple.c")
+end
@@ -0,0 +1,5 @@
+ENV["PATH"] = ""
+
+configure do
+  check_cfg package: "mypackage"
+end
@@ -0,0 +1,7 @@
+configure do
+  check_cfg package: "mypackage"
+end
+
+env(echo: :command) do |env|
+  env.Program("myconfigtest", "simple.c")
+end
@@ -0,0 +1,13 @@
+configure do
+  check_cfg package: "mypackage", use: "myp"
+end
+
+env(echo: :command) do |env|
+  env.Copy("myconfigtest1.c", "simple.c")
+  env.Program("myconfigtest1.exe", "myconfigtest1.c")
+end
+
+env(echo: :command, use: "myp") do |env|
+  env.Copy("myconfigtest2.c", "simple.c")
+  env.Program("myconfigtest2.exe", "myconfigtest2.c")
+end
@@ -0,0 +1,3 @@
+configure do
+  check_cxx_compiler
+end
@@ -0,0 +1,3 @@
+configure do
+  check_cxx_compiler "mycompiler"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_cxx_compiler "g++", "clang++"
+end
@@ -0,0 +1,12 @@
+configure do
+  check_cxx_compiler "clang++", use: "clang"
+  check_cxx_compiler
+end
+
+env "t1" do |env|
+  env.Program("test_gcc.exe", "simple.cc")
+end
+
+env "t2", use: "clang" do |env|
+  env.Program("test_clang.exe", "simple.cc")
+end
@@ -0,0 +1,8 @@
+configure do
+  check_cxx_header "string.h", check_cpppath: ["./usr1"]
+  check_cxx_header "frobulous.h", check_cpppath: ["./usr2"]
+end
+
+env do |env|
+  env.Object("test.o", "test.cc")
+end
@@ -0,0 +1,3 @@
+configure do
+  check_cxx_header "not___found.h"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_cxx_header "not___found.h", fail: false
+end
@@ -0,0 +1,3 @@
+configure do
+  check_cxx_header "string.h"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_d_compiler
+end
@@ -0,0 +1,3 @@
+configure do
+  check_d_compiler "mycompiler"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_d_compiler "gdc", "ldc2", "ldc"
+end
@@ -0,0 +1,12 @@
+configure do
+  check_d_compiler "ldc2", use: "ldc2"
+  check_d_compiler
+end
+
+env "t1" do |env|
+  env.Program("test_gcc.exe", "simple.d")
+end
+
+env "t2", use: "ldc2" do |env|
+  env.Program("test_ldc2.exe", "simple.d")
+end
@@ -0,0 +1,9 @@
+configure do
+  check_d_compiler
+  check_d_import "std.stdio", check_d_import_path: ["./usr1"]
+  check_d_import "frobulous", check_d_import_path: ["./usr2"]
+end
+
+env do |env|
+  env.Object("test.o", "test.d")
+end
@@ -0,0 +1,3 @@
+configure do
+  check_d_import "not.found"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_d_import "not.found", fail: false
+end
@@ -0,0 +1,4 @@
+configure do
+  check_d_compiler
+  check_d_import "std.stdio"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_lib "mfoofoo"
+end
@@ -0,0 +1,3 @@
+env(echo: :command) do |env|
+  env.Library("usr2/libfrobulous.a", "two.c")
+end
@@ -0,0 +1,8 @@
+configure do
+  check_lib "m", check_libpath: ["./usr1"]
+  check_lib "frobulous", check_libpath: ["./usr2"]
+end
+
+env(echo: :command) do |env|
+  env.Program("simple.exe", "simple.c")
+end
@@ -0,0 +1,3 @@
+configure do
+  check_lib "mfoofoo", fail: false
+end
@@ -0,0 +1,7 @@
+configure do
+  check_lib "m"
+end
+
+env(echo: :command) do |env|
+  env.Program("simple.exe", "simple.c")
+end
@@ -0,0 +1,13 @@
+configure do
+  check_lib "m", use: :m
+end
+
+env(echo: :command) do |env|
+  env.Copy("test1.c", "simple.c")
+  env.Program("test2.exe", "test1.c")
+end
+
+env(echo: :command, use: %w[m]) do |env|
+  env.Copy("test2.c", "simple.c")
+  env.Program("test2.exe", "test2.c")
+end
@@ -0,0 +1,8 @@
+configure do
+  check_lib "m", use: false
+end
+
+env(echo: :command) do |env|
+  env.Copy("test1.c", "simple.c")
+  env.Program("test2.exe", "test1.c")
+end
@@ -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
@@ -0,0 +1,3 @@
+configure do
+  check_program "program-that-is-not-found"
+end
@@ -0,0 +1,3 @@
+configure do
+  check_program "program-that-is-not-found", fail: false
+end
@@ -0,0 +1,3 @@
+configure do
+  check_program "find"
+end
@@ -0,0 +1,6 @@
+configure do
+  check_c_compiler
+end
+env do |env|
+  puts "Prefix is #{Task["configure"]["prefix"]}"
+end
@@ -0,0 +1,28 @@
+configure do
+  custom_check("Checking 'grep' version") do |op|
+    stdout, stderr, status = op.log_and_test_command(%w[grep --version])
+    should_fail = true
+    if status != 0
+      fail_message = "error executing grep"
+    elsif stdout =~ /^grep \(GNU grep\) 1\./
+      fail_message = "too old!"
+      status = 1
+    elsif stdout =~ /^grep \(GNU grep\) 2\./
+      fail_message = "we'll work with it but you should upgrade"
+      status = 1
+      should_fail = false
+      op.store_merge("CPPDEFINES" => "GREP_WORKAROUND")
+    else
+      op.store_append("CPPDEFINES" => "GREP_FULL")
+    end
+    op.complete(status, success_message: "good!", fail_message: fail_message, fail: should_fail)
+  end
+  custom_check("Checking sed -E flag") do |op|
+    stdout, stderr, status = op.log_and_test_command(%w[sed -E -e s/ab+/rep/], stdin: "abbbc")
+    op.complete(stdout =~ /repc/ ? 0 : 1, success_message: "good", fail_message: "fail")
+  end
+end
+
+env do |env|
+  puts env["CPPDEFINES"]
+end
@@ -0,0 +1,13 @@
+project_name "configure test"
+autoconf false
+configure do
+  check_c_compiler
+  check_cxx_compiler
+  check_d_compiler
+  check_cfg package: "mypackage"
+  check_c_header "stdio.h"
+  check_cxx_header "iostream"
+  check_d_import "std.stdio"
+  check_lib "m"
+  check_program "ls"
+end
@@ -0,0 +1,8 @@
+configure do
+  check_c_header "math.h", set_define: "HAVE_MATH_H"
+  check_c_header "stdio.h", set_define: "HAVE_STDIO_H"
+end
+
+env(echo: :command) do |env|
+  env.Object("simple.o", "simple.c")
+end
@@ -0,0 +1,3 @@
+default do
+  puts "default"
+end
@@ -0,0 +1,5 @@
+configure do
+  check_c_compiler "foo123c", fail: false, on_fail: "Install the foo123 package"
+  check_d_compiler "foo123d", fail: false
+  check_cxx_compiler "foo123cxx", on_fail: lambda {puts "Install the foo123cxx package"}
+end
@@ -0,0 +1 @@
+check_c_compiler "gcc"
@@ -0,0 +1,6 @@
+#include <stdio.h>
+
+int main(int argc, char *argv[])
+{
+    printf("This is a simple C program\n");
+}
@@ -0,0 +1,6 @@
+#include <iostream>
+
+int main(int argc, char *argv[])
+{
+    std::cout << "Hi" << std::endl;
+}
@@ -0,0 +1,7 @@
+import std.stdio;
+
+int main()
+{
+    writeln("Hello");
+    return 0;
+}
@@ -0,0 +1,4 @@
+int two(void)
+{
+    return 42;
+}
@@ -1,16 +1,16 @@
 class MySource < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    File.open(target, 'w') do |fh|
+  def run(options)
+    File.open(@target, 'w') do |fh|
      fh.puts <<EOF
 #define THE_VALUE 5678
 EOF
    end
-    target
+    true
  end
 end

-Rscons::Environment.new do |env|
-  env.add_builder(MySource.new)
+env do |env|
+  env.add_builder(MySource)
  env.MySource('inc.h', [])
  env.Program('program.exe', Dir['*.c'])
 end
@@ -1,10 +1,11 @@
-Rscons::Environment.new do |env|
+env do |env|
  env.Command("inc.c",
              [],
              "CMD" => %w[ruby gen.rb ${_TARGET}],
              "CMD_DESC" => "Generating")
  env["build_root"] = env.build_root
  env["inc_c"] = "inc.c"
-  env.build_after("${build_root}/program.o", "${inc_c}")
-  env.Program("program.exe", ["program.c", "inc.c"])
+  env.Object("program.o", "program.c")
+  env.build_after("program.o", "${inc_c}")
+  env.Program("program.exe", ["program.o", "inc.c"])
 end
@@ -1,18 +1,18 @@
 class MySource < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    File.open(target, 'w') do |fh|
+  def run(options)
+    File.open(@target, 'w') do |fh|
      fh.puts <<EOF
 #define THE_VALUE 678
 EOF
    end
-    target
+    true
  end
 end

-env = Rscons::Environment.new do |env|
+env = env do |env|
  env["hdr"] = "inc.h"
  env["src"] = "program.c"
-  env.add_builder(MySource.new)
+  env.add_builder(MySource)
  env.MySource('${hdr}')
  env.Program('program.exe', "${src}")
 end
@@ -1,16 +1,16 @@
 class MySource < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    File.open(target, 'w') do |fh|
+  def run(options)
+    File.open(@target, 'w') do |fh|
      fh.puts <<EOF
-#define THE_VALUE #{env.expand_varref("${the_value}")}
+#define THE_VALUE #{@env.expand_varref("${the_value}")}
 EOF
    end
-    target
+    true
  end
 end

-e1 = Rscons::Environment.new do |env|
-  env.add_builder(MySource.new)
+e1 = env do |env|
+  env.add_builder(MySource)
  env["one"] = "5"
  env[:cfg] = {val: "9"}
  env["two"] = lambda do |args|
@@ -0,0 +1,6 @@
+env do |env|
+  env.add_builder(:MyBuilder) do |options|
+    "hi"
+  end
+  env.MyBuilder("foo")
+end
@@ -0,0 +1,6 @@
+env do |env|
+  env.add_builder(:MyBuilder) do |options|
+    wait_for(1)
+  end
+  env.MyBuilder("foo")
+end
@@ -1,19 +1,19 @@
 class CHGen < Rscons::Builder
-  def run(target, sources, cache, env, vars)
-    c_fname = target
-    h_fname = target.sub(/\.c$/, ".h")
-    unless cache.up_to_date?([c_fname, h_fname], "", sources, env)
+  def run(options)
+    c_fname = @target
+    h_fname = @target.sub(/\.c$/, ".h")
+    unless @cache.up_to_date?([c_fname, h_fname], "", @sources, @env)
      puts "CHGen #{c_fname}"
      File.open(c_fname, "w") {|fh| fh.puts "int THE_VALUE = 42;"}
      File.open(h_fname, "w") {|fh| fh.puts "extern int THE_VALUE;"}
-      cache.register_build([c_fname, h_fname], "", sources, env)
+      @cache.register_build([c_fname, h_fname], "", @sources, @env)
    end
-    target
+    true
  end
 end

-Rscons::Environment.new do |env|
-  env.add_builder(CHGen.new)
+env do |env|
+  env.add_builder(CHGen)
  env.CHGen("inc.c", ["program.c"])
  env.Program("program.exe", %w[program.c inc.c])
 end
@@ -1,14 +1,15 @@
-Rscons::Environment.new do |env|
+env do |env|
  env["build_root"] = env.build_root
  env["inc_h"] = "inc.h"

  env.Copy("copy_inc.h", "${inc_h}")
-  env.depends("${build_root}/program.o", "${inc_h}")
-  env.Program("program.exe", ["program.c", "inc.c"])
+  env.depends("program.o", "${inc_h}")
+  env.Object("program.o", "program.c")
+  env.Program("program.exe", ["program.o", "inc.c"])

-  env.Command("inc.c",
-              [],
-              "CMD" => %w[ruby gen.rb ${_TARGET}],
-              "CMD_DESC" => "Generating")
-  env.produces("inc.c", "inc.h")
+  inc_c = env.Command("inc.c",
+                      [],
+                      "CMD" => %w[ruby gen.rb ${_TARGET}],
+                      "CMD_DESC" => "Generating")
+  inc_c.produces("inc.h")
 end
@@ -0,0 +1,15 @@
+env do |env|
+  env["build_root"] = env.build_root
+  env["inc_h"] = "inc.h"
+
+  env.Copy("copy_inc.h", "${inc_h}")
+  env.depends("program.o", "${inc_h}")
+  env.Object("program.o", "program.c")
+  env.Program("program.exe", ["program.o", "inc.c"])
+
+  env.Command("inc.c",
+              [],
+              "CMD" => %w[ruby gen.rb ${_TARGET}],
+              "CMD_DESC" => "Generating")
+  env.produces("inc.c", "inc.h")
+end
@@ -0,0 +1,19 @@
+class MyBuilder < Rscons::Builder
+  def run(options)
+    if @thread
+      true
+    else
+      print_run_message("#{name} #{target}", nil)
+      @thread = Thread.new do
+        sleep 2
+        FileUtils.touch(@target)
+      end
+      wait_for(@thread)
+    end
+  end
+end
+
+env do |env|
+  env.add_builder(MyBuilder)
+  env.MyBuilder("foo")
+end
@@ -0,0 +1,8 @@
+configure do
+  check_d_compiler "gdc"
+end
+
+env(echo: :command) do |env|
+  env["D_IMPORT_PATH"] << "src"
+  env.Program("hello-d.exe", glob("src/*.d"))
+end
@@ -1,3 +0,0 @@
-Rscons::Environment.new(echo: :command) do |env|
-  env.Program("hello-d.exe", Rscons.glob("*.d"))
-end
@@ -0,0 +1,8 @@
+configure do
+  check_d_compiler "ldc2"
+end
+
+env(echo: :command) do |env|
+  env["D_IMPORT_PATH"] << "src"
+  env.Program("hello-d.exe", glob("src/*.d"))
+end
@@ -0,0 +1,6 @@
+env(echo: :command) do |env|
+  env["LD_LIBRARY_PATH"] << "src"
+  env.Object("main.o", "src/main.d")
+  env.Object("mod.o", "src/mod.d")
+  env.Program("hello-d.exe", ["main.o", "mod.o"])
+end