rake 0.4.8

data/TODO

@@ -0,0 +1,19 @@
+= Rake Project -- To Do List
+
+Send suggestions for this list to mailto:jim@weirichhouse.org or on
+the rake-devel@rubyforge.org mailing list.
+
+=== To Do
+* 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?
+* Java support utilities
+* Installation support utilities
+  * Check out installpkg.rb
+* Autogenerate Dependencies
+* Rules should apply to existing tasks if no actions are defined.
+* How to create multiple package tasks without task name collision?
+* Trap "ln -s" commands that fail and use "cp" instead (SMB mounted
+  drives have problems with "ln -s".
+
+(moved DONE list to CHANGES file)

data/bin/rake

@@ -0,0 +1,8 @@
+begin
+  require 'rake'
+rescue LoadError
+  require 'rubygems'
+  require_gem 'rake'
+end
+RakeApp.new.run
+

data/doc/example/Rakefile1

@@ -0,0 +1,38 @@
+# Example Rakefile -*- ruby -*-
+
+task :default => [:main]
+
+file "a.o" => ["a.c"] do |t|
+  src = t.name.sub(/\.o$/, '.c')
+  sh "gcc #{src} -c -o #{t.name}"
+end
+
+file "b.o" => ["b.c"] do |t|
+  src = t.name.sub(/\.o$/, '.c')
+  sh "gcc #{src} -c -o #{t.name}"
+end
+
+file "main.o" => ["main.c"] do |t|
+  src = t.name.sub(/\.o$/, '.c')
+  sh "gcc #{src} -c -o #{t.name}"
+end
+
+OBJFILES = ["a.o", "b.o", "main.o"]
+task :obj => OBJFILES
+
+file "main" => OBJFILES do |t|
+  sh "gcc -o #{t.name} main.o a.o b.o"
+end
+
+task :clean do
+  rm_f FileList['*.o']
+  Dir['*~'].each { |fn| rm_f fn }
+end
+
+task :clobber => [:clean] do
+  rm_f "main"
+end
+
+task :run => ["main"] do
+  sh "./main"
+end

data/doc/example/Rakefile2

@@ -0,0 +1,35 @@
+# Example Rakefile -*- ruby -*-
+# Using the power of Ruby
+
+task :default => [:main]
+
+def ext(fn, newext)
+  fn.sub(/\.[^.]+$/, newext)
+end
+
+SRCFILES = Dir['*.c']
+OBJFILES = SRCFILES.collect { |fn| ext(fn,".o") }
+
+OBJFILES.each do |objfile|
+  srcfile = ext(objfile, ".c")
+  file objfile => [srcfile] do |t|
+    sh "gcc #{srcfile} -c -o #{t.name}"
+  end
+end
+
+file "main" => OBJFILES do |t|
+  sh "gcc -o #{t.name} main.o a.o b.o"
+end
+
+task :clean do
+  rm_f FileList['*.o']
+  Dir['*~'].each { |fn| rm_f fn }
+end
+
+task :clobber => [:clean] do
+  rm_f "main"
+end
+
+task :run => ["main"] do
+  sh "./main"
+end

data/doc/example/a.c

@@ -0,0 +1,6 @@
+#include <stdio.h>
+
+void a()
+{
+    printf ("In function a\n");
+}

data/doc/example/b.c

@@ -0,0 +1,6 @@
+#include <stdio.h>
+
+void b()
+{
+    printf ("In function b\n");
+}

data/doc/example/main.c

@@ -0,0 +1,11 @@
+#include <stdio.h>
+
+extern void a();
+extern void b();
+
+int main ()
+{
+    a();
+    b();
+    return 0;
+}

data/doc/glossary.rdoc

@@ -0,0 +1,51 @@
+= Glossary
+
+[<b>action</b>]
+	Code to be executed in order to perform a task.  Actions in a
+	rakefile are specified in a code block (usually delimited by
+	+do+/+end+ pairs.
+
+[<b>execute</b>]
+	When a task is executed, all of its actions are performed, in
+	the order they were defined.  Note that unlike
+	<tt>invoke</tt>, <tt>execute</tt> always executes the actions
+	(without invoking or executing the prerequisites).
+
+[<b>file task</b> (FileTask)]
+	 A file task is a task whose purpose is to create a file
+	 (which has the same name as the task).  When invoked, a file
+	 task will only execute if one or more of the following
+	 conditions are true.
+
+         1. The associated file does not exist.
+	 2. A prerequisite has a later time stamp than the existing file.
+
+	 Because normal Tasks always have the current time as
+	 timestamp, a FileTask that has a normal Task prerequisite
+	 will always execute.
+
+[<b>invoke</b>]
+	When a task is invoked, first we check to see if it has been
+	invoked before.  if it has been, then nothing else is done.
+	If this is the first time its been invoked, then we invoke
+	each of its prerequisites.  Finally, we check to see if we
+	need to execute the actions of this task by calling
+	<tt>needed?</tt>.  Finally, if the task is needed, we execute
+	its actions.
+
+	NOTE: Currently prerequisites are invoked even if the task is
+	not needed.  This may change in the future.
+
+[<b>prerequisites</b>]
+	Every task has a set (possiblity empty) of prerequisites.  A
+	prerequisite P to Task T is itself a task that must be invoked
+	before Task T.  
+
+[<b>rule</b>]
+	A rule is a recipe for synthesizing a task when no task is
+	explicitly defined.  Rules generally synthesize file tasks.
+
+[<b>task</b> (Task)]
+	Basic unit of work in a rakefile.  A task has a name, a set of
+	prerequisites and a list of actions to be performed.
+

data/doc/proto_rake.rdoc

@@ -0,0 +1,127 @@
+= Original Prototype Rake
+
+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
+ 	fail "Too Many Target Names: #{args.keys.join(' ')}" if args.size > 1
+ 	fail "No Task Name Given" if args.size < 1
+ 	task_name = args.keys[0]
+ 	deps = args[task_name]
+       else
+ 	task_name = args
+ 	deps = []
+       end
+       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)
+     latest_prereq = @prerequisites.collect{|n| Task[n].timestamp}.max
+     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
+     while ! File.exist?("Rakefile")
+       Dir.chdir("..")
+       fail "No Rakefile found" if Dir.pwd == here
+       here = Dir.pwd
+     end
+     puts "(in #{Dir.pwd})"
+     load "./Rakefile"
+     ARGV.push("default") if ARGV.size == 0
+     ARGV.each { |task_name| Task[task_name].invoke }
+   rescue Exception => ex
+     puts "rake aborted ... #{ex.message}"
+     puts ex.backtrace.find {|str| str =~ /Rakefile/ } || ""
+   end    
+ end
+ 
+ if __FILE__ == $0 then
+   rake
+ end

data/doc/rakefile.rdoc

@@ -0,0 +1,234 @@
+= Rakefile Format
+
+First of all, there is no special format for a Rakefile.  A Rakefile
+contains executable Ruby code.  Anything legal in a ruby script is
+allowed in a Rakefile.
+
+Now that we understand there is no special syntax in a Rakefile, there
+are some conventions that are used in a Rakefile that are a little
+unusual in a typical Ruby program.  Since a Rakefile is tailored to
+specifying tasks and actions, the idioms used in a Rakefile are
+designed to support that.
+
+So, what goes into a Rakefile?
+
+== Tasks
+
+Tasks are the main unit of work in a Rakefile.  Tasks have a name
+(usually given as a symbol or a string), a list of prerequisites (more
+symbols or strings) and a list of actions (given as a block).
+
+=== Simple Tasks
+
+A task is declared by using the +task+ method.  +task+ takes a single
+parameter that is the name of the task.
+
+  task :name
+
+=== Tasks with Prerequisites
+
+Any prerequisites are given as a list (inclosed 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
+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 ...
+
+  hash = Hash.new
+  hash[:name] = [:prereq1, :prereq2]
+  task(hash)
+
+=== 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..
+
+  task :name => [:prereq1, :prereq2] do |t|
+    # actions (may reference t)
+  end
+
+=== Multiple Definitions
+
+A task may be specified more than once.  Each specification adds its
+prerequisites and actions to the existing definition.  This allows one
+part of a rakefile to specify the actions and a different rakefile
+(perhaps separately generated) to specify the dependencies.
+
+For example, the following is equivalent to the single task
+specification given above.
+
+  task :name
+  task :name => [:prereq1]
+  task :name => [:prereq2]
+  task :name do |t|
+    # actions
+  end
+
+== File Tasks
+
+Some tasks are designed to create a file from one or more other files.
+Tasks that generate these files may be skipped if the file already
+exists.  File tasks are used to specify file creation tasks.
+
+File tasks are declared using the +file+ method (instead of the +task+
+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.
+
+  file "prog" => ["a.o", "b.o"] do |t|
+    sh "cc -o #{t.name} #{t.prerequisites.join(' ')}"
+  end
+
+== Directory Tasks
+
+It is common to need to create directories upon demand.  The
++directory+ convenience method is a short-hand for creating a FileTask
+that creates the directory.  For example, the following declaration
+...
+
+  directory "testdata/examples/doc"
+
+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
+
+The +directory+ method does not accept prerequisites or actions, but
+both prerequisites and actions can be added later.  For example ...
+
+  directory "testdata"
+  file "testdata" => ["otherdata"]
+  file "testdata" do
+    cp Dir["standard_data/*.data"], "testdata"
+  end
+
+== Rules
+
+When a file is named as a prerequisite, but does not have a file task
+defined for it, Rake will attempt to synthesize a task by looking at a
+list of rules supplied in the Rakefile.
+
+Suppose we were trying to invoke task "mycode.o", but no task is
+defined for it.  But the rakefile has a rule that look like this ...
+
+  rule '.o' => ['.c'] do |t|
+    sh "cc #{t.source} -c -o #{t.name}"
+  end
+
+This rule will synthesize any task that ends in ".o".  It has a
+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.
+
+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
+rules with actions that reference the source file.
+
+=== Advanced Rules
+
+Any regular expression may be used as the rule pattern.  Additionally,
+a proc may be used to calculate the name of the source file.  This
+allows for complex patterns and sources.
+
+The following rule is equivalent to the example above.
+
+  rule( /\.o$/ => [
+    proc {|task_name| task_name.sub(/\.[^.]+$/, '.c') }
+  ]) do |t|
+    sh "cc #{t.source} -c -o #{t.name}"
+  end    
+
+<b>NOTE:</b> 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' => [
+    proc { |tn| tn.sub(/\.class$/, '.java').sub(/^classes\//, 'src/') }
+  ] do |t|
+    java_compile(t.source, t.name)  
+  end
+
+<b>NOTE:</b> +java_compile+ is a hypothetical method that invokes the
+java compiler.
+
+== Comments
+
+Standard Ruby comments (beginning with "#") can be used anywhere it is
+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:
+
+  desc "Create a distribution package"
+  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.
+
+  traken$ rake -T
+  (in /home/.../rake)
+  rake clean            # Remove any temporary products.
+  rake clobber          # Remove any generated file.
+  rake clobber_rdoc     # Remove rdoc products
+  rake contrib_test     # Run tests for contrib_test
+  rake default          # Default Task
+  rake install          # Install the application
+  rake lines            # Count lines in the main rake file
+  rake rdoc             # Build the rdoc HTML Files
+  rake rerdoc           # Force a rebuild of the RDOC files
+  rake test             # Run tests
+  rake testall          # Run all test targets
+
+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.
+
+== Odds and Ends
+
+=== do/end verses { }
+
+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
+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.
+
+  # DON'T DO THIS!
+  file "prog" => object_files {
+    # Actions are expected here (but it doesn't work)!
+  }
+
+Because curly braces have a higher precedence than +do+/+end+, the
+block is associated with the +object_files+ method rather than the
++file+ method.
+
+This is the proper way to specify the task ...
+
+  # THIS IS FINE
+  file "prog" => object_files do
+    # Actions go here
+  end
+
+----
+== See
+
+* README -- Main documentation for Rake.