rake 0.4.11 → 13.4.2

data/doc/rakefile.rdoc

@@ -27,12 +27,12 @@ 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]
 
-<b>NOTE:</b> Although this syntax looks a little funky, it is legal
+*NOTE:* Although this syntax looks a little funky, it is legal
 Ruby.  We are constructing a hash where the key is :name and the value
 for that key is the list of prerequisites.  It is equivalent to the
 following ...
@@ -41,13 +41,27 @@ following ...
   hash[:name] = [:prereq1, :prereq2]
   task(hash)
 
+You can also use strings for task names and prerequisites, rake doesn't care.
+This is the same task definition:
+
+  task 'name' => %w[prereq1 prereq2]
+
+As is this:
+
+  task name: %w[prereq1 prereq2]
+
+We'll prefer this style for regular tasks with prerequisites throughout the
+rest of the document.  Using an array of strings for the prerequisites means
+you will need to make fewer changes if you need to move tasks into namespaces
+or perform other refactorings.
+
 === Tasks with Actions
 
 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|
+  task name: [:prereq1, :prereq2] do |t|
     # actions (may reference t)
   end
 
@@ -62,8 +76,8 @@ For example, the following is equivalent to the single task
 specification given above.
 
   task :name
-  task :name => [:prereq1]
-  task :name => [:prereq2]
+  task name: :prereq1
+  task name: %w[prereq2]
   task :name do |t|
     # actions
   end
@@ -79,8 +93,8 @@ method).  In addition, file tasks are usually named with a string
 rather than a symbol.
 
 The following file task creates a executable program (named +prog+)
-given two object files name <tt>a.o</tt> and <tt>b.o</tt>.  The tasks
-for creating <tt>a.o</tt> and <tt>b.o</tt> are not shown.
+given two object files named +a.o+ and +b.o+.  The tasks
+for creating +a.o+ and +b.o+ are not shown.
 
   file "prog" => ["a.o", "b.o"] do |t|
     sh "cc -o #{t.name} #{t.prerequisites.join(' ')}"
@@ -97,9 +111,9 @@ that creates the directory.  For example, the following declaration
 
 is equivalent to ...
 
-  file "testdata"              do |t| mkdir t.name end
-  file "testdata/examples"     do |t| mkdir t.name end
-  file "testdata/examples/doc" do |t| mkdir t.name end
+  file "testdata" do |t| mkdir t.name end
+  file "testdata/examples" => ["testdata"] do |t| mkdir t.name end
+  file "testdata/examples/doc" => ["testdata/examples"] do |t| mkdir t.name end
 
 The +directory+ method does not accept prerequisites or actions, but
 both prerequisites and actions can be added later.  For example ...
