rake 0.7.3 → 0.8.7

data/Rakefile

@@ -16,14 +16,17 @@ require 'rake/clean'
 require 'rake/testtask'
 require 'rake/rdoctask'
 
-CLEAN.include('**/*.o', '*.dot')
+CLEAN.include('**/*.o', '*.dot', '**/.*.rbc')
 CLOBBER.include('doc/example/main', 'testdata')
 CLOBBER.include('test/data/**/temp_*')
 CLOBBER.include('test/data/chains/play.*')
 CLOBBER.include('test/data/file_creation_task/build')
 CLOBBER.include('test/data/file_creation_task/src')
 CLOBBER.include('TAGS')
-CLOBBER.include('coverage')
+CLOBBER.include('coverage', 'rcov_aggregate')
+
+# Prevent OS X from including extended attribute junk in the tar output
+ENV['COPY_EXTENDED_ATTRIBUTES_DISABLE'] = 'true'
 
 def announce(msg='')
   STDERR.puts msg
@@ -37,11 +40,7 @@ else
   CURRENT_VERSION = "0.0.0"
 end
 
-if ENV['REL']
-  PKG_VERSION = ENV['REL']
-else
-  PKG_VERSION = CURRENT_VERSION
-end
+$package_version = CURRENT_VERSION
 
 SRC_RB = FileList['lib/**/*.rb']
 
@@ -51,6 +50,9 @@ desc "Default Task"
 task :default => :test_all
 
 # Test Tasks ---------------------------------------------------------
+task :dbg do |t|
+  puts "Arguments are: #{t.args.join(', ')}"
+end
 
 # Common Abbreviations ...
 
@@ -79,13 +81,13 @@ end
 Rake::TestTask.new(:test_functional) do |t|
   t.test_files = FileList['test/fun*.rb']
   t.warning = true
-  t.warning = true
+  t.verbose = false
 end
 
 Rake::TestTask.new(:test_contribs) do |t|
   t.test_files = FileList['test/contrib/test*.rb']
-  t.verbose = false
   t.warning = true
+  t.verbose = false
 end
 
 begin
@@ -93,15 +95,21 @@ begin
 
   Rcov::RcovTask.new do |t|
     t.libs << "test"
-    t.rcov_opts = ['-xRakefile', '-xrakefile', '-xpublish.rf', '--text-report']
+    dot_rakes = 
+    t.rcov_opts = [
+      '-xRakefile', '-xrakefile', '-xpublish.rf',
+      '-xlib/rake/contrib', '-x/Library', 
+      '--text-report',
+      '--sort coverage'
+    ] + FileList['rakelib/*.rake'].pathmap("-x%p")
     t.test_files = FileList[
-      'test/test*.rb',
-      'test/contrib/test*.rb'
+      'test/test*.rb', 'test/functional.rb'
     ]
+    t.output_dir = 'coverage'
     t.verbose = true
   end
 rescue LoadError
-  # No rcov available
+  puts "RCov is not available"
 end
 
 directory 'testdata'
@@ -120,19 +128,30 @@ end
 
 # Create a task to build the RDOC documentation tree.
 
-rd = Rake::RDocTask.new("rdoc") { |rdoc|
+begin
+  require 'darkfish-rdoc'
+  DARKFISH_ENABLED = true
+rescue LoadError => ex
+  DARKFISH_ENABLED = false
+end
+
+BASE_RDOC_OPTIONS = [
+  '--line-numbers',
+  '--main', 'README',
+  '--title', 'Rake -- Ruby Make',
+]
+
+rd = Rake::RDocTask.new("rdoc") do |rdoc|
   rdoc.rdoc_dir = 'html'
-#  rdoc.template = 'kilmer'
-#  rdoc.template = 'css2'
   rdoc.template = 'doc/jamis.rb'
   rdoc.title    = "Rake -- Ruby Make"
-  rdoc.options << '--line-numbers' << '--inline-source' <<
-    '--main' << 'README' <<
-    '--title' <<  'Rake -- Ruby Make' 
+  rdoc.options = BASE_RDOC_OPTIONS.dup
+  rdoc.options << '-SHN' << '-f' << 'darkfish' if DARKFISH_ENABLED
+    
   rdoc.rdoc_files.include('README', 'MIT-LICENSE', 'TODO', 'CHANGES')
   rdoc.rdoc_files.include('lib/**/*.rb', 'doc/**/*.rdoc')
   rdoc.rdoc_files.exclude(/\bcontrib\b/)
-}
+end
 
 # ====================================================================
 # Create a task that will package the Rake software into distributable
