begin expanding README documentation

README.md

@@ -6,7 +6,7 @@ Software construction library inspired by SCons and implemented in Ruby
 
 Add this line to your application's Gemfile:
 
-    gem 'rscons'
+    gem "rscons"
 
 And then execute:
 
@@ -18,20 +18,135 @@ Or install it yourself as:
 
 ## Usage
 
-    RScons::Environment.new do |env|
+Rscons is a Ruby library.
-      env.Program('program', Dir['*.c'])
+It can be called from a standalone Ruby script or it can be used with rake and
-    end
+called from your Rakefile.
 
+### Example: Building a C Program
+
+```ruby
+RScons::Environment.new do |env|
+  env["CFLAGS"] << "-Wall"
+  env.Program("program", Dir["**/*.c"])
+end
+```
+
+### Example: Building a D Program
+
+```ruby
+RScons::Environment.new do |env|
+  env["DFLAGS"] << "-Wall"
+  env.Program("program", Dir["**/*.d"])
+end
+```
+
+### Example: Cloning an Environment
+
+```ruby
 main_env = RScons::Environment.new do |env|
-      env.build_dir('src', 'build/main')
+  # Store object files from sources under "src" in "build/main"
-      env.Program('program', Dir['src/**/*.cc'])
+  env.build_dir("src", "build/main")
+  env["CFLAGS"] = ["-DSOME_DEFINE", "-O3"]
+  env["LIBS"] = ["SDL"]
+  env.Program("program", Dir["src/**/*.cc"])
 end
 
 debug_env = main_env.clone do |env|
-      env.build_dir('src', 'build/debug')
+  # Store object files from sources under "src" in "build/debug"
-      env['CFLAGS'] = ['-g', '-O0']
+  env.build_dir("src", "build/debug")
-      env.Program('program-debug', Dir['src/**/*.cc'])
+  env["CFLAGS"] -= ["-O3"]
+  env["CFLAGS"] += ["-g", "-O0"]
+  env.Program("program-debug", Dir["src/**/*.cc"])
 end
+```
+
+### Example: Custom Builder
+
+```ruby
+class GenerateFoo < Rscons::Builder
+  def run(target, sources, cache, env, vars)
+    File.open(target, "w") do |fh|
+      fh.puts <<EOF
+#define GENERATED 42
+EOF
+    end
+  end
+end
+
+Rscons::Environment.new do |env|
+  env.GenerateFoo("foo.h", [])
+  env.Program("a.out", Dir["*.c"])
+end
+```
+
+### Example: Using different compilation flags for some sources
+
+```ruby
+Rscons::Environment.new do |env|
+  env["CFLAGS"] = ["-O3", "-Wall", "-DDEFINE"]
+  env.add_tweaker do |build_op|
+    if build_op[:target] =~ %r{build/third-party}
+      build_op[:vars]["CFLAGS"] -= ["-Wall"]
+    end
+  end
+  env.build_dir("src", "build")
+  env.Program("program", Dir["**/*.cc"])
+end
+```
+
+### Example: Creating a static library
+
+```ruby
+Rscons::Environment.new do |env|
+  env.Library("mylib.a", Dir["src/**/*.c"])
+end
+```
+
+## Details
+
+### Default Builders
+
+Rscons ships with a number of default builders:
+
+* Library, which collects object files into a static library archive file
+* Object, which compiles source files to produce an object file
+* Program, which links object files to produce an executable
+
+If you want to create an Environment that does not contain any (or select)
+builders, you can use the `exclude_builders` key to the Environment constructor.
+
+### Managing Environments
+
+An Rscons::Environment consists of:
+
+* a collection of construction variables
+* a collection of builders
+* a mapping of build directories
+* a collection of targets to build
+* a collection of tweakers
+
+When cloning an environment, the construction variables, builders, and build
+directories are cloned, but the new environment does not inherit any of the
+targets or tweakers from the source environment.
+
+Cloned environments contain "deep copies" of construction variables.
+For example, in:
+
+```ruby
+base_env = Rscons::Environment.new
+base_env["CPPPATH"] = ["one", "two"]
+cloned_env = base_env.clone
+cloned_env["CPPPATH"] << "three"
+```
+
+`base_env["CPPPATH"]` will not include "three".
+
+### Construction Variables
+
+The default construction variables that Rscons uses are named using uppercase
+strings.
+Rscons options are lowercase symbols.
+Lowercase strings are reserved as user-defined construction variables.
 
 ## Contributing