From f278b211f783c8ed76fb7d7af45d3d045840370b Mon Sep 17 00:00:00 2001
From: Josh Holtrop <jholtrop@gmail.com>
Date: Fri, 14 Feb 2014 09:50:39 -0500
Subject: [PATCH] README: add more information about custom builders

---
 README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/README.md b/README.md
index f4b83e3..34a5819 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,11 @@ 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)
@@ -73,10 +78,12 @@ class GenerateFoo < Rscons::Builder
 #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", Dir["*.c"])
 end
@@ -93,16 +100,23 @@ class CmdBuilder < Rscons::Builder
       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
 ```
 
 ### 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)
@@ -112,6 +126,7 @@ class CmdBuilder < Rscons::Builder
 end
 
 Rscons::Environment.new do |env|
+  env.add_builder(CmdBuilder.new)
   env.CmdBuilder("foo.gen", "foo_gen.cfg")
 end
 ```