rake 0.4.8 → 0.7.3

data/doc/rakefile.rdoc

@@ -110,6 +110,46 @@ both prerequisites and actions can be added later.  For example ...
     cp Dir["standard_data/*.data"], "testdata"
   end
 
+== Tasks with Parallel Prerequisites
+
+Rake allows parallel execution of prerequisites using the following syntax:
+
+  multitask :copy_files => [:copy_src, :copy_doc, :copy_bin] do
+    puts "All Copies Complete"
+  end
+
+In this example, +copy_files+ is a normal rake task.  Its actions are
+executed whereever 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
+prerequisites, all of the primary/parallel prerequisites will wait
+until the common prerequisites have been run.
+
+For example, if the <tt>copy_<em>xxx</em></tt> tasks have the
+following prerequisites:
+
+  task :copy_src => [:prep_for_copy]
+  task :copy_bin => [:prep_for_copy]
+  task :copy_doc => [:prep_for_copy]
+
+Then the +prep_for_copy+ task is run before starting all the copies in
+parallel.  Once +prep_for_copy+ is complete, +copy_src+, +copy_bin+,
+and +copy_doc+ are all run in parallel.  Note that +prep_for_copy+ is
+run only once, even though it is referenced in multiple threads.
+
+=== Thread Safety
+
+The Rake internal data structures are thread-safe with respect
+to the multitask parallel execution, so there is no need for the user
+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.
+
 == Rules
 
 When a file is named as a prerequisite, but does not have a file task
@@ -128,8 +168,8 @@ prerequisite a source file with an extension of ".c" must exist.  If
 Rake is able to find a file named "mycode.c", it will automatically
 create a task that builds "mycode.o" from "mycode.c".
 
-Notice that the source file "mycode.c" must exist.  Rake does not
-(currently) try to do multi-level task synthesis.
+If the file "mycode.c" does not exist, rake will attempt
+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
@@ -163,6 +203,39 @@ The following rule might be used for Java files ...
 <b>NOTE:</b> +java_compile+ is a hypothetical method that invokes the
 java compiler.
 
+== Importing Dependencies
+
+Any ruby file (including other rakefiles) can be included with a
+standard Ruby +require+ command.  The rules and declarations in the
+required file are just added to the definitions already accumulated.
+
+Because the files are loaded _before_ the rake targets are evaluated,
+the loaded files must be "ready to go" when the rake command is
+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.
+
+=== Example:
+
+  require 'rake/loaders/makefile'
+
+  file ".depends.mf" => [SRC_LIST] do |t|
+    sh "makedepend -f- -- #{CFLAGS} -- #{t.prerequisites} > #{t.name}"
+  end
+
+  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
+loading.
+
 == Comments
 
 Standard Ruby comments (beginning with "#") can be used anywhere it is
@@ -170,7 +243,7 @@ legal in Ruby source code, including comments for tasks and rules.
 However, if you wish a task to be described using the "-T" switch,
 then you need to use the +desc+ command to describe the task.
 
-Example:
+=== Example:
 
   desc "Create a distribution package"
   task :package => [ ... ] do ... end
@@ -198,6 +271,109 @@ Only tasks with descriptions will be displayed with the "-T" switch.
 Use "-P" (or "--prereqs") to get a list of all tasks and their
 prerequisites.
 
