drake 0.8.7.0.2.4 → 0.9.0.0.3.0

data/Rakefile-drake

@@ -0,0 +1,67 @@
+
+def git(*args)
+  sh "git", *args
+end
+
+task :drake_pull_mainline do
+  git "pull",
+      "--no-commit",
+      "git://github.com/jimweirich/rake.git",
+      "refs/heads/master:refs/heads/origin"
+end
+
+task :drake_check_directory do
+  unless `git status` =~ %r!nothing to commit \(working directory clean\)!
+    raise "Directory not clean"
+  end
+end
+
+task :drake_prerelease => [:clobber, :gemspec, :drake_check_directory] do
+  unless `git pull` =~ %r!Already up-to-date!
+    raise "New stuff from remote repository"
+  end
+  %w[github.com].each { |server|
+    cmd = "ping " + (
+      if Config::CONFIG["host"] =~ %r!darwin!
+        "-c2 #{server}"
+      else
+        "#{server} 2 2"
+      end
+    )
+    unless `#{cmd}` =~ %r!0% packet loss!
+      raise "No ping for #{server}"
+    end
+  }
+end
+
+task :drake_publish => :rdoc do
+  Dir.chdir("html") {
+    sh "scp", "-r", ".", "quix@rubyforge.org:/var/www/gforge-projects/drake"
+  }
+  git "branch", "-D", "gh-pages"
+  git "checkout", "--orphan", "gh-pages"
+  FileUtils.rm ".git/index"
+  git "clean", "-fdx", "-e", "html"
+  Dir["html/*"].each { |path|
+    FileUtils.mv path, "."
+  }
+  FileUtils.rmdir "html"
+  git "add", "."
+  git "commit", "-m", "generated by rdoc"
+  git "push", "-f", "origin", "gh-pages"
+end
+
+task :drake_finish_release do
+  git "tag", "drake-#{SPEC.version}"
+  git "push", "--tags", "origin", "master"
+  sh "gem", "push", gem
+end
+
+task :drake_release =>
+  [
+   :drake_prerelease,
+   :gem,
+   "test:all",
+   :drake_finish_release,
+  ]
+

data/TODO

@@ -6,7 +6,7 @@ the rake-devel@rubyforge.org mailing list.
 === To Do
 * Need a nice API for accessing tasks in namespaces, namespaces in an app, etc.
 * Provide a way to disable -w warning mode.
-* Define a set of default rules that work in the absense of any Rakefile
+* Define a set of default rules that work in the absence of any Rakefile
 * What about cyclic dependencies?
 * Java support utilities
 * Installation support utilities

data/bin/drake

@@ -3,6 +3,8 @@
 #--
 # Copyright (c) 2003, 2004, 2005, 2006, 2007  Jim Weirich
 #
+# Copyright (c) 2008-2011 James M. Lawrence
+#
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
 # deal in the Software without restriction, including without limitation the

data/doc/command_line_usage.rdoc

@@ -9,7 +9,7 @@ Options are:
 [<tt><em>name</em>=<em>value</em></tt>]
     Set the environment variable <em>name</em> to <em>value</em>
     during the execution of the <b>rake</b> command.  You can access
-    the value by using ENV['<em>name</em>'].  
+    the value by using ENV['<em>name</em>'].
 
 [<tt>--classic-namespace</tt> (-n)]
     Import the Task, FileTask, and FileCreateTask into the top-level
@@ -42,6 +42,8 @@ Options are:
 
 [<tt>--threads</tt> _number_ (-j)]
     Run up to N independent tasks simultaneously in separate threads.
+    If _number_ is not given, run as many tasks in parallel as the
+    dependencies allow.
 
 [<tt>--nosearch</tt>  (-N)]
     Do not search for a Rakefile in parent directories.
@@ -63,11 +65,11 @@ Options are:
 [<tt>--rakelibdir</tt> _rakelibdir_ (-R)]
     Auto-import any .rake files in RAKELIBDIR. (default is 'rakelib')
 