@@ -147,20 +166,22 @@ PKG_FILES = FileList[
   'test/**/*.rf',
   'test/**/*.mf',
   'test/**/Rakefile',
+  'test/**/subdir',
   'doc/**/*'
 ]
 PKG_FILES.exclude('doc/example/*.o')
+PKG_FILES.exclude('TAGS')
 PKG_FILES.exclude(%r{doc/example/main$})
 
 if ! defined?(Gem)
   puts "Package Target requires RubyGEMs"
 else
-  spec = Gem::Specification.new do |s|
+  SPEC = Gem::Specification.new do |s|
     
     #### Basic information.
 
     s.name = 'rake'
-    s.version = PKG_VERSION
+    s.version = $package_version
     s.summary = "Ruby based make-like utility."
     s.description = <<-EOF
       Rake is a Make-like program implemented in Ruby. Tasks
@@ -192,7 +213,7 @@ else
 
     s.has_rdoc = true
     s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
-    s.rdoc_options = rd.options
+    s.rdoc_options = BASE_RDOC_OPTIONS
 
     #### Author and project details.
 
@@ -206,10 +227,18 @@ else
 #     end
   end
 
-  package_task = Rake::GemPackageTask.new(spec) do |pkg|
+  package_task = Rake::GemPackageTask.new(SPEC) do |pkg|
     pkg.need_zip = true
     pkg.need_tar = true
   end
+
+  file "rake.gemspec" => ["Rakefile", "lib/rake.rb"] do |t|
+    require 'yaml'
+    open(t.name, "w") { |f| f.puts SPEC.to_yaml }
+  end
+
+  desc "Create a stand-alone gemspec"
+  task :gemspec => "rake.gemspec"
 end
 
 # Misc tasks =========================================================
@@ -246,12 +275,6 @@ task :lines do
   show_line("TOTAL", total_lines, total_code)
 end
 
-ARCHIVEDIR = '/mnt/usb'
-
-task :archive => [:package] do
-  cp FileList["pkg/*.tgz", "pkg/*.zip", "pkg/*.gem"], ARCHIVEDIR
-end
-
 # Define an optional publish target in an external file.  If the
 # publish.rf file is not found, the publish targets won't be defined.
 
@@ -259,86 +282,108 @@ load "publish.rf" if File.exist? "publish.rf"
 
 # Support Tasks ------------------------------------------------------
 
+RUBY_FILES = FileList['**/*.rb'].exclude('pkg')
+
 desc "Look for TODO and FIXME tags in the code"
 task :todo do