+== Namespaces
+
+As projects grow (and along with it, the number of tasks), it is
+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
+each other.
+
+For example:
+
+  namespace "main"
+    task :build do
+      # Build the main program
+    end
+  end
+
+  namespace "samples" do
+    task :build do
+      # Build the sample programs
+    end
+  end
+
+  task :build => ["main:build", "samples:build"]
+
+Referencing a task in a separate namespace can be achieved by
+prefixing the task name with the namespace and a colon
+(e.g. "main:build" refers to the :build task in the +main+ namespace).
+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.  
+
+=== FileTasks
+
+File task names are not scoped by the namespace command.  Since the
+name of a file task is the name of an actual file in the file system,
+it makes little sense to include file task names in name space.
+Directory tasks (created by the +directory+ command) are a type of
+file task and are also not affected by namespaces.
+
+=== Name Resolution
+
+When looking up a task name, rake will start with the current
+namespace and attempt to find the name there.  If it fails to find a
+name in the current namespace, it will search the parent namespaces
+until a match is found (or an error occurs if there is no match).
+
+The "rake" namespace is a special implicit namespace that refers to
+the toplevel names.
+
+If a task name begins with a "^" character, the name resolution will
+start in the parent namespace.  Multiple "^" characters are allowed.
+
+Here is an example file with multiple :run tasks and how various names
+resolve in different locations.
+
+  task :run
+
+  namespace "one" do
+    task :run
+
+    namespace "two" do
+      task :run
+
+      # :run            => "one:two:run"
+      # "two:run"       => "one:two:run"
+      # "one:two:run"   => "one:two:run"
+      # "one:run"       => "one:run"
+      # "^run"          => "one:run"
+      # "^^run"         => "rake:run" (the top level task)
+      # "rake:run"      => "rake:run" (the top level task)
+    end
+
+    # :run       => "one:run"
+    # "two:run"  => "one:two:run"
+    # "^run"     => "rake:run"
+  end
+
+  # :run           => "rake:run"
+  # "one:run"      => "one:run"
+  # "one:two:run"  => "one:two:run"
+
+== FileLists
+
+FileLists are the way Rake manages lists of files.  You can treat a
+FileList as an array of strings for the most part, but FileLists
+support some additional operations.
+
+=== Creating a FileList
+
+Creating a file list is easy.  Just give it the list of file names:
+
+   fl = FileList['file1.rb', file2.rb']
+
+Or give it a glob pattern:
+
+   fl = FileList['*.rb']
+
+   
+
 == Odds and Ends
 
 === do/end verses { }
@@ -229,6 +405,7 @@ This is the proper way to specify the task ...
   end
 
 ----
+
 == See
 
 * README -- Main documentation for Rake.

data/doc/release_notes/rake-0.4.14.rdoc

@@ -0,0 +1,23 @@
+= Rake 0.4.14 Released
+
+== Changes
+
+Version 0.4.14 is a compatibility fix to allow Rake's test task to
+work under Ruby 1.8.2.  A change in the Test::Unit autorun feature
+prevented Rake from running any tests.  This release fixes the
+problem.
+
+Rake 0.4.14 is the recommended release for anyone using Ruby 1.8.2.
+
+== What is Rake
+
+Rake is a build tool similar to the make program in many ways.  But
+instead of cryptic make recipes, Rake uses standard Ruby code to
+declare tasks and dependencies.  You have the full power of a modern
+scripting language built right into your build tool.
+
+== Availability
+
+Home Page:: http://rake.rubyforge.org/
+Download::  http://rubyforge.org/project/showfiles.php?group_id=50
+

data/doc/release_notes/rake-0.4.15.rdoc

@@ -0,0 +1,35 @@
+= Rake 0.4.15 Released
+
+== Changes
+
+Version 0.4.15 is a bug fix update for the Ruby 1.8.2 compatibility
+changes.  This release includes:
+
+* Fixed a bug that prevented the TESTOPTS flag from working with the
+  revised for 1.8.2 test task.
+
+* Updated the docs on --trace to indicate that it also enables a full
+  backtrace on errors. 
+
+* Several fixes for new warnings generated.
+
+== Mini-Roadmap
+
+I will continue to issue Rake updates in the 0.4.xx series as new
+Ruby-1.8.2 issues become manifest.  Once the codebase stabilizes, I
+will release a 0.5.0 version incorporating all the changes.  If you
+are not using Ruby-1.8.2 and wish to avoid version churn, I recommend
+staying with a release prior to Rake-0.4.14.
+
+== What is Rake
+
+Rake is a build tool similar to the make program in many ways.  But
+instead of cryptic make recipes, Rake uses standard Ruby code to
+declare tasks and dependencies.  You have the full power of a modern
+scripting language built right into your build tool.
+
+== Availability
+
+Home Page:: http://rake.rubyforge.org/
+Download::  http://rubyforge.org/project/showfiles.php?group_id=50
+

data/doc/release_notes/rake-0.5.0.rdoc

@@ -0,0 +1,53 @@
+= Rake 0.5.0 Released
+
+It has been a long time in coming, but we finally have a new version
+of Rake available.  
+
+== Changes
+
+* Fixed bug where missing intermediate file dependencies could cause
+  an abort with --trace or --dry-run.  (Brian Candler)
+
+* Recursive rules are now supported (Tilman Sauerbeck).
+
+* Added tar.gz and tar.bz2 support to package task (Tilman Sauerbeck).
+
+* Added warning option for the Test Task (requested by Eric Hodel).
+
+* The jamis rdoc template is only used if it exists.
+
+* Added fix for Ruby 1.8.2 test/unit and rails problem.
+
+* Added contributed rake man file. (Jani Monoses)
+
+* Fixed documentation that was lacking the Rake module name (Tilman
+  Sauerbeck).
+
+== What is Rake
+
+Rake is a build tool similar to the make program in many ways.  But
+instead of cryptic make recipes, Rake uses standard Ruby code to
+declare tasks and dependencies.  You have the full power of a modern
+scripting language built right into your build tool.
+
+== Availability
+
+The easiest way to get and install rake is via RubyGems ...
+
+  gem install rake    (you may need root/admin privileges)
+
+Otherwise, you can get it from the more traditional places:
+
+Home Page:: http://rake.rubyforge.org/
+Download::  http://rubyforge.org/project/showfiles.php?group_id=50
+
+== Thanks
+
+Lots of people provided input to this release.  Thanks to Tilman
+Sauerbeck for numerous patches, documentation fixes and suggestions.
+And for also pushing me to get this release out.  Also, thanks to
+Brian Candler for the finding and fixing --trace/dry-run fix.  That
+was an obscure bug.  Also to Eric Hodel for some good suggestions.
+
+-- Jim Weirich
+

data/doc/release_notes/rake-0.5.3.rdoc

@@ -0,0 +1,78 @@
+= Rake 0.5.0 Released
+
+Although it has only been two weeks since the last release, we have
+enough updates to the Rake program to make it time for another
+release.
+
+== Changes
+
+Here are the changes for version 0.5.3 ...
+
+* FileLists have been extensively changed so that they mimic the
+  behavior of real arrays even more closely.  In particular,
+  operations on FileLists that return a new collection (e.g. collect,
+  reject) will now return a FileList rather than an array.  In
+  addition, several places where FileLists were not properly expanded
+  before use have been fixed.
+
+* A method (+ext+) to simplify the handling of file extensions was
+  added to String and to Array.
+
+* The 'testrb' script in test/unit tends to silently swallow syntax
+  errors in test suites.  Because of that, the default test loader is
+  now a rake-provided script.  You can still use 'testrb' by setting
+  the loader flag in the test task to :testrb.  (See the API documents
+  for TestTask for all the loader flag values).
+
+* FileUtil methods (e.g. cp, mv, install) are now declared to be
+  private.  This will cut down on the interference with user defined
+  methods of the same name.
+
+* Fixed the verbose flag in the TestTask so that the test code is
+  controlled by the flag.  Also shortened up some failure messages.
+  (Thanks to Tobias Luetke for the suggestion).
+
+* Rules will now properly detect a task that can generate a source
+  file.  Previously rules would only consider source files that were
+  already present.
+
+* Added an +import+ command that allows Rake to dynamically import
+  dependendencies into a running Rake session.  The +import+ command
+  can run tasks to update the dependency file before loading them.
+  Dependency files can be in rake or make format, allowing rake to
+  work with tools designed to generate dependencies for make.
+
+== What is Rake
+
+Rake is a build tool similar to the make program in many ways.  But
+instead of cryptic make recipes, Rake uses standard Ruby code to
+declare tasks and dependencies.  You have the full power of a modern
+scripting language built right into your build tool.
+
+== Availability
+
+The easiest way to get and install rake is via RubyGems ...
+
+  gem install rake    (you may need root/admin privileges)
+
+Otherwise, you can get it from the more traditional places:
+
+Home Page:: http://rake.rubyforge.org/
+Download::  http://rubyforge.org/project/showfiles.php?group_id=50
+
+== Thanks
+
+As usual, it was input from users that drove a alot of these changes.
+Thanks to ...
+
+* Brian Gernhardt for the rules fix (especially for the patience to
+  explain the problem to me until I got what he was talking about).
+* Stefan Lang for pointing out problems in the dark corners of the
+  FileList implementation.
+* Alexey Verkhovsky pointing out the silently swallows syntax errors
+  in tests.
+* Tobias Luetke for beautifying the test task output.
+* Sam Roberts for some of the ideas behind dependency loading.
+
+-- Jim Weirich
+

data/doc/release_notes/rake-0.5.4.rdoc

@@ -0,0 +1,46 @@
+= Rake 0.5.4 Released
+
+Time for some minor bug fixes and small enhancements
+
+== Changes
+
+Here are the changes for version 0.5.3 ...
+
+* Added double quotes to the test runner.  This allows the location of
+  the tests (and runner) to be in a directory path that contains
+  spaces (e.g. "C:/Program Files/ruby/bin").
+
+* Added .svn to default ignore list.  Now subversion project metadata
+  is automatically ignored by Rake's FileList.
+
+* Updated FileList#include to support nested arrays and filelists.
+  FileLists are flat lists of file names.  Using a FileList in an
+  include will flatten out the nested file names.
+
+== What is Rake
+
+Rake is a build tool similar to the make program in many ways.  But
+instead of cryptic make recipes, Rake uses standard Ruby code to
+declare tasks and dependencies.  You have the full power of a modern
+scripting language built right into your build tool.
+
+== Availability
+
+The easiest way to get and install rake is via RubyGems ...
+
+  gem install rake    (you may need root/admin privileges)
+
+Otherwise, you can get it from the more traditional places:
+
+Home Page:: http://rake.rubyforge.org/
+Download::  http://rubyforge.org/project/showfiles.php?group_id=50
+
+== Thanks
+
+As usual, it was input from users that drove a alot of these changes.
+Thanks to ...
+
+* Tilman Sauerbeck for the nested FileList suggestion.
+* Josh Knowles for pointing out the spaces in directory name problem.
+
+-- Jim Weirich

data/doc/release_notes/rake-0.6.0.rdoc

@@ -0,0 +1,141 @@
+= Rake 0.6.0 Released
+
+Its time for some long requested enhancements and lots of bug fixes
+... And a whole new web page.
+
+== New Web Page
+
+The primary documentation for rake has moved from the RubyForge based
+wiki to its own Hieraki based web site.  Constant spam on the wiki
+made it a difficult to keep clean.  The new site will be easier to
+update and organize.
+
+Check out the new documentation at: http://docs.rubyrake.org
+
+We will be adding new documentation to the site as time goes on.
+
+In addition to the new docs page, make sure you check out Martin
+Fowlers article on rake at http://martinfowler.com/articles/rake.html
+
+== Changes
+
+=== New Features
+
+* Multiple prerequisites on Rake rules now allowed.  However, keep the
+  following in mind:
+
+  1. All the prerequisites of a rule must be available before a rule
+     is triggered, where "enabled" means (a) an existing file, (b) a
+     defined rule, or (c) another rule which also must be
+     trigger-able.
+  2. Rules are checked in order of definition, so it is important to
+     order your rules properly.  If a file can be created by two
+     different rules, put the more specific rule first (otherwise the
+     more general rule will trigger first and the specific one will
+     never be triggered).
+  3. The <tt>source</tt> method now returns the name of the first
+     prerequisite listed in the rule.  <tt>sources</tt> returns the
+     names of all the rule prerequisites, ordered as they are defined
+     in the rule.  If the task has other prerequisites not defined in
+     the rule (but defined in an explicit task definition), then they
+     will _not_ be included in the sources list.
+
+* FileLists may now use the egrep command.  This popular enhancement
+  is now a core part of the FileList object.  If you want to get a
+  list of all your to-dos, fixmes and TBD comments, add the following
+  to your Rakefile.
+
+    desc "Look for TODO and FIXME tags in the code"
+    task :todo do
+      FileList['**/*.rb'].egrep /#.*(FIXME|TODO|TBD)/
+    end
+
+* The <tt>investigation</tt> method was added to task object to dump
+  out some important values.  This makes it a bit easier to debug Rake
+  tasks.
+
+  For example, if you are having problems with a particular task, just
+  print it out:
+
+    task :huh do
+      puts Rake::Task['huh'].investigation
+    end
+
+* The Rake::TestTask class now supports a "ruby_opts" option to pass
+  arbitrary ruby options to a test subprocess.
+
+=== Some Incompatibilities
+
+* When using the <tt>ruby</tt> command to start a Ruby subprocess, the
+  Ruby interpreter that is currently running rake is used by default.
+  This makes it easier to use rake in an environment with multiple
+  ruby installation.  (Previously, the first ruby command found in the
+  PATH was used).
+
+  If you wish to chose a different Ruby interpreter, you can
+  explicitly choose the interpreter via the <tt>sh</tt> command.
+
+* The major rake classes (Task, FileTask, FileCreationTask, RakeApp)
+  have been moved out of the toplevel scope and are now accessible as
+  Rake::Task, Rake::FileTask, Rake::FileCreationTask and
+  Rake::Application.  If your Rakefile
+  directly references any one of these tasks, you may:
+
+  1. Update your Rakefile to use the new classnames
+  2. Use the --classic-namespace option on the rake command to get the
+     old behavior,
+  3. Add <code>require 'rake/classic_namespace'</code> to the
+     Rakefile to get the old behavior.
+
+  <tt>rake</tt> will print a rather annoying warning whenever a
+  deprecated class name is referenced without enabling classic
+  namespace.
+
+=== Bug Fixes
+
+* Several unit tests and functional tests were fixed to run better
+  under windows.
+
+* Directory tasks are now a specialized version of a File task.  A
+  directory task will only be triggered if it doesn't exist.  It will
+  not be triggered if it is out of date w.r.t. any of its
+  prerequisites.
+
+* Fixed a bug in the Rake::GemPackageTask class so that the gem now
+  properly contains the platform name.
+
+* Fixed a bug where a prerequisite on a <tt>file</tt> task would cause
+  an exception if the prerequisite did not exist.
+
+== What is Rake
+
+Rake is a build tool similar to the make program in many ways.  But
+instead of cryptic make recipes, Rake uses standard Ruby code to
+declare tasks and dependencies.  You have the full power of a modern
+scripting language built right into your build tool.
+
+== Availability
+
+The easiest way to get and install rake is via RubyGems ...
+
+  gem install rake    (you may need root/admin privileges)
+
+Otherwise, you can get it from the more traditional places:
+
+Home Page:: http://rake.rubyforge.org/
+Download::  http://rubyforge.org/project/showfiles.php?group_id=50
+
+== Thanks
+
+As usual, it was input from users that drove a alot of these changes.
+The following people either contributed patches, made suggestions or
+made otherwise helpful comments.  Thanks to ...
+
+* Greg Fast (better ruby_opt test options)
+* Kelly Felkins (requested by better namespace support)
+* Martin Fowler (suggested Task.investigation)
+* Stuart Jansen (send initial patch for multiple prerequisites).
+* Masao Mutch (better support for non-ruby Gem platforms)
+* Philipp Neubeck (patch for file task exception fix)
+
+-- Jim Weirich