@@ -110,6 +124,189 @@ 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: %w[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 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 prerequisites 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.
+
+== 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 name +
+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 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 parameters, 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.
+
+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
+
+=== Tasks that take Variable-length Parameters
+
+Tasks that need to handle a list of values as a parameter can use the
+extras method of the args variable.  This allows for tasks that can
+loop over a variable number of values, and its compatible with named
+parameters as well:
+
+   task :email, [:message] do |t, args|
+     mail = Mail.new(args.message)
+     recipients = args.extras
+     recipients.each do |target|
+       mail.send_to(target)
+     end
+   end
+
+There is also the convenience method to_a that returns all parameters
+in the sequential order they were given, including those associated
+with named parameters.
+
+=== 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.  The older format may be dropped in future
+versions of rake.
+
+== Accessing Task Programmatically
+
+Sometimes it is useful to manipulate tasks programmatically in a
+Rakefile. To find a task object use Rake::Task.[].
+
+=== 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 caution.
+
 == Rules
 
 When a file is named as a prerequisite, but does not have a file task
@@ -128,8 +325,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
@@ -147,22 +344,68 @@ 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
+*NOTE:* Because of a _quirk_ in Ruby syntax, parenthesis are
 required on *rule* when the first argument is a regular expression.
 
 The following rule might be used for Java files ...
 
-  rule '.java' => [
+  rule '.class' => [
     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
+*NOTE:* +java_compile+ is a hypothetical method that invokes the
 java compiler.
 
+=== Implicit File Tasks
+
+When a task is not defined but a file with that name exists, Rake
+automatically creates an implicit file task for it. For example:
+
+  $ rake hello_world       # Error: task not found
+  $ touch hello_world      # Create a file with the same name
+  $ rake hello_world       # Now succeeds automatically
+
+Use the <tt>--rules</tt> command line option to trace how rules are
+resolved when searching for tasks; note that creation of implicit file
+tasks is not traced.
+
+== 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 makes 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 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.
+
+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
@@ -173,14 +416,14 @@ then you need to use the +desc+ command to describe the task.
 Example:
 
   desc "Create a distribution package"
-  task :package => [ ... ] do ... end
+  task package: %w[ ... ] 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
+  $ rake -T
   (in /home/.../rake)
   rake clean            # Remove any temporary products.
   rake clobber          # Remove any generated file.
@@ -198,19 +441,119 @@ 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 interfere with each other.
+
+For example:
+
+  namespace "main" do
+    task :build do
+      # Build the main program
+    end
+  end
+
+  namespace "samples" do
+    task :build do
+      # Build the sample programs
+    end
+  end
+
+  task build: %w[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.
+
+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 { }
+=== 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 {
@@ -228,7 +571,65 @@ This is the proper way to specify the task ...
     # Actions go here
   end
 
+== Rakefile Path
+
+When issuing the +rake+ command in a terminal, Rake will look
+for a Rakefile in the current directory. If a Rakefile  is not found,
+it will search parent directories until one is found.
+
+For example, if a Rakefile resides in the +project/+ directory,
+moving deeper into the project's directory tree will not have an adverse
+effect on rake tasks:
+
+  $ pwd
+  /home/user/project
+
+  $ cd lib/foo/bar
+  $ pwd
+  /home/user/project/lib/foo/bar
+
+  $ rake run_pwd
+  /home/user/project
+
+As far as rake is concerned, all tasks are run from the directory in
+which the Rakefile resides.
+
+=== Multiple Rake Files
+
+Not all tasks need to be included in a single Rakefile. Additional
+rake files (with the file extension "+.rake+") may be placed in
++rakelib+ directory located at the top level of a project (i.e.
+the same directory that contains the main +Rakefile+).
+
+Also, rails projects may include additional rake files in the
++lib/tasks+ directory.
+
+=== Clean and Clobber Tasks
+
+Through <tt>require 'rake/clean'</tt> Rake provides +clean+ and +clobber+
+tasks:
+
++clean+ ::
+  Clean up the project by deleting scratch files and backup files.  Add files
+  to the +CLEAN+ FileList to have the +clean+ target handle them.
+
++clobber+ ::
+  Clobber all generated and non-source files in a project.  The task depends
+  on +clean+, so all the +CLEAN+ files will be deleted as well as files in the
+  +CLOBBER+ FileList.  The intent of this task is to return a project to its
+  pristine, just unpacked state.
+
+You can add file names or glob patterns to both the +CLEAN+ and +CLOBBER+
+lists.
+
+=== Phony Task
+
+The phony task can be used as a dependency to allow file-based tasks to use
+non-file-based-tasks as prerequisites without forcing them to rebuild.  You
+can <tt>require 'rake/phony'</tt> to add the +phony+ task.
+
 ----
+
 == See
 
-* README -- Main documentation for Rake.
+* README.rdoc -- Main documentation for Rake.

data/doc/rational.rdoc

@@ -38,13 +38,13 @@ too much work.  And that was the end of that!
 ... Except I couldn't get the thought out of my head.  What exactly
 would be needed to make the about syntax work as a make file?  Hmmm, you
 would need to register the tasks, you need some way of specifying
-dependencies between tasks, and some way of kicking off the process. 
+dependencies between tasks, and some way of kicking off the process.
 Hey!  What if we did ... and fifteen minutes later I had a working
 prototype of Ruby make, complete with dependencies and actions.
 
 I showed the code to my coworker and we had a good laugh.  It was just
 about a page worth of code that reproduced an amazing amount of the
-functionality of make.  We were both truely stunned with the power of
+functionality of make.  We were both truly stunned with the power of
 Ruby.
 
 But it didn't do everything make did.  In particular, it didn't have
@@ -53,7 +53,7 @@ prerequisite files have a later timestamp).  Obviously THAT would be a
 pain to add and so Ruby Make would remain an interesting experiment.
 
 ... Except as I walked back to my desk, I started thinking about what
-file based dependecies would really need.  Rats!  I was hooked again,
+file based dependencies would really need.  Rats!  I was hooked again,
 and by adding a new class and two new methods, file/timestamp
 dependencies were implemented.
 
@@ -97,7 +97,7 @@ Here's another task with dependencies ...
    end
 
 Task :clobber depends upon task :clean, so :clean will be run before
-:clobber is executed. 
+:clobber is executed.
 
 Files are specified by using the "file" command.  It is similar to the
 task command, except that the task name represents a file, and the task
@@ -115,7 +115,7 @@ Here is a file based dependency that will compile "hello.cc" to
 
 I normally specify file tasks with string (rather than symbols).  Some
 file names can't be represented by symbols.  Plus it makes the
-distinction between them more clear to the casual reader.  
+distinction between them more clear to the casual reader.
 
 Currently writing a task for each and every file in the project would be
 tedious at best.  I envision a set of libraries to make this job
@@ -133,7 +133,7 @@ created for rake.
 That's it.  There's no documentation (other than whats in this
 message).  Does this sound interesting to anyone?  If so, I'll continue
 to clean it up and write it up and publish it on RAA.  Otherwise, I'll
-leave it as an interesting excerise and a tribute to the power of Ruby.
+leave it as an interesting exercise and a tribute to the power of Ruby.
 
 Why /might/ rake be interesting to Ruby programmers.  I don't know,
 perhaps ...

data/exe/rake

@@ -0,0 +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.
+#++
+
+require "rake"
+
+Rake.application.run