-[<tt>--randomize</tt>[=_seed_]]
-    Randomize the order of sibling prerequisites for each task.  When
-    _seed_ is given, <tt>srand(seed.hash)</tt> will be called so that
-    the same permutations will be produced for subsequent runs with
-    the same _seed_.
+[<tt>--randomize</tt> _seed_]
+    Randomize the order of sibling prerequisites for each task. Runs
+    with the same _seed_ will produce the same sibling permutations.
+    If no _seed_ is given then one will be generated. _seed_ is
+    reported when Rake exits.
 
 [<tt>--require</tt> _name_ (-r)]
     Require _name_ before executing the Rakefile.
@@ -89,23 +91,35 @@ Options are:
     Use the project level Rakefile, ignoring the system-wide (global)
     rakefiles.
 
-[<tt>--tasks</tt> (-T)]
+[<tt>--tasks</tt> <em>pattern</em> (-T)]
     Display a list of the major tasks and their comments.  Comments
-    are defined using the "desc" command.
+    are defined using the "desc" command.  If a pattern is given, then
+    only tasks matching the pattern are displayed.
+
+[<tt>--no-top-level-dsl</tt> (-X)]
+    Do not put the Rake DSL commands into the top level scope.
+
+[<tt>--top-level-dsl</tt>]
+    Put the Rake DSL commands into the top level scope (default).
+
+    NOTE: Although currently Rake defaults to its DSL in the top level
+    scope, the plan is to deprecate this in the future and default ot
+    having the DSL commands *not* appear in the top level scope.
 
 [<tt>--trace</tt> (-t)]
     Turn on invoke/execute tracing. Also enable full backtrace on
     errors.
 
-[<tt>--usage</tt> (-h)]
-    Display a usage message and exit.
-
 [<tt>--verbose</tt> (-v)]
     Echo the Sys commands to standard output.
 
 [<tt>--version</tt> (-V)]
     Display the program version and exit.
 
+[<tt>--where</tt> <em>pattern</em> (-W)]
+    Display tasks that match <em>pattern</em> and the file and line
+    number where the task is defined.
+
 In addition, any command line option of the form
 <em>VAR</em>=<em>VALUE</em> will be added to the environment hash
 <tt>ENV</tt> and may be tested in the Rakefile.

data/doc/glossary.rdoc

@@ -37,9 +37,9 @@
 	not needed.  This may change in the future.
 
 [<b>prerequisites</b>]
-	Every task has a set (possiblity empty) of prerequisites.  A
+	Every task has a set (possibly empty) of prerequisites.  A
 	prerequisite P to Task T is itself a task that must be invoked
-	before Task T.  
+	before Task T.
 
 [<b>rule</b>]
 	A rule is a recipe for synthesizing a task when no task is

data/doc/jamis.rb

