* lib/rake/*: Updated to rake 0.9.6

* doc/rake/*:  ditto
* test/rake/*:  ditto


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38514 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 56 insertions, 33 deletions

diff --git a/doc/rake/rakefile.rdoc b/doc/rake/rakefile.rdoc
index f8ae72c32a..a00c9fd21e 100644
--- a/doc/rake/rakefile.rdoc
+++ b/doc/rake/rakefile.rdoc
@@ -1,4 +1,4 @@
-= Rakefile Format (as of version 0.8.3)
+= Rakefile Format (as of version 0.8.7)
 
 First of all, there is no special format for a Rakefile.  A Rakefile
 contains executable Ruby code.  Anything legal in a ruby script is
@@ -27,7 +27,7 @@ parameter that is the name of the task.
 
 === Tasks with Prerequisites
 
-Any prerequisites are given as a list (inclosed in square brackets)
+Any prerequisites are given as a list (enclosed in square brackets)
 following the name and an arrow (=>).
 
   task :name => [:prereq1, :prereq2]
@@ -45,7 +45,7 @@ following ...
 
 Actions are defined by passing a block to the +task+ method.  Any Ruby
 code can be placed in the block.  The block may reference the task
-object via the block paramter..
+object via the block parameter.
 
   task :name => [:prereq1, :prereq2] do |t|
     # actions (may reference t)
@@ -119,14 +119,14 @@ Rake allows parallel execution of prerequisites using the following syntax:
   end
 
 In this example, +copy_files+ is a normal rake task.  Its actions are
-executed whereever all of its prerequisites are done.  The big
+executed whenever all of its prerequisites are done.  The big
 difference is that the prerequisites (+copy_src+, +copy_bin+ and
 +copy_doc+) are executed in parallel.  Each of the prerequisites are
 run in their own Ruby thread, possibly allowing faster overall runtime.
 
 === Secondary Prerequisites
 
-If any of the primary prerequites of a multitask have common secondary
+If any of the primary prerequisites of a multitask have common secondary
 prerequisites, all of the primary/parallel prerequisites will wait
 until the common prerequisites have been run.
 
@@ -183,6 +183,22 @@ argument string should be quoted.  Something like this:
 (Quoting rules vary between operating systems and shells, so make sure
 you consult the proper docs for your OS/shell).
 
+=== Tasks Arguments and the Environment
+
+Task argument values can also be picked up from the environment.  For
+example, if the "release" task expected a parameter named
+"release_version", then either
+
+   rake release[0.8.2]
+
+or
+
+   RELEASE_VERSION rake release
+
+will work.  Environment variable names must either match the task
+parameter exactly, or match an all-uppercase version of the task
+parameter.
+
 === Tasks that Expect Parameters
 
 Parameters are only given to tasks that are setup to expect them.  In
@@ -195,10 +211,10 @@ declared as:
    task :name, [:first_name, :last_name]
 
 The first argument is still the name of the task (:name in this case).
-The next to argumements are the names of the parameters expected by
+The next two arguments are the names of the parameters expected by
 :name in an array (:first_name and :last_name in the example).
 
-To access the values of the paramters, the block defining the task
+To access the values of the parameters, the block defining the task
 behaviour can now accept a second parameter:
 
    task :name, [:first_name, :last_name] do |t, args|
@@ -210,7 +226,8 @@ The first argument of the block "t" is always bound to the current
 task object.  The second argument "args" is an open-struct like object
 that allows access to the task arguments.  Extra command line
 arguments to a task are ignored.  Missing command line arguments are
-given the nil value.
+picked up from matching environment variables.  If there are no
+matching environment variables, they are given the nil value.
 
 If you wish to specify default values for the arguments, you can use
 the with_defaults method in the task body.  Here is the above example
@@ -239,11 +256,12 @@ for tasks with arguments.  For example:
 There is an older format for declaring task parameters that omitted
 the task argument array and used the :needs keyword to introduce the
 dependencies.  That format is still supported for compatibility, but
-is not recommended for use.
+is not recommended for use.  The older format may be dropped in future
+versions of rake.
 
-== Accessing Task Programatically
+== Accessing Task Programmatically
 
-Sometimes it is useful to manipulate tasks programatically in a
+Sometimes it is useful to manipulate tasks programmatically in a
 Rakefile. To find a task object, use the <tt>:[]</tt> operator on the
 <tt>Rake::Task</tt>.
 
@@ -260,7 +278,7 @@ actions.
 
    task :dont do
      Rake::Task[:doit].clear
-   end        
+   end
 
 Running this example:
 
@@ -269,7 +287,7 @@ Running this example:
   DONE
   $ rake dont doit
   (in /Users/jim/working/git/rake/x)
-  $ 
+  $
 
 The ability to programmatically manipulate tasks gives rake very
 powerful meta-programming capabilities w.r.t. task execution, but
@@ -294,7 +312,7 @@ Rake is able to find a file named "mycode.c", it will automatically
 create a task that builds "mycode.o" from "mycode.c".
 
 If the file "mycode.c" does not exist, rake will attempt
-to recursively synthesize a rule for it. 
+to recursively synthesize a rule for it.
 
 When a task is synthesized from a rule, the +source+ attribute of the
 task is set to the matching source file.  This allows us to write
@@ -312,7 +330,7 @@ The following rule is equivalent to the example above.
     proc {|task_name| task_name.sub(/\.[^.]+$/, '.c') }
   ]) do |t|
     sh "cc #{t.source} -c -o #{t.name}"
-  end    
+  end
 
 <b>NOTE:</b> Because of a _quirk_ in Ruby syntax, parenthesis are
 required on *rule* when the first argument is a regular expression.
@@ -322,7 +340,7 @@ The following rule might be used for Java files ...
   rule '.java' => [
     proc { |tn| tn.sub(/\.class$/, '.java').sub(/^classes\//, 'src/') }
   ] do |t|
-    java_compile(t.source, t.name)  
+    java_compile(t.source, t.name)
   end
 
 <b>NOTE:</b> +java_compile+ is a hypothetical method that invokes the
@@ -340,12 +358,17 @@ invoked.  This make generated dependency files difficult to use.  By
 the time rake gets around to updating the dependencies file, it is too
 late to load it.
 
-The +import+ command addresses this by specifying a file to be loaded
-_after_ the main rakefile is loaded, but _before_ any targets on the
-command line are specified.  In addition, if the file name matches an
-explicit task, that task is invoked before loading the file.  This
-allows dependency files to be generated and used in a single rake
-command invocation.
+The +Rake.import+ command addresses this by specifying a file to be
+loaded _after_ the main rakefile is loaded, but _before_ any targets
+on the command line are invoked.  In addition, if the file name
+matches an explicit task, that task is invoked before loading the
+file.  This allows dependency files to be generated and used in a
+single rake command invocation.
+
+<b>NOTE:</b> Starting in Rake version 0.9.0, the top level +import+
+command is deprecated and we recommend using the scoped
+"+Rake.import+" command mentioned above.  Future versions of Rake will
+drop support for the top level +import+ command.
 
 === Example:
 
@@ -355,7 +378,7 @@ command invocation.
     sh "makedepend -f- -- #{CFLAGS} -- #{t.prerequisites} > #{t.name}"
   end
 
-  import ".depends.mf"
+  Rake.import ".depends.mf"
 
 If ".depends" does not exist, or is out of date w.r.t. the source
 files, a new ".depends" file is generated using +makedepend+ before
@@ -374,9 +397,9 @@ then you need to use the +desc+ command to describe the task.
   task :package => [ ... ] do ... end
 
 The "-T" switch (or "--tasks" if you like to spell things out) will
-display a list of tasks that have a defined comment.  If you use
-+desc+ to describe your major tasks, you have a semi-automatic way of
-generating a summary of your Rake file.
+display a list of tasks that have a description.  If you use +desc+ to
+describe your major tasks, you have a semi-automatic way of generating
+a summary of your Rake file.
 
   traken$ rake -T
   (in /home/.../rake)
@@ -403,12 +426,12 @@ common for task names to begin to clash.  For example, if you might
 have a main program and a set of sample programs built by a single
 Rakefile.  By placing the tasks related to the main program in one
 namespace, and the tasks for building the sample programs in a
-different namespace, the task names will not will not interfer with
+different namespace, the task names will not will not interfere with
 each other.
 
 For example:
 
-  namespace "main"
+  namespace "main" do
     task :build do
       # Build the main program
     end
@@ -429,7 +452,7 @@ Nested namespaces are supported, so
 
 Note that the name given in the +task+ command is always the unadorned
 task name without any namespace prefixes.  The +task+ command always
-defines a task in the current namespace.  
+defines a task in the current namespace.
 
 === FileTasks
 
@@ -499,17 +522,17 @@ Or give it a glob pattern:
 
 == Odds and Ends
 
-=== do/end verses { }
+=== do/end versus { }
 
 Blocks may be specified with either a +do+/+end+ pair, or with curly
 braces in Ruby.  We _strongly_ recommend using +do+/+end+ to specify the
 actions for tasks and rules.  Because the rakefile idiom tends to
-leave off parenthesis on the task/file/rule methods, unusual
+leave off parentheses on the task/file/rule methods, unusual
 ambiguities can arise when using curly braces.
 
 For example, suppose that the method +object_files+ returns a list of
 object files in a project.  Now we use +object_files+ as the
-prerequistes in a rule specified with actions in curly braces.
+prerequisites in a rule specified with actions in curly braces.
 
   # DON'T DO THIS!
   file "prog" => object_files {
@@ -531,4 +554,4 @@ This is the proper way to specify the task ...
 
 == See
 
-* README -- Main documentation for Rake.
+* README.rdoc -- Main documentation for Rake.