-  FileList['**/*.rb'].exclude('pkg').egrep(/#.*(FIXME|TODO|TBD)/)
+  RUBY_FILES.egrep(/#.*(FIXME|TODO|TBD)/)
 end
 
 desc "Look for Debugging print lines"
 task :dbg do
-  FileList['**/*.rb'].egrep(/\bDBG|\bbreakpoint\b/)
+  RUBY_FILES.egrep(/\bDBG|\bbreakpoint\b/)
 end
 
 desc "List all ruby files"
 task :rubyfiles do 
-  puts Dir['**/*.rb'].reject { |fn| fn =~ /^pkg/ }
-  puts Dir['bin/*'].reject { |fn| fn =~ /CVS|(~$)|(\.rb$)/ }
+  puts RUBY_FILES
+  puts FileList['bin/*'].exclude('bin/*.rb')
 end
 task :rf => :rubyfiles
 
+desc "Create a TAGS file"
+task :tags => "TAGS"
+
+TAGS = 'xctags -e'
+
+file "TAGS" => RUBY_FILES do
+  puts "Makings TAGS"
+  sh "#{TAGS} #{RUBY_FILES}", :verbose => false
+end
+
 # --------------------------------------------------------------------
 # Creating a release
 
+def plugin(plugin_name)
+  require "rake/plugins/#{plugin_name}"
+end
+
+task :noop
+#plugin "release_manager"
+
 desc "Make a new release"
-task :release => [
-  :prerelease,
-  :clobber,
-  :test_all,
-  :update_version,
-  :package,
-  :tag] do
-  
+task :release, :rel, :reuse, :reltest,
+  :needs => [
+    :prerelease,
+    :clobber,
+    :test_all,
+    :update_version,
+    :package,
+    :tag
+  ] do
   announce 
   announce "**************************************************************"
-  announce "* Release #{PKG_VERSION} Complete."
+  announce "* Release #{$package_version} Complete."
   announce "* Packages ready to upload."
   announce "**************************************************************"
   announce 
 end
 
 # Validate that everything is ready to go for a release.
-task :prerelease do
+task :prerelease, :rel, :reuse, :reltest do |t, args|
+  $package_version = args.rel
   announce 
   announce "**************************************************************"
-  announce "* Making RubyGem Release #{PKG_VERSION}"
+  announce "* Making RubyGem Release #{$package_version}"
   announce "* (current version #{CURRENT_VERSION})"
   announce "**************************************************************"
   announce  
 
   # Is a release number supplied?
-  unless ENV['REL']
-    fail "Usage: rake release REL=x.y.z [REUSE=tag_suffix]"
+  unless args.rel
+    fail "Usage: rake release[X.Y.Z] [REUSE=tag_suffix]"
   end
 
   # Is the release different than the current release.
   # (or is REUSE set?)
-  if PKG_VERSION == CURRENT_VERSION && ! ENV['REUSE']
-    fail "Current version is #{PKG_VERSION}, must specify REUSE=tag_suffix to reuse version"
+  if $package_version == CURRENT_VERSION && ! args.reuse
+    fail "Current version is #{$package_version}, must specify REUSE=tag_suffix to reuse version"
   end
 
   # Are all source files checked in?
-  if ENV['RELTEST']
+  if args.reltest
     announce "Release Task Testing, skipping checked-in file test"
   else
     announce "Checking for unchecked-in files..."
-    data = `cvs -q update`
+    data = `svn st`
     unless data =~ /^$/
-      fail "CVS update is not clean ... do you have unchecked-in files?"
+      abort "svn status is not clean ... do you have unchecked-in files?"
     end
     announce "No outstanding checkins found ... OK"
   end
 end
 
-task :update_version => [:prerelease] do
-  if PKG_VERSION == CURRENT_VERSION
+task :update_version, :rel, :reuse, :reltest,
+  :needs => [:prerelease] do |t, args|
+  if args.rel == CURRENT_VERSION
     announce "No version change ... skipping version update"
   else
-    announce "Updating Rake version to #{PKG_VERSION}"
+    announce "Updating Rake version to #{args.rel}"
     open("lib/rake.rb") do |rakein|
       open("lib/rake.rb.new", "w") do |rakeout|
 	rakein.each do |line|
 	  if line =~ /^RAKEVERSION\s*=\s*/
-	    rakeout.puts "RAKEVERSION = '#{PKG_VERSION}'"
+	    rakeout.puts "RAKEVERSION = '#{args.rel}'"
 	  else
 	    rakeout.puts line
 	  end
@@ -346,23 +391,24 @@ task :update_version => [:prerelease] do
       end
     end
     mv "lib/rake.rb.new", "lib/rake.rb"
-    if ENV['RELTEST']
+    if args.reltest
       announce "Release Task Testing, skipping commiting of new version"
     else
-      sh %{cvs commit -m "Updated to version #{PKG_VERSION}" lib/rake.rb} # "
+      sh %{svn commit -m "Updated to version #{args.rel}" lib/rake.rb} # "
     end
   end
 end
 
 desc "Tag all the CVS files with the latest release number (REL=x.y.z)"
-task :tag => [:prerelease] do
-  reltag = "REL_#{PKG_VERSION.gsub(/\./, '_')}"
-  reltag << ENV['REUSE'].gsub(/\./, '_') if ENV['REUSE']
-  announce "Tagging CVS with [#{reltag}]"
-  if ENV['RELTEST']
+task :tag, :rel, :reuse, :reltest,
+  :needs => [:prerelease] do |t, args|
+  reltag = "REL_#{args.rel.gsub(/\./, '_')}"
+  reltag << args.reuse.gsub(/\./, '_') if args.reuse
+  announce "Tagging Repository with [#{reltag}]"
+  if args.reltest
     announce "Release Task Testing, skipping CVS tagging"
   else
-    sh %{cvs tag #{reltag}}
+    sh %{svn copy svn+ssh://rubyforge.org/var/svn/rake/trunk svn+ssh://rubyforge.org/var/svn/rake/tags/#{reltag} -m 'Commiting release #{reltag}'} ###'
   end
 end
 
@@ -378,6 +424,7 @@ end
 
 load 'xforge.rf' if File.exist?('xforge.rf')
 
+desc "Where is the current directory.  This task displays\nthe current rake directory"
 task :where_am_i do
   puts Rake.original_dir
 end

data/TODO

@@ -4,6 +4,7 @@ Send suggestions for this list to mailto:jim@weirichhouse.org or on
 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
 * What about cyclic dependencies?

data/bin/rake

@@ -1,3 +1,27 @@
+#!/usr/bin/env ruby
+
+#--
+# Copyright (c) 2003, 2004, 2005, 2006, 2007  Jim Weirich
+#
+# 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
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 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.
+#++
+
 begin
   require 'rake'
 rescue LoadError

data/doc/command_line_usage.rdoc

@@ -0,0 +1,102 @@
+= Rake Command Line Usage
+
+Rake is invoked from the command line using:
+
+   % rake [<em>options</em> ...]  [<em>VAR</em>=<em>VALUE</em>]  [<em>targets</em> ...]
+
+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>'].  
+
+[<tt>--classic-namespace</tt> (-n)]
+    Import the Task, FileTask, and FileCreateTask into the top-level
+    scope to be compatible with older versions of Rake.  Alternatively
+    you can include the line <code>require
+    'rake/classic_namespace'</code> in your Rakefile to get the
+    classic behavior.
+
+[<tt>--describe</tt> _pattern_ (-D)]
+    Describe the tasks (matching optional PATTERN), then exit.
+
+[<tt>--dry-run</tt> (-n)]
+    Do a dry run.  Print the tasks invoked and executed, but do not
+    actually execute any of the actions.
+
+[<tt>--execute</tt> _code_ (-e)]
+    Execute some Ruby code and exit.
+
+[<tt>--execute-print</tt> _code_ (-p)]
+    Execute some Ruby code, print the result, and exit.
+
+[<tt>--execute-continue</tt> _code_ (-p)]
+    Execute some Ruby code, then continue with normal task processing.
+
+[<tt>--help</tt>  (-H)]
+    Display some help text and exit.
+
+[<tt>--libdir</tt> _directory_  (-I)]
+    Add _directory_ to the list of directories searched for require.
+
+[<tt>--nosearch</tt>  (-N)]
+    Do not search for a Rakefile in parent directories.
+
+[<tt>--prereqs</tt>  (-P)]
+    Display a list of all tasks and their immediate prerequisites.
+
+[<tt>--quiet</tt> (-q)]
+    Do not echo commands from FileUtils.
+
+[<tt>--rakefile</tt> _filename_ (-f)]
+    Use _filename_ as the name of the rakefile. The default rakefile
+    names are +rakefile+ and +Rakefile+ (with +rakefile+ taking
+    precedence). If the rakefile is not found in the current
+    directory, +rake+ will search parent directories for a match. The
+    directory where the Rakefile is found will become the current
+    directory for the actions executed in the Rakefile.
+
+[<tt>--rakelibdir</tt> _rakelibdir_ (-R)]
+    Auto-import any .rake files in RAKELIBDIR. (default is 'rakelib')
+
+[<tt>--require</tt> _name_ (-r)]
+    Require _name_ before executing the Rakefile.
+
+[<tt>--rules</tt>]
+    Trace the rules resolution.
+
+[<tt>--silent (-s)</tt>]
+    Like --quiet, but also suppresses the 'in directory' announcement.
+
+[<tt>--system</tt> (-g)]
+    Use the system wide (global) rakefiles. The project Rakefile is
+    ignored. By default, the system wide rakefiles are used only if no
+    project Rakefile is found. On Unix-like system, the system wide
+    rake files are located in $HOME/.rake. On a windows system they
+    are stored in $APPDATA/Rake.
+
+[<tt>--no-system</tt> (-G)]
+    Use the project level Rakefile, ignoring the system-wide (global)
+    rakefiles.
+
+[<tt>--tasks</tt> (-T)]
+    Display a list of the major tasks and their comments.  Comments
+    are defined using the "desc" command.
+
+[<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.
+
+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/rakefile.rdoc

@@ -1,4 +1,4 @@
-= Rakefile Format
+= Rakefile Format (as of version 0.8.3)
 
 First of all, there is no special format for a Rakefile.  A Rakefile
 contains executable Ruby code.  Anything legal in a ruby script is
@@ -150,6 +150,131 @@ to do extra synchronization for Rake's benefit.  However, if there are
 user data structures shared between the parallel prerequisites, the
 user must do whatever is necessary to prevent race conditions.
 
+== Tasks with Arguments
+
+Prior to version 0.8.0, rake was only able to handle command line
+arguments of the form NAME=VALUE that were passed into Rake via the
+ENV hash.  Many folks had asked for some kind of simple command line
+arguments, perhaps using "--" to separate regular task names from
+argument values on the command line.  The problem is that there was no
+easy way to associate positional arguments on the command line with
+different tasks.  Suppose both tasks :a and :b expect a command line
+argument: does the first value go with :a?  What if :b is run first?
+Should it then get the first command line argument.
+
+Rake 0.8.0 solves this problem by explicitly passing values directly
+to the tasks that need them.  For example, if I had a release task
+that required a version number, I could say:
+
+   rake release[0.8.2]
+
+And the string "0.8.2" will be passed to the :release task.  Multiple
+arguments can be passed by separating them with a comma, for example:
+
+   rake name[john,doe]
+
+Just a few words of caution.  The rake task name and its arguments
+need to be a single command line argument to rake.  This generally
+means no spaces.  If spaces are needed, then the entire rake +
+argument string should be quoted.  Something like this:
+
+   rake "name[billy bob, smith]"
+
+(Quoting rules vary between operating systems and shells, so make sure
+you consult the proper docs for your OS/shell).
+
+=== Tasks that Expect Parameters
+
+Parameters are only given to tasks that are setup to expect them.  In
+order to handle named parameters, the task declaration syntax for
+tasks has been extended slightly.
+
+For example, a task that needs a first name and last name might be
+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
+:name in an array (:first_name and :last_name in the example).
+
+To access the values of the paramters, the block defining the task
+behaviour can now accept a second parameter:
+
+   task :name, [:first_name, :last_name] do |t, args|
+     puts "First name is #{args.first_name}"
+     puts "Last  name is #{args.last_name}"
+   end
+
+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.
+
+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
+where we specify default values for the first and last names:
+
+   task :name, [:first_name, :last_name] do |t, args|
+     args.with_defaults(:first_name => "John", :last_name => "Dough")
+     puts "First name is #{args.first_name}"
+     puts "Last  name is #{args.last_name}"
+   end
+
+=== Tasks that Expect Parameters and Have Prerequisites
+
+Tasks that use parameters have a slightly different format for
+prerequisites.  Use the arrow notation to indicate the prerequisites
+for tasks with arguments.  For example:
+
+   task :name, [:first_name, :last_name] => [:pre_name] do |t, args|
+     args.with_defaults(:first_name => "John", :last_name => "Dough")
+     puts "First name is #{args.first_name}"
+     puts "Last  name is #{args.last_name}"
+   end
+
+=== Deprecated Task Parameters Format
+
+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.
+
+== Accessing Task Programatically
+
+Sometimes it is useful to manipulate tasks programatically in a
+Rakefile. To find a task object, use the <tt>:[]</tt> operator on the
+<tt>Rake::Task</tt>.
+
+=== Programmatic Task Example
+
+For example, the following Rakefile defines two tasks.  The :doit task
+simply prints a simple "DONE" message.  The :dont class will lookup
+the doit class and remove (clear) all of its prerequisites and
+actions.
+
+   task :doit do
+     puts "DONE"
+   end
+
+   task :dont do
+     Rake::Task[:doit].clear
+   end        
+
+Running this example:
+
+  $ rake doit
+  (in /Users/jim/working/git/rake/x)
+  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
+should be used with cation.
+
 == Rules
 
 When a file is named as a prerequisite, but does not have a file task
@@ -372,8 +497,6 @@ Or give it a glob pattern:
 
    fl = FileList['*.rb']
 
-   
-
 == Odds and Ends
 
 === do/end verses { }