@@ -183,7 +183,7 @@ h3, h4, h5, h6 {
 CSS
 
 XHTML_PREAMBLE = %{<?xml version="1.0" encoding="%charset%"?>
-<!DOCTYPE html 
+<!DOCTYPE html
      PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 }
@@ -510,7 +510,7 @@ FILE_INDEX = XHTML_PREAMBLE + <<HTML
 <!--
   body {
     background-color: #EEE;
-    font-family: #{FONTS}; 
+    font-family: #{FONTS};
     color: #000;
     margin: 0px;
   }

data/doc/parallel.rdoc

@@ -29,8 +29,8 @@ short answer is probably that +multitask+ was easy to implement, while
 dynamically finding parallelizable tasks and safely executing them in
 separate threads requires a little more code.
 
-Rake now supports the -j option which does exactly this.  To run up to
-three tasks in parallel,
+Rake now supports the +-j+ option which does exactly this. To run up
+to three tasks in parallel,
 
   % rake -j3
 
@@ -38,33 +38,40 @@ or equivalently,
 
   % rake --threads 3
 
+Without a number,
+
+  % rake -j
+
+means as many tasks as possible will run in parallel: the dependency
+graph alone determines the number.
+
 == A Note on Dependencies
 
-Without +multitask+ or -j (or --randomize, explained below), Rake
-invokes tasks in a predetermined order.  Rakefile authors inevitably
-come to rely on this order.  Even though their dependency graph may be
-wide and hierarchical, the only graph which has ever been tested is
-linear: one which results from visiting each node in sequence.
+Without +multitask+ or +-j+, Rake invokes tasks in a predetermined
+order. Rakefile authors inevitably come to rely on this order. Even
+though their dependency graph may be wide and hierarchical, the only
+graph which has ever been tested is linear: one which results from
+visiting each node in sequence.
 
 Consider
 
    task :a => [:x, :y, :z]
 
-When Rake runs in single-threaded mode (the default), _x_,_y_,_z_ will
-be invoked <em>in that order</em> before _a_ is invoked, assuming no
-other rules exist involving these tasks.  However with -j _N_ for
-_N_ > 1, one should not expect any particular order of execution.
-Since there is no dependency specified between _x_,_y_,_z_ above, Rake
-is free to run them in any order.
+When Rake runs in single-threaded mode (the default), tasks
+_x_,_y_,_z_ will be invoked <em>in that order</em> before _a_ is
+invoked, assuming no other rules exist involving these tasks. However
+with +-j+ _N_ for _N_ > 1, one should not expect any
+particular order of execution. Since there is no dependency specified
+between _x_,_y_,_z_ above, Rake is free to run them in any order.
 
 The problem of underspecified dependencies plagues Makefiles as well
-(GNU make has supported -j for some time).
+(GNU make has supported +-j+ for some time).
 
-== Migrating to -j
+== Migrating to +-j+
 
-Suppose -j produces errors from insufficient dependencies in your
-Rakefile.  Do you want to bother fixing them?  If you are satisfied
-with your build time, then there is really no reason to use -j.
+Suppose +-j+ produces errors from insufficient dependencies in your
+Rakefile. Do you want to bother fixing them? If you are satisfied with
+your build time then there is really no reason to use +-j+.
 
 If on the other hand your build takes twenty minutes to complete, you
 may be interested in getting the full dependency graph correct in
@@ -76,10 +83,10 @@ saying what you mean:
 
   % rake --randomize[=SEED]
 
-This will randomize the order of sibling prerequisites for each task.
-When SEED is given, <tt>srand(SEED.hash)</tt> will be called so that
-the same permutations will be produced for subsequent runs with the
-same SEED.
+where the optional SEED is an integer. This will randomize the order
+of sibling prerequisites for each task. Runs with the same SEED will
+produce the same sibling permutations. If no SEED is given then one
+will be generated. SEED is reported when Rake exits.
 
 Though this option may cause an error due to underspecified
 dependencies, with SEED at least it will be an error which is exactly
@@ -89,15 +96,15 @@ advantage of using a single thread.
 == Task#invoke inside Task#invoke
 
 Parallelizing tasks means surrendering control over the
-micro-management of their execution.  Manually invoking tasks inside
+micro-management of their execution. Manually invoking tasks inside
 other tasks is rather contrary to this notion, throwing a monkey
-wrench into the system.  An exception will be raised when this is
-attempted in -j mode.
+wrench into the system. An exception will be raised when this is
+attempted in +-j+ mode.
 
-== What is the Difference Between -j and Multitask?
+== What is the Difference Between +-j+ and Multitask?
 
 What if you replaced +task+ with +multitask+ everywhere in your
-Rakefile?  Isn't that the same as -j?
+Rakefile?  Isn't that the same as +-j+?
 
 It is effectively the same when the number of tasks is small.  However
 an all-multitask Rakefile becomes problematic as the number of tasks
@@ -107,6 +114,7 @@ Multitask blindly fires off N threads for the N prerequisites of a
 task.
 
 A simplistic +multitask+ setup for compiling 100 C files might spawn
-100 threads running 100 compiler processes all at the same time.  To
+100 threads running 100 compiler processes all at the same time. To
 reduce the load you could make several reasonably-sized multitasks
-then tie them together with a regular +task+.  Or you could just use -j.
+then tie them together with a regular +task+. Or you could just use
++-j+.

data/doc/proto_rake.rdoc

@@ -4,54 +4,54 @@ This is the original 100 line prototype rake program.
 
 ---
  #!/usr/bin/env ruby
- 
+
  require 'ftools'
- 
+
  class Task
    TASKS = Hash.new
- 
+
    attr_reader :prerequisites
- 
+
    def initialize(task_name)
      @name = task_name
      @prerequisites = []
      @actions = []
    end
- 
+
    def enhance(deps=nil, &block)
      @prerequisites |= deps if deps
      @actions << block if block_given?
      self
    end
- 
+
    def name
      @name.to_s
    end
- 
+
    def invoke
      @prerequisites.each { |n| Task[n].invoke }
      execute if needed?
    end
- 
+
    def execute
      return if @triggered
      @triggered = true
      @actions.collect { |act| result = act.call(self) }.last
    end
- 
+
    def needed?
      true
    end
- 
+
    def timestamp
      Time.now
    end
- 
+
    class << self
      def [](task_name)
        TASKS[intern(task_name)] or fail "Don't know how to rake #{task_name}"
      end
-     
+
      def define_task(args, &block)
        case args
        when Hash
@@ -66,18 +66,18 @@ This is the original 100 line prototype rake program.
        deps = deps.collect {|d| intern(d) }
        get(task_name).enhance(deps, &block)
      end
- 
+
      def get(task_name)
        name = intern(task_name)
        TASKS[name] ||= self.new(name)
      end
- 
+
      def intern(task_name)
        (Symbol === task_name) ? task_name : task_name.intern
      end
    end
  end
- 
+
  class FileTask < Task
    def needed?
      return true unless File.exist?(name)
@@ -85,25 +85,25 @@ This is the original 100 line prototype rake program.
      return false if latest_prereq.nil?
      timestamp < latest_prereq
    end
- 
+
    def timestamp
      File.new(name.to_s).mtime
    end
  end
- 
+
  def task(args, &block)
    Task.define_task(args, &block)
  end
- 
+
  def file(args, &block)
    FileTask.define_task(args, &block)
  end
- 
+
  def sys(cmd)
    puts cmd
    system(cmd) or fail "Command Failed: [#{cmd}]"
  end
-   
+
  def rake
    begin
      here = Dir.pwd
@@ -119,9 +119,9 @@ This is the original 100 line prototype rake program.
    rescue Exception => ex
      puts "rake aborted ... #{ex.message}"
      puts ex.backtrace.find {|str| str =~ /Rakefile/ } || ""
-   end    
+   end
  end
- 
+
  if __FILE__ == $0 then
    rake
  end

data/doc/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.
 
@@ -154,7 +154,7 @@ user must do whatever is necessary to prevent race conditions.
 
 Rake now supports the command-line option -j for automatically
 detecting non-dependent tasks and safely executing them in parallel.
-See parallel.rdoc.
+See parallel.rdoc[http://quix.github.com/rake/files/doc/parallel_rdoc.html].
 
 == Tasks with Arguments
 
@@ -189,6 +189,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
@@ -201,10 +217,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|
@@ -216,7 +232,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
@@ -245,11 +262,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>.
 
@@ -266,7 +284,7 @@ actions.
 
    task :dont do
      Rake::Task[:doit].clear
-   end        
+   end
 
 Running this example:
 
@@ -275,7 +293,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
@@ -300,7 +318,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
@@ -318,7 +336,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.
@@ -328,7 +346,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
@@ -346,12 +364,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:
 
@@ -361,7 +384,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
@@ -380,9 +403,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)
@@ -409,7 +432,7 @@ 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:
@@ -435,7 +458,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
 
@@ -505,17 +528,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 {
@@ -537,4 +560,4 @@ This is the proper way to specify the task ...
 
 == See
 
-* README -- Main documentation for Rake.
+* README.rdoc -- Main documentation for